probevctrl Command

Purpose

Changes and displays the ProbeVue dynamic tracing parameters and the ProbeVue sessions.

Syntax

probevctrl [ -c attribute = value ] [ -C ] [ -f { milli|micro }] [ -d sessionID ] [ -l ] [ -n attribute = value ] [ -p ] [-s { probevue_session_id } ] [ -t ] [ -u user-list ] [-T { show|start|stop|reset }]

Description

The probevctrl command changes and displays the ProbeVue dynamic tracing parameters, the per-processor trace buffer size, the consumed pinned memory, the user owning the session, the identifier of the process that started the session, and the information on whether the session has kernel probes for the ProbeVue sessions.

The following ProbeVue parameters are configurable:

ProbeVue status (enabled/disabled).
Maximum pinned memory (MB) allocated for all ProbeVue sessions.
Maximum pinned memory (KB) allocated for a non-privileged user’s ProbeVue session including the memory for the trace buffers.
Number of concurrent ProbeVue sessions allowed for a regular user.
Default size of the per-processor trace buffers (KB).
The minimum period in milliseconds that a regular user can request the trace consumer to read from its trace buffers.
The default period in milliseconds that the ProbeVue buffers will be read by the trace consumer.
The size of the per-processor computation stack used by a ProbeVue session (KB).
The minimum time interval allowed for global root user in interval probes.
The percentage of memory that is allocated for the dynamic data structure.
The size of the per-processor local table in KB.
The number of page fault contexts for handling page faults.
The maximum number of threads a ProbeVue session should support when it has thread local variables.
The maximum size of per-CPU buffer, in bytes, used by a net probe action.
The maximum time, in milliseconds, a systrace probe action can take when the action is started in interrupt context.
The maximum time, in milliseconds, a sysproc probe action can take when the action is started in interrupt context.
The maximum time, in milliseconds, an io probe action can take when the action is started in interrupt context.
The maximum time, in milliseconds, a net probe action can take when the action is started in interrupt context

Only the root user or the users having the aix.ras.probevue.manage authorization can update the ProbeVue parameters and view all the ProbeVue sessions. Otherwise, users can view only the sessions owned by themselves. Each session is displayed in the following format:

Sid	Pid	Uid	Buffer size in bytes	Consumed memory in bytes	Kernel probes	Profiling
sid	pid	uid	bufsize	memory	yes or no	yes or no

By default, the ProbeVue is enabled. Attempt to disable the ProbeVue when the ProbeVue sessions are active will fail.

Flags

-c

Specifies non-user ProbeVue parameters. Arguments to this flag must be separated by commas or enclosed in double quotation marks and separated by commas or spaces. If either the -p or the -t flag is not specified with this flag, new values will be made effective both in the present boot and next boot sessions. The valid attribute-value pairs are as follows:

trace= {on | off}: Specifies whether the ProbeVue must be enabled or disabled.
default_buffer_size=default_buffer_size: Specifies the default size of the per-processor trace buffers in KB. This is rounded to the next 4KB page.
max_total_mem_size=max_total_mem_size: Specifies the maximum pinned memory in MB consumable by the entire ProbeVue framework.
default_read_rate=default_read_rate: Specifies the default period in milliseconds that the ProbeVue buffers will be read by the trace consumer.
stack_size=stack_size_in_4Kpages: Specifies the size of the per-processor computation stack in KB. This will be rounded to the next 4KB page.
local_table_size=number: Specifies the size of the per-processor local table in KB. Half of the space allocated for the local table is used by temporary strings. The default value is set to 4 KB.
min_interval=interval in ms: Specifies the minimum time interval allowed for global root user in interval probes.
num_pagefaults=number: Specifies the number of page fault contexts for handling page faults. The specified number of page fault contexts are preallocated during ProbeVue framework initialization.
num_threads_traced=number: Specifies the maximum number of threads a ProbeVue session can support when it has thread local variables. The ProbeVue framework preallocates all the thread-local variables at the start of a session for the maximum number of threads that are specified with this attribute.
max_net_buf_size=number: Specifies the maximum size of per-CPU buffer, in bytes, used by a net probe action.
max_intr_systrcprb_time=number: Specifies the maximum amount of time, in milliseconds, that a probe action can take to run when the systrace probe action is started in interrupt context.
max_intr_sysprocprb_time=number: Specifies the maximum amount of time, in milliseconds, that a probe action can take to run when the sysproc probe action is started in interrupt context.
max_intr_ioprb_time=number: Specifies the maximum amount of time, in milliseconds, that a probe action can take to run when the io probe action is started in interrupt context.
max_intr_netprb_time=number: Specifies the maximum amount of time, in milliseconds, that a probe action can take to run when the net probe action is started in interrupt context.

