topasrec Command

Purpose

The topasrec command generates binary recording of the local system metrics, CEC (Central Electronic Complex) metrics, and Cluster metrics.

Note: The xmwlm and xmtrend utilities are obsolete and are replaced by topasrec command.

Syntax

Local binary recording:

topasrec -L [ -c sample_count ] [ -o < output_filename >] [ -s seconds ] [ -t trace level ]

Local Azizo recording:

topasrec -L -O type=azizo

CEC recording:

topasrec -C [ -c sample_count ] [ -o < output_filename > ] [ -s seconds ] [ -O xmtopas=<hostname> ]

Cluster recording:

topasrec -G [ -c sample_count ] [ -o < output_filename > ] [ -s seconds ] [ -O xmtopas=<hostname> ]

List running recording:

topasrec -l

Description

Note:
  1. You cannot run the topasrec command inside a workload partition (WPAR).
  2. The CEC or cluster recording re-spawns after the partition migration or hibernation is complete. The active recording file is renamed to <current_file_name>.mig.<HH>.<MM>.<SS> after migration of the partition, and <current_file_name>.hib.<HH>.<MM>.<SS> after hibernation of the partition.

The topasrec command records the local system data, the cross-partition data (CEC statistics), and the cluster data in binary format.

When you run the topasrec command for a CEC recording, the topasrec command collects a set of metrics from the AIX® partitions running on the same CEC. The topasrec command collects dedicated and shared partition data, and a set of aggregated values to provide an overview of the partition set on the same CEC.

The topasrec command finds metrics to be recorded from the /usr/lpp/perfagent/daily.cf file, and you should not alter the daily.cf file. Altering the daily.cf file affects the following recording files:
  1. Persistent/nonpersistent local recordings
  2. WLE Recording
  3. Performance management service data collection
  4. Performance PMR (perfpmr) data collected for performance problem analysis
