probevue Command

Purpose

Starts a dynamic trace session. The command can preprocess the header file and exit without starting the dynamic trace session.

Syntax

probevue [ -c "{ timestamp = { 0 | 1 } thread = { on | off } tid = { t1, ... } pid = { p1, ... } }" ] [ -I Include_file1, ... ] [-s Buffer_size ] [ -o Output_file ] [ -t Interval ] [ -X Program_name [ -A "Arguments_to_program" ] ] [ -K ] [ Script_name [ Arguments_to_script ] ] [ -e Pinned_memory_dvar_percent] [-d]

probevue [ -P < C ++ header file > ]

probevue [ -l "{ syscall | syscallx | syscallx32 | syscallx64 | interval | systrace }"]

Description

The probevue command analyzes the operating system and user programs by dynamically enabling the user-specified probes, starting the actions that are associated with the probes when they are triggered, and presenting the captured trace data.

When you specify the probevue command with a vue script, the command enables the tracing that was specified in the script, and produces the tracing output.

When the -P option is specified with the C++ header file, the command produces the preprocessed encrypted C header file. The encrypted C header file can be further used to probe C++ application by using the -I option of the probevue command.

Flags

Item	Description
-A "Arguments_to_program"	Specifies the arguments to the program that you specified to using the -X flag. If there are multiple arguments to the application, enclose each argument in quotation marks.
-c	Specifies how the trace data needs to be formatted. You must enclose arguments to this option in quotation marks and separate each argument by spaces. The options are as follows: timestamp={0\|1} Controls the reporting of the time stamp that is associated with an event in the trace report. Specify one of the following values: 0 Displays the timestamp, in seconds and microseconds, for each message relative to the beginning of the trace. The first line of the trace output shows the base time from which the individual time stamps are measured. 1 With each message, displays the actual time taken to create the message. Note: If both options are desired then 0,1 must be entered. That is, there must be no spaces between 0,1. thread={on\|off} Displays the thread ID which generated the message, with each message. The default value is off. pid={p1,..} Displays only the messages that were generated by the processes specified. Note: If the thread has died before the trace consumer tries to know the process to which the thread belongs, or if the process that you specified no longer exists, the consumer cannot display the messages that were generated by the threads in this process, when you filter the messages by the process ID. tid={t1,..} Displays only the messages that were generated by the threads that you specified.
-d	Displays the list of probes enabled for the session.
-e Pinned_memory_dvar_percent	Specifies the percentage of the dynamic data structure memory allocated for dynamic type variables. A minimum of 10 and a maximum of 100 value can be specified as the percentage.
-I Include_file1	Uses the file specified as a post-processed header file, that is one with no C-preprocessor operators. It can be passed through the command line to be included when compiling the vue script.
-K	Enables RAS events related functionality in a probevue session.
-l	Lists all the probe points supported by the probe manager. When you specify the -l flag with the probevue command, no other flags must be used. You can specify more than one probe manager with the -l flag, such as `-l syscall-l syscallx-l interval`. The probe manager supports interval, syscall, syscallx, and systrace probes for the -l flag. If you specify wrong arguments or an incorrect probe manager with the -l option, a usage error is displayed. `probevue -l syscall`: Lists all the possible system call that can be traced on the system. `probevue -l syscallx`: Displays all base system calls that can be traced on the system. This option lists the system call separately for the 32 and 64-bit systems. `probevue -l syscallx32`: Displays the 32-bit base system calls that can be traced on the system. `probevue -l syscallx64`: Displays the 64-bit base system calls that can be traced on the system. `probevue -l interval`: Specifies the minimum and maximum interval duration supported for regular and root users with the interval probe. `probevue -l systrace`: Displays a description about the systrace probe.
-o Output_file	Writes the report to a file rather than to the standard output.
-P C++ header file	Preprocesses the C++ header file and creates an output preprocessed file for each input C++ header file. The preprocessed output file has the same name as the input C++ header file, with a .Vue suffix. Note: You cannot use other flags with the -P option. The -P flag accepts any file name, except the file name with a .Vue suffix.
-s Buffer_size	Specifies the size of the per-CPU trace buffers in KB. This is rounded to the next 4K page.
-t Interval	Specifies how often the trace buffers are read. The minimum interval that you can specify is 10 milliseconds. The time interval specified by the regular user (that is a user without the aix.ras.probevue.trace privilege) is rounded to the next highest multiple of 10 milliseconds. The read rate is retrieved from the probevue configuration. Note: A regular user can specify the minimum read rate and the probevctrl command can change the default read rate.
-X Program_name	Starts a program and enables probes before the program starts. You can use the special environment variables $__CPID and $__CTID within a vue script to identify the process ID and the thread ID of the application that is launched.

Security

Attention RBAC users and Trusted AIX® users: This command can perform privileged operations. Only privileged users can run privileged operations. For more information about authorizations and privileges, see Privileged Command Database in Security. For a list of privileges and the authorizations associated with this command, see the lssecattr command or the getcmdattr subcommand.

Examples

To start a probevue session with script syscall.e, enter:
```
probevue syscall.e
```
To send the trace report to the /tmp/trace_report file, enter:
```
probevue -o /tmp/trace_report syscall.e
```
To display the trace report of the thread IDs 12345,4567 and the timestamp relative to the beginning of trace, enter:
```
probevue -c "timestamp=0 tid=12345,4567" syscall.e
```
To include the header file stat.i and allocate 4K of per-CPU buffer, enter:
```
probevue –I stat.i –s 4 syscall.e
```
To preprocess the C++ header file myheader.h , enter:
```
  probevue –P myheader.h
```
The probevue command generates the myheader.Vue file, which is an encrypted C++ header file and is included in the trace session by using the -I option.
To increase the percentage of pinned memory for the current session of the dynamic data structures (stack trace and associative array), from a default of 50 -75 for the ASO.e script, enter:
```
probevue -e 75  ASO.e
```

Files

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