-C

Sets the ProbeVue session tunable to initial values. The -C option uses the current configuration of system to determine configuration initial values ( High Config or Low Config) to be set and updates both current and next boot parameters. For more information about high and low configuration values of tunables, see the ProbeVue dynamic tracing facility topic.

Note: Before using the -C flag, ensure there is no active ProbeVue session.

-d sessionId

Displays the list of probes enabled for the specified session. When you specify all as the session ID, then the probes for all the ProbeVue sessions that can be viewed by the user is displayed. A list of ProbeVue sessions and the associated session ID can be obtained using the probevctrl command.

-f

Specifies the format in which time consumed data for probe actions needs to be displayed. The -f option can be used along with the -T option and it shows action on a specific session. The possible formats follow:

milli: Displays the time in milliseconds.
micro: Displays the time in microseconds.

The default format is milli.

-l

Lists the present value of the ProbeVue configuration parameters. If the -p or the -t flag is not specified, parameter values for the present boot session are displayed.

-n

Specifies the configurable parameters for regular users. Arguments to this option must be separated by commas or enclosed in double quotation marks and separated by commas or spaces. If either the -p or the -t flag is not specified with this flag, new values will be made effective both in the present boot and next boot sessions. The valid attribute-value pairs are as follows:

max_mem_size=max_mem_size: Specifies the maximum pinned memory in MB consumable by a ProbeVue session.
max_sessions=max_sessn: Specifies the maximum concurrent sessions allowed.
min_read_rate=min_read_rate: Specifies the minimum period in milliseconds that a regular user can request the trace consumer to read from its trace buffers.
pin_mem_dvar_pc=pin_mem_dvar_pc: Specifies the percentage of memory that can be allocated to the dynamic data structure for dynamic type variables. This memory can be used for stack trace and associative array type dynamic variables. The value of this parameter is set in the range 10-100. The default value is 50.

-p

Specifies that the default values for the next boot must be updated and displayed.

-s probevue_session_id

Specifies the session on which the action is to be performed. This flag must be used with the -T flag.

-u

Specifies comma-separated user list whose ProbeVue sessions must be listed. If the -u flag is not specified, all of the ProbeVue sessions that the user can view are displayed. A user with the aix.ras.probevue.manage authorization can view all of the ProbeVue sessions in the system. Users without this authorization can view only the ProbeVue sessions they own.

-t

Specifies that the default values for the present boot session must be updated and displayed.

-T show | start | stop | reset

Specifies whether to show, start, stop, or reset the probe action profiling for the session that is specified by the -s flag. The -s flag must be used along with this flag.

Examples

To modify the next boot default buffer size and to turn on the dynamic tracing, enter:

probevctrl -c trace=on,default_buffer_size=8 -p

probevctrl -c "trace=on default_buffer_size=8" -p

To list the next boot ProbeVue configuration, enter:
```
probevctrl -l -p
```
To list the present ProbeVue configuration, enter:
```
probevctrl -l -t
```
To list all of the ProbeVue sessions, enter:
```
probevctrl
```
To list all of the ProbeVue sessions owned by the user guest, enter:
```
probevctrl -u guest
```
To increase the percentage of pinned memory that is allocated for the dynamic data structures (stack trace and associative array) for the next boot from a default 50 -75, enter:
```
probevctrl -n  pin_mem_dvar_pc = 75
```