The nmon, CEC, and cluster recordings are not affected by altering the daily.cf file. If you wants to have a reduced subset of metrics for recording, you can back up the existing daily.cf file, and alter it to remove the metrics that you do not want to record. Removing these metrics affects all the recording files previously listed. For example, if you do not want Disk/*/busy metrics to be recorded by using the topasrec command, you can remove this line from the /usr/lpp/perfagent/daily.cf file.
Note: For any dynamic configuration changes to the system, the tool has to be restarted to reflect the new changes.

Flags

Item Description
-C Records CEC statistics in binary format. The -C flag specifies that the cross-partition statistics are to be recorded.
-c sample_count Records the specified number of records and then stops.

If the -c flag is not specified, or if the value of the sample_count parameter is zero, the recording is continuous and the topasrec command writes to the recording file until it is stopped.
-L Records local statistics in binary format.
-l Lists the recordings that are running.
-s seconds Specifies the recording interval in seconds. The value of the seconds parameter should be a multiple of 60. For continuous recordings ( topasrec -c 0 ) of CEC and local statistics, the default value of recording interval is 900 seconds. For a sample count that is greater than zero, the default value of the recording interval is 300 seconds.
-O xmtopas=<hostname> Specifies the name of the host that aggregates the data and provides it to topasrec. If this is not specified, topasrec will get data from one of the known aggregators.
Note: You cannot use the override option with persistent recording.
-o < output_filename > Specifies the name of the output file. The value of the output_filename parameter can be a directory with an optional file prefix. You can specify one of the following types of file names to the output_filename parameter:
  • A directory. The directory should always end with /. For example, the /etc/perf/ directory.
  • A directory with a file name. For example, the /home/tester/perf_load file.
  • A file name. For example, the perf_load file.

The default output file is the current directory ( ./ ).

In CEC recording, Cluster Recording and local recording, the default prefix of the file name is the host name.

If you provide a file name that contains a directory and a file name prefix in the -o output_filename flag, the name of the recorded file is in the following format:
  • For CEC metrics, the output is in the following format:

    <filename>_cec_YYMMDD_HHMM.topas

  • For Cluster metrics, the output is in the following format:

    <filename>_cluster_YYMMDD_HHMM.topas

  • For local metrics, the output is in the following format:

    <filename>_YYMMDD_HHMM.topas

If you provide a file name that contains only the directory prefix, the name of the recorded file is in the following format:
  • For CEC metrics, the output is in the following format:

    <filename/hostname>_cec_YYMMDD_HHMM.topas

  • For Cluster metrics, the output is in the following format:

    <filename/hostname>_cluster_YYMMDD_HHMM.topas

  • For local metrics, the output is in the following format:

    <filename/hostname>_YYMMDD_HHMM.topas

In these formats, year (YY), month (MM), day (DD), hour (HH), and minute (MM) correspond to the time when the recording file is created.

Note: For CEC/Cluster Recording , if xmtopas override option is used then filename will be the value specified for xmtopas=<value>.

Example:

< value>_cec_YYMMDD_HHMM.topas
< value>_cluster_YYMMDD_HHMM.topas
-r retention Specifies the number of days for which the file must be retained. The minimum value is 1. For example, -r 5 specifies that the file is retained for five days.
-R max_days_per_file Specifies the number of days for which the performance data needs to be written to a file. The minimum value is 1 and maximum value is 366. For example, if we start a persistent recording with option -R 2 on day 1, the performance data of day 1 and day 2 are written to the same file. On day 3, a new file is created that contains the performance data of day 3 and day 4.
-t trace level Specifies the trace level. The trace level can be set from 1 to 9.

Parameters

Item Description
sample_count Specifies the number of records to generate.
output_filename Specifies the name of the output file.
seconds Specifies the recording interval in seconds.

Examples

  1. To start a local binary recording that runs for 5 minutes and contains system metrics every 1 minute, enter the following command: 
    topasrec -L -c 5 -s 60
    If the file is created at 23:14, Mar 10, 2008, and the host name is ses15, then the output file name is ./ses15_080310_2314.topas.
  2. To start a continuous local binary recording with a /home/test/sample file name, enter the following command: 
    topasrec -L -o /home/test/sample
    If the file is created at 12:05, Mar 10, 2008, and the host name is ses15, then the output file name is /home/test/sample_080310_1205.topas.
  3. To start a CEC recording that runs for 20 minutes with metrics recorded at 120-second intervals, and generate an output file named sample, enter the following command: 
    topasrec -C -o sample -s 120 -c 10
    If the file is created at 08:07, Feb 1, 2008, and the host name is ses15, then the output file name is ./sample_cec_080201_0807.topas.
  4. To start a continuous local binary recording with a /home/test/sample_bin file name, enter the following command: 
    topasrec -C -o /home/test/sample_bin
    If the file is created at 04:20, Feb 1, 2008, and the host name is ses15, then the output file name is /home/test/sample_bin_080201_0420.topas.
  5. To list the details of the running recordings, enter the following command: 
    topasrec –l
  6. To enable trace, enter the following command: 
    topasrec –L –t 1
  7. To start a Cluster recording that runs for 20 minutes with metrics recorded at 120-second intervals, and generate an output file named sample, enter the following command: 
    topasrec -G -o sample -s 120 -c 10
    If the file is created at 08:07, Feb 1, 2008 and the host name is ses15 then the output file name is /sample_cluster_080201_0807.topas..
  8. To start a continuous local Cluster recording with a /home/test/sample_bin file name, enter the following command: 
    topasrec -G -o /home/test/sample_bin
  9. To manually start a local azizo recording, enter the following command: 
    topasrec -L -O type=azizo
    If a valid /etc/perf/xmtopas.cf file is present, the azizo recording is automatically started by the xmtopas command. After the recording is started, it generates the azizo.<yymmdd> file in the /etc/perf/ directory and runs only if the xmtopas command is running

Files

Item Description
/usr/bin/topasrec Contains the topasrec command.