glance_tt(1M)glance_tt(1M)NAME
glance_tt, glance_tt+ - feed metrics from the GlancePlus TRANSACTION
class to the HP-UX Workload Manager
SYNOPSIS
interval] {metric | metric_expr} app_name trans_name [trans_user]
interval] wlm_metric app_name trans_name
{ | trans_user, trans_user, ...}
DESCRIPTION
The and data collectors provide a method by which the values derived
from metrics in the GlancePlus TRANSACTION class can be sent to the HP-
UX Workload Manager (WLM) daemon, for use in the definition of system
service-level objectives (SLOs). It does so by running the GlancePlus
Adviser with an autogenerated syntax file to periodically report on
stdout the value specified by the metric, metric_expr, or wlm_metric
parameters. This value is then picked up by which passes it to for
processing.
GlancePlus collects TRANSACTION class metrics for applications that use
the Application Response Measurement (ARM) interface to report per-
transaction performance data. Transaction instances are identified by
the app_name, trans_name, and trans_user parameters, and only data from
these instances are used in the reported value. Applications use the
ARM interface at runtime to define the values of these strings corre‐
sponding to the applications' transaction instances. Because of this,
the app_name parameter can be different from the application names
defined in GlancePlus or HP-UX WLM, and the trans_user parameter need
not correspond to valid HP-UX user names.
must be running for GlancePlus to collect transactions.
To determine the valid values of app_name, trans_name, and trans_user
for a particular application, start the application and invoke one of
the following GlancePlus tools:
· gpm(1), GlancePlus graphical interface
See the Transaction Tracking screen
· glance(1), GlancePlus text-based interface
Use the options to begin with the Transaction Tracking screen
· glance adviser, glance(1) with option
Run the following adviser script to list the data:
% /opt/perf/bin/glance -j 10 -adviser_only -syntax \
/opt/perf/examples/adviser/arm
For more information on the ARM interface supplied with GlancePlus, see
arm(3).
When the trans_user parameter is not specified to the collector reports
values that only include an application's completed transaction
instances with no defined application user name. When trans_user is
specified, only the application's transaction instances with a matching
application user name are included in the values reported.
The metric_expr parameter to can be any valid Adviser expression, per‐
mitting GlancePlus metrics from the GLOBAL and TABLE classes to be com‐
bined with TRANSACTION class metrics. See the "METRICS" section for a
more detailed discussion of Adviser expressions.
The collector simulates and reports the values of several GlancePlus
TRANSACTION class metrics for completed transaction instances whose
defined application user name matches one of the trans_user parameters.
If is specified instead of multiple trans_users, the values reported
will include application transaction instances for all valid applica‐
tion user names, plus undefined. The values are said to be simulated
because GlancePlus does not directly report metrics that include a sub‐
set of all the valid user names. Instead, derives these metrics from
calculations on their basic components that GlancePlus does supply.
See the "WLM_TT Metric Class" subsection of the "METRICS" section for
further details on these calculations.
Choosing the right GlancePlus data collector
HP-UX WLM provides several GlancePlus data collectors, each optimized
for collecting different classes of metrics. If metric or metric_expr
does not contain a TRANSACTION class metric, then one of the other
GlancePlus data collectors should be used instead of In general, the
data collector that requires the least number of parameters to provide
the desired metric value will be the one that provides that metric most
efficiently. See glance_gbl(1M) for a discussion of the other available
GlancePlus data collectors.
Options
Specifies the interval, in seconds, over which data is collected and a
metric value is reported. If not provided, the default
value of 30 is used. This adjusts the value of the
TT_INTERVAL metric.
Parameters
metric Specifies the GlancePlus TRANSACTION class metric to
collect and report. For a complete list of all TRANSAC‐
TION class metrics, see the "Performance Metrics" sec‐
tion in the gpm(1) online help. Metrics that have a
string value are not valid.
wlm_metric Specifies the WLM_TT class metric to calculate and
report. See the "WLM_TT Metric Class" subsection of the
"METRICS" section for a complete list of available met‐
rics and their definitions.
metric_expr Specifies an Adviser expression combining one or more
metrics from the GlancePlus TRANSACTION, GLOBAL, or TA‐
BLE classes. For a complete list of all metrics in
these classes, see the "Performance Metrics" section in
the gpm(1) online help. The expression can be suffixed
with an optional formatting string of the form where
width indicates the maximum number of characters in the
value, and decimals indicates the floating-point preci‐
sion. The entire expression, including the optional
formatting string, must be enclosed in quotes. See the
"Expressions" and "Format" subsections of the "METRICS"
section for further discussion.
app_name Specifies the name of the application providing the
transaction data to be collected. The application pro‐
vides this name to the ARM interface at runtime, and it
is displayed in the "App Name" column of the GlancePlus
Transaction Tracker window. The name is case-sensitive,
and app_name must be quoted if the name contains spaces.
trans_name Specifies the name of the transaction of interest within
the application specified by app_name. The application
provides this name to the ARM interface at runtime, and
it is displayed in the "Tran Name" column of the Glance‐
Plus Transaction Tracker window. The name is case-sen‐
sitive, and trans_name must be quoted if the name con‐
tains spaces.
trans_user Specifies the application user name used in selecting
transaction instances to include in metric collection.
The application optionally provides this name to the ARM
interface at runtime, and it is displayed in the "User
Name" column of the GlancePlus Transaction Tracker win‐
dow. If trans_user is not specified to the metric value
reported will only include transaction instances gener‐
ated by undefined application users. If one or more
comma-separated trans_users are specified, then the met‐
ric value reported will only include transactions gener‐
ated by any of those application users. The name is
case-sensitive, and trans_user must be quoted if the
name contains spaces.
METRICS
Metrics are used by WLM in the construction of service-level objectives
(SLOs). Specifically, they are used in:
· statements, telling WLM how well a workload is performing
· statements, assigning CPU shares
· and statements, enabling SLOs based on the metric's value
GlancePlus provides a large number of metrics that are suitable for use
with WLM. and each provide access to a subset of those metrics.
TRANSACTION metric class
Listed here are only a few of the applicable metrics from the Glance‐
Plus TRANSACTION metric class. For a complete listing of GlancePlus
metrics and important usage notes, please consult the "The Adviser" and
"Performance Metrics" sections of the gpm(1) online help.
The number of completed transactions during the last interval for this
transaction.
NOTE: will not deliver this metric (nor any other met‐
ric) unless one or more of the named transactions com‐
pletes in the interval--that is, unless TT_COUNT is
greater than zero. Hence, will never receive a TT_COUNT
value of zero (0) from
The number of completed transactions that exceeded the threshold time
set in the GlancePlus ttd.conf file. This SLO should
not be confused with SLOs defined in the WLM configura‐
tion file. For more information on ttd.conf and Glance‐
Plus SLOs, see ttd.conf(4).
The average transaction time, in seconds, during the last interval for
this transaction.
WLM_TT metric class
The collector only accepts metrics from the WLM_TT metric class. This
class is implemented within the collector and provides metric values
that are analogous to those provided in the GlancePlus TRANSACTION
class. The difference is that data from transactions generated by mul‐
tiple application users is combined into a single metric in the WLM_TT
metric class.
The following is a list of available metrics in the WLM_TT class.
While all of the metrics described here are available for collection, a
number of them may not be especially useful measures for WLM. In par‐
ticular, cumulative (*_CUM) and per-transaction resource
(*_resource_PER_TRAN) metrics are likely of use in only limited situa‐
tions.
In the formulas, the sum() pseudo function aggregates the metric over
all transaction instances matching app_name, trans_name, and any of the
provided trans_user names.
Average transaction completion time, in seconds, over the last inter‐
val, and
since the last counter reset respectively. This metric
is calculated with the following formulas.
sum(TT_WALL_TIME) / sum(TT_COUNT)sum(TT_WALL_TIME_CUM) / sum(TT_COUNT_CUM)
The percent of transactions that exceeded the GlancePlus SLO threshold
defined in ttd.conf.
100 * sum(TT_SLO_COUNT) / sum(TT_COUNT)
100 * sum(TT_SLO_COUNT_CUM) / sum(TT_COUNT_CUM)
Various per-transaction resource stats. The WLM_TT class supports
all the same _PER_TRAN and _PER_TRAN_CUM metrics as the
GlancePlus TRANSACTION class.
sum(TT_*_PER_TRAN x TT_COUNT) / sum(TT_COUNT)
sum(TT_*_PER_TRAN_CUM x TT_COUNT_CUM) / sum(TT_COUNT_CUM)
NOTE: These per-transaction resource metrics require
transaction resource data collection to be enabled. For
information on how to do this, see the "Per-transaction
resource metrics" section below.
Other TRANSACTION class metrics not covered by the above, and explic‐
itly
excluding all metrics ending _PCT, _UTIL, and _RATE.
These metrics will be simply summed together.
sum(TT_*)
Per-transaction resource metrics
NOTE: Collection of per-transaction resource metrics incurs additional
measurement overhead. Enable only as required.
You can collect the TT_WALL_TIME_PER_TRAN and WLM_TT_WALL_TIME_PER_TRAN
metrics without enabling the collection of per-transaction resource
metrics.
To enable collection of per-transaction resource usage:
1. Modify the file /var/opt/perf/parm.
Edit this file to log transaction=resource data. For example, your
log line may look like the following after you add the transac‐
tion=resource portion:
log global application process dev=disk,lvm transaction=resource
By modifying the parm file, the setting will persist with each start
of the measurement agents.
2. Restart the measurement agents:
mwa restart
3. Restart all ARMed applications.
For more information regarding transaction tracking, consult the gpm(1)
online help, the document (available in a file starting with "tyt"
under a subdirectory of /opt/perf/paperdocs/arm/), and midaemon(1) and
related manpages.
Expressions
You can combine numeric metrics and constants into an arithmetic
expression for use as the metric_expr parameter to A full discussion of
Adviser expression syntax can be found in the gpm(1) online help, in
the section "The Adviser". Some example expressions, using GLOBAL met‐
rics:
"GBL_CPU_TOTAL_UTIL - GBL_CPU_USER_MODE_UTIL"
"( 100 - GBL_CPU_TOTAL_UTIL ) / 100.0"
When specifying a metric_expr, the expression must be enclosed in
quotes to ensure it is passed as a single argument.
(For information on metrics that are used, but not described, in this
manpage, see the file /opt/perf/paperdocs/gp/C/metrics.txt.)
Format
Adviser expressions, especially those involving division of integer
quantities, can be formatted to force a well-defined floating-point
precision. Without formatting, undesired truncation and/or rounding
may occur.
When providing a format specification with a metric_expr, use parenthe‐
ses around the expression to clearly indicate that the entire expres‐
sion is to be formatted.
"(expression)|width|decimals"
MODIFYING YOUR C PROGRAM TO SEND ARM TRANSACTION DATA
To modify your C program to generate ARM transaction data for use by
WLM:
1. Add ARM API calls to your program
Modify your program to use the ARM API calls described in the arm(3)
man page. To use these calls, you must reference the include file
/opt/perf/include/arm.h.
Be sure to:
· Register app_name with ARM through the arm_init API call
· Mark the start and stop of each transaction in which you are
interested
2. Compile your program
Compile your program, specifying the locations for the ARM header
file and library--being sure to link against the ARM library.
For HP-UX 11i v1 (B.11.11), the compile/link line is:
% /opt/ansic/bin/cc -Ae prog.c -I /opt/perf/include \
-L /opt/perf/lib -larm
The -Ae option ensures you compile using the extended ANSI mode.
For HP-UX 11i v2 (B.11.23) on IA64 platforms, the compile/link line
for 32-bit IA ARMed programs is:
% /opt/ansic/bin/cc -Ae prog.c -I /opt/perf/include \
-L /opt/perf/lib/hpux32 -larm
For HP-UX 11i v2 (B.11.23) and HP-UX 11i v3 (B.11.31) on IA64 plat‐
forms, the compile/link line for 64-bit IA ARMed programs is:
% /opt/ansic/bin/cc -Ae +DD64 prog.c -I /opt/perf/include \
-L /opt/perf/lib/hpux64 -larm
3. Ensure that ttd is configured and running
4. Start the program you instrumented with ARM calls
The start and stop times for your transactions will now be made
available through HP's ARM implementation. For more information, see
ttd(1) and midaemon(1).
5. Edit your WLM configuration to pick up the transaction data
To extract ARM data (from HP's ARM implementation) and forward it to
WLM, use wlmrcvdc with the glance_tt command in the configuration
file:
tune metricA {
coll_argv = wlmrcvdc glance_tt
metric # Metric you choose to monitor
app_name # Application registered with ARM
trans_name [trans_user]; # Transaction in the
# application to get the metric for, along
# with an application user
}
The metric used above is typically from the TRANSACTION metric class
(TT_*), but can also be an expression that combines a transaction
metric with metrics from the GLOBAL (GBL_*) and TABLE (TBL_*) metric
classes.
You can fine-tune transaction tracking in the /var/opt/perf/ttd.conf
file if desired. This file has an entry (tran=*) that enables all
transactions to be tracked. However, you may want to fine-tune what
is tracked. For more information, see the ttd(1) manpage and the
ttd.conf file or the ttd.conf(4) manpage.
6. Activate your WLM configuration:
configfile
EXAMPLES
WLM is configured to collect metrics provided by and by creating a
structure for the metric and setting the tunable as shown in the proto‐
type below.
tune metric {
coll_argv = wlmrcvdc
glance_tt metric
app_name trans_name trans_user;
}
When loaded by WLM, this structure causes to start as the source of
values for the metric. In turn, will start to do the work of collecting
the metric values from GlancePlus. With this structure defined, the
metric can then be used in and statements throughout the WLM configura‐
tion file.
The following examples show some ways of using metrics collected with
and
Example #1
This example shows the collection of average wall time for a frequently
occurring transaction in a busy application. The application is regis‐
tered using the name "Transaction Application". The transaction being
measured is named "Insert". The application does not register user
names.
# Keep average response time within acceptable limit.
slo tran_slo {
pri = 5;
mincpu = 10;
maxcpu = 75;
entity = PRM group tran_grp;
goal = metric tran_time < 3.0;
}
# Report average response time for Insert transactions.
tune tran_time {
coll_argv = wlmrcvdc
glance_tt TT_WALL_TIME_PER_TRAN
"Transaction Application"
Insert;
}
Example #2
This is essentially the same as the previous example, except that here,
the application does register a user name. In this example, there are
instances of the application being run by user "finance" and other
instances registered to user "purchase". In order to collect a com‐
bined metric, must be used.
# Keep average response time within acceptable limit.
slo tran_slo {
pri = 5;
mincpu = 10;
maxcpu = 75;
entity = PRM group tran_grp;
goal = metric tran_time < 3.0;
}
# Report average response time for Insert transactions
# by finance and purchasing users.
tune tran_time {
coll_argv = wlmrcvdc
glance_tt+ WLM_TT_WALL_TIME_PER_TRAN
"Transaction Application"
Insert "finance,purchase";
}
calculates the metric by performing the following calculation on data
collected from GlancePlus in each interval with transaction activity:
( ( TT_WALL_TIME[finance] + TT_WALL_TIME[purchase] ) ÷
( TT_COUNT[finance] + TT_COUNT[purchase] ) )
Example #3
This example demonstrates use of an Adviser expression.
# Hold to 15% or below the percentage of sales Update
# transactions that exceed the ttd.conf threshold.
slo tran_slo {
pri = 5;
mincpu = 10;
maxcpu = 75;
entity = PRM group tran_grp;
goal = metric sales_violations < 15;
}
# Report percentage of Update transactions by sales
# that take longer than the ttd.conf threshold.
tune sales_violations {
coll_argv = wlmrcvdc
glance_tt
"((TT_SLO_COUNT * 100) / TT_COUNT)|6|2"
"Transaction Application"
Update sales;
}
EXTERNAL INFLUENCES
Environment Variables
The value of if set and not null, is displayed in certain diagnostic
messages. If it is not set or is null, the word is substituted.
DIAGNOSTICS
and write invalid argument, usage, and unexpected termination error
messages on stderr if the terminal is available; otherwise such error
messages are directed to syslogd (using the facility). Notification of
unexpected death of the Adviser will include the value of if available.
Error messages from the Adviser are written on stderr. When invoked
from stderr is directed to /dev/null; hence, these diagnostic messages
are discarded. However, using the tunable in your WLM configuration,
you can redirect stderr to a location of your choosing. (See "NOTES"
for additional troubleshooting tips.)
NOTES
If transactions are not appearing as expected, ensure that is config‐
ured and running.
and do not report a metric value for intervals where no transactions
complete.
and are located in /opt/wlm/lbin/coll/. Under normal operating condi‐
tions, it should not be necessary to run these data collectors interac‐
tively. However, during initial setup, or when debugging configuration
problems, it may be helpful to invoke them from an interactive shell to
test that the proper metric values are being reported.
While some metrics are normalized, others may be in proportion to
pseudo constants such as These constants are generally static, but it
is possible for them to be changed. Be sure to take this into account
when specifying a metric. For metrics that vary with "constant" values
(such as TT_COUNT, being in proportion to TT_INTERVAL), it may be nec‐
essary to form an expression that normalizes the metric to a rate or
percentage. This can be especially important if the interval is ever
adjusted or WLM operates in an environment where system configurations
may vary. For example, to extrapolate the number of transactions com‐
pleted per second, normalized to a 30-second block, use the following
Adviser expression:
"(30 * TT_COUNT / TT_INTERVAL)|8|2"
WARNINGS
metric_exprs that may evaluate to a floating-point value should specify
a precision to avoid truncation and/or rounding. This is especially
important in cases involving division of an integer.
Specifying an unregistered application name, transaction name, or user
name will not result in an error, nor will it produce any data.
TRANSACTION metrics are only available if the transaction tracking reg‐
istration daemon (ttd) is properly configured and running.
DEPENDENCIES
and require the optional HP product, GlancePlus.
AUTHOR
was developed by HP.
FEEDBACK
If you would like to comment on the current HP-UX WLM functionality or
make suggestions for future releases, please send email to:
wlmfeedback@rsn.hp.com
FILES
The default log file for syslogd's
facility. Check here for possible diag‐
nostics.
Configures logging of transaction metrics.
Configuration file for the transaction tracking registration daemon
(ttd). It enables the registration of
transactions by name.
SEE ALSOglance(1), ttd(1), glance_app(1M), glance_gbl(1M), glance_prm(1M),
glance_prm_by_vg(1M), wlmrcvdc(1M), arm(3), ttd.conf(4), wlmconf(4),
wlm(5)
HP-UX Workload Manager User's Guide (/opt/wlm/share/doc/WLMug.pdf)
HP-UX Workload Manager homepage (http://www.hp.com/go/wlm)
GlancePlus (gpm) online help
Optional Software Required glance_tt(1M)
