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| 2} thread = { on | off } tid = { t1, ... } pid = { p1, ... } abs_mem_for_dvars=memory_in_KB num_threads_traced=number_of_thread_to_trace}" ] [-d] [ -i Async_Fetch_Interval ] [ -e Pinned_memory_dvar_percent ] [-f to_print_time_profile_data_milli_or_micro ] [ -I Include_file1, ... ] [ -K ] [ -o Output_file ] [-q info={none|normal|detail}] [ -s Buffer_size ][ -t Interval ][ -T ] [-u] [ -X Program_name [ -A "Arguments_to_program" ] [-L "Lib path"] [-g] ] [ Script_name [ Arguments_to_script ] ]

probevue [ -P C ++_header_file ]

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

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.

The arguments to the probevue command and the vue script can be specified in a script instead of the command line. The script can be run repeatedly with same arguments by using this script. A vue language construct #VUE_CMD_ARGS can be used to specify the arguments to the probevue command in the file and the #VUE_SCRIPT_ARGS language construct can be used to specify the arguments to the vue script.

Notes:

When the arguments are specified in the script, all the arguments for a vue construct must be on the same line.
If arguments to the probevue command are specified by command line and in the script, only command line arguments are considered and all command arguments in the script are ignored. This process applies to the vue script arguments also.
The #VUE_CMD_ARGS and #VUE_SCRIPT_ARGS constructs do not support standard input.
The dynamic memory requirement of the probevue command is proportional to the product of number of CPUs and per-CPU trace buffer size (the value of the default_buffer_size tunable parameter of the probevctrl command). Hence, in a system that has large number of CPUs and higher value of per-CPU buffer can cause the probevue command to exceed the memory limit set by the ulimit parameter. In such scenarios, run the probevue command with the -u flag to cross that limit.

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.
-g	Turn on grouping of output from every clause of the probevue session i.e. all the output from a clause will appear together without getting interleaved by output from any other clause that is running simultaneously in another CPU. The -g flag overrides the `group_output_start()` or the `group_output_end()` statements present in the VUE script. Output of every clause is grouped from clause start to clause end irrespective of the `group_output_start()` or the `group_output_end()` statements present in the clauses.
-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\|2} 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. 2 With each message, displays the actual time taken to create the message as per the printf's %A format. 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. abs_mem_for_dvars=memory_in_KB Specifies the pinned memory, in kilo bytes (KB), that is allocated for dynamic type variables. This option is mutually exclusive to the -e option. num_threads_traced=number_of_thread_to_trace Specifies the maximum number of threads that the current ProbeVue session can support when the session has thread-local variables. This value overrides the corresponding global ProbeVue tunable value.
-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.
-f	Specifies the format in which the time taken by probe action must be displayed. The supported formats follow: milli Displays time in milliseconds. micro Display time in microseconds. The default format is milli.
-i Async_Fetch_Interval	Specifies how often the asynchronous statistics is fetched for the probevue command. This option overrides the global interval time for the probevue command. The minimum interval is 100 milliseconds.
-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, systrace, io, sysproc, and net 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. Note: For syscallx probe manager, when the -l syscallx probe is used, it displays both 32-bit and 64-bit base-system calls. To view only 32-bit calls, use syscallx32 probes, and to view only 64-bit calls, use syscallx64 probes.
-L "Lib path"	Prioritizes library search in the specified path. If the libraries are not found in the specified path, searches libraries in the default library path that is saved in the header of the `loader` section in the eXtended COFF (XCOFF) file. The -L flag is applicable to the user function tracing (uft) and C++ probe managers that use the name of the executable file. The -L flag is ignored for other probe managers.
-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.
-q info=level	Specifies reporting level of informational messages while parsing the vue script. The possible values follow: none No informational messages are displayed. normal Only important informational messages are displayed. detail All informational messages that can result in incorrect execution are reported.
-s Buffer_size	Specifies the size of the per-CPU trace buffers in KB. This is rounded to the next 4K page. You can use following levels:
-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.
-T	Starts probe action profiling at the start of session. The -T flag ensures that probe actions are profiled when the session is started.
-u	Starts probeVue session and sets the data segment to unlimited value. The -u flag is used to print stack traces from multiple processes of large binaries.
-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
```

The following script is an example of providing the arguments in the script:

!#/usr/bin/probevue
	#VUE_CMD_ARGS=-o /tmp/trace_out
	#VUE_SCRIPT_ARGS=read
	
	@@syscall:*:$1:entry 
	{
		printf("%t\n", get_stktrace(4));
	}

The script runs as: ./script.e

Files

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