p4 monitor

Display Perforce process information and control long-running tasks.

Syntax

p4 [g-opts] monitor show [-a -l -e -L -s R | T | P | B | F | I ]
p4 [g-opts] monitor terminate id
p4 [g-opts] monitor clear {id | all}
p4 [g-opts] monitor pause id
p4 [g-opts] monitor resume id
p4 [g-opts] monitor realtime [-F -T]

Syntax conventions

Description

p4 monitor allows a system administrator to observe and control Helix Server-related processes running on a Helix Server machine. Processes are tracked using a dedicated table that is constantly updated. This has a minor impact on server performance.

To use p4 monitor, you must enable monitoring on the Perforce service by setting the monitor configurable with p4 configure.

Valid values for the monitor configurable are:

• 0: Server process monitoring off. (Default)
• 1: monitor active commands
• 2: active commands and idle connections
• 3: same as 2, but also includes connections that failed to initialize (stuck at the Init() phase)
• 5: same as 2, but also includes a list of the files locked by the command for more than one second
• 10: same as 5, but also includes lock wait times
• 25: same as 10, except that the list of files locked by the command includes files locked for any duration

Changes to the monitor configurable affect all new p4 processes that connect to the server. Restarting the server is not required.

See Enabling process monitoring in Helix Core Server Administrator Guide.

Command syntax variants provide the following alternatives:

• (list level access):To list current process information, use p4 monitor show. By default, all processes are listed, but only the command (for example, sync, edit, submit) is shown, without arguments. Use the -s status option to restrict the display to processes in the specified state.

• (super level access):To show the list of arguments associated with each command, use the -a (arguments) option or -l (long) option. For additional information from the user environment, use the -e (environment) option. To show locked files, use the -L option.

• (operator or super level access): To mark a process for termination, use p4 monitor terminate id. This command requires that the user be an operator or have super level access.

  The p4 monitor terminate command does not mark a process for termination unless the process has been running for at least ten seconds. Some commands, such as p4 obliterate, cannot be terminated.

  To control how often the list of processes is refreshed, see the db.monitor.interval, which is also mentioned in the Support Knowledgebase article, "Fixing a hung Helix Server".

• (operator or super level access): If a command terminates prematurely on the server side, it might be erroneously listed as running. You can clear such processes with p4 monitor clear.

  With super level access:

  • To remove an entry from the monitor table, use p4 monitor clear id
  • To clear the entire table, use p4 monitor clear all

  Processes marked as running continue to run to completion even if removed from the monitor table with p4 monitor clear.

• (operator or super level access): To control the following tasks if they are running too long, use the p4 monitor pause and p4 monitor resume:

  • p4 admin
  • p4 dbstat
  • p4 grep
  • p4 ldapsync -g
  • p4 ping
  • p4 pull
  • p4 verify

Output format

Each line of p4 monitor output consists of the following fields:

pid status owner hh:mm:ss command [args]

pid	The process ID under Unix (or thread ID under Windows)
status	R, T, P, B, F, or I, depending on whether the process is: Running marked for Termination Paused Background Finish Idle Note Finish and Background occur only in replica servers.
owner	The Helix Server user name of the user who invoked the command.
hh:mm:ss	The time elapsed since the command was called.
command [args]	The command and arguments as received by the Perforce service.

For example, consider the following output to the p4 monitor show -L command, which displays information about locked files:

8764 R user 00:00:00 edit
      [server.locks/clients/88,d/ws4(W),db.locks(R),db.rev(R)]
8766 R user 00:00:00 edit
      [server.locks/clients/89,d/ws5(W),db.locks(R),db.rev(R)]
8768 R user 00:00:00 monitor

Following pid, status, owner, and time information, this shows two edit commands that have various files locked, including the client workspace lock in exclusive mode for the workspaces ws4 and ws5, and db.locks and db.rev tables in read-only mode.

If you have enabled idle process monitoring (by setting the monitor configurable to 2), idle processes appear with a status of R, but with a command of IDLE.

Some commands (for instance, p4 submit) invoke multiple processes. For example, dm_CommitSubmit or dm_SubmitChange might appear in the output of p4 monitor as two separate phases of the p4 submit command.

Getting pull thread information for replicas

If you are running a replica with monitoring enabled and you have not configured the monitor table to be disk-resident, you can run the following command to get more precise information about what pull threads are doing. (Remember to set monitor.lsof).

$ p4 monitor show -sB -la -L

Command output would look like this:

31701 B uservice-edge3 00:07:24 pull sleeping 1000 ms
    [server.locks/replica/49,d/pull(W)]

p4 monitor realtime

Outputs real-time performance counters when enabled by setting the rt.monitorfile configurable. One use case is to determine, in real time, whether a replica is making progress while replicating a large transaction from the master. (This use case requires that the rpl.track.behind configurable be set to 1 or 2.)

p4 monitor realtime options

You must be an operator or have super access to use the following options:

-F	List only performance counters satisfying the filter expression. The filter evaluates the contents of the fields in the preceding list. Filtering is case-sensitive. Example: -F "name=rtv.svr.sessions*" (The filter syntax is similar to the one used for Job Views.)
-T	Returns only the specified fields. The field names can be specified using a comma-delimited list or a space-delimited list. Example: -T "name,value"

The real-time performance counters are for monitoring in real time:

Counter	Description
rtv.db.ckp.active	Indicates if a checkpoint is in progress.
rtv.db.ckp.records	The number of records that have been read into an ongoing checkpoint.
rtv.db.io.records	Running count of database IO reads, writes, and deletes. This counter might affect performance. To enable, set the db.rt.io configurable to 1.
rtv.db.lockwait	Commands waiting for locks. Includes the high mark of most commands waiting for locks at any one time.
rtv.rpl.behind.bytes	Replication lag represented as bytes of journal that the upstream server has yet to send. This counter is enabled when the rpl.track.behind configurable is set to 1 or greater. The rpl.track.behind.interval configurable can be used to tune the frequency of updates during p4 pull.
rtv.rpl.behind.journals	Replication lag represented as rotated journals that the upstream server has yet to send. See rtv.rpl.behind.bytes for related configurables.
rtv.server.connection.pause.pct.cpu	The percentage of commands to pause when CPU pressure is in a high state. The highest percentage of this or the rtv.server.connection.pause.pct.mem counter takes precedence.
rtv.server.connection.pause.pct.mem	The percentage of commands to pause when memory pressure is in a medium or high state. The highest percentage of the rtv.server.connection.pause.pct.cpu or this counter takes precedence.
rtv.svr.sessions.active	Current connections from clients. Includes a high mark of most concurrent connections at any one time.
rtv.svr.sessions.paused	Number of server sessions that are paused.
rtv.svr.sessions.total	Running count of client connections.
rtv.sys.mem.os.available	An estimate of how much memory is available for starting new applications without swapping.
rtv.sys.mem.os.free	Amount of memory that is not allocated to any application or the operating system.
rtv.sys.mem.os.swap.free	Amount of swap memory that is not allocated.
rtv.sys.mem.os.swap.total	Total amount of swap configured in the system.
rtv.sys.mem.os.total	Total amount of operating system memory.
rtv.sys.pressure.lastcollecttime	Timestamp of the most recent assessment of system pressure.
rtv.sys.pressure.level.cpu	The level of CPU pressure on a scale from 0 = low, 1 = medium, 2 = high
rtv.sys.pressure.level.mem	The level of memory pressure on a scale from 0 = low, 1 = medium, 2 = high

Options

You must be an operator or have super access to use the following options:

-a	Show all arguments associated with the process (for example, edit file.c, or sync -f //depot/src/...). Helix Server user names are truncated to 10 characters, and each line of output is limited to 80 characters.
-e	Show environment information, including invoking Helix Server application (if known), host IP address, and workspace name.
-l	Show all arguments in long form, that is, without truncating user names or the list of command line arguments.
-L	Show information about locked files. The information is collected only for the duration of the p4 monitor command, and is not persisted. Pre-requisites for using this option vary with the platform on which the server is running. On Unix platforms, you must set the monitor.lsof configurable to the following value: $ path/lsof -F pln The value for path varies with the version of Unix you are using. For example, /usr/bin/lsof. There are circumstances in which monitor.lsof might not work for you: your Linux machine does not support lsof, the version of lsof might not work with the Helix Server, or the administrator might not be willing to run the lsof command for security reasons. If this is the case, you can still get information about locked files by setting the monitor configurable, described next. Note Microsoft Windows does not have the lsof utility to list open files, and we therefore recommend that Windows systems use values other than 5, 10, or 25. You can use the -z tag option with this option. In that case, the p4 monitor show command will return one lockinfo tag for each file that the process has locked.
-s status	Restrict the display to processes in the Running, Terminated, Paused, Background, Finish, or Idle states.
g-opts	See Global options.

Usage Notes

Can File Arguments Use Revision Specifier?	Can File Arguments Use Revision Range?	Minimal Access Level Required
No	No	super available to an operator user list is sufficient for p4 monitor show

Examples

p4 monitor show	Show Helix Server process information (commands only). Requires list access only.
p4 monitor show -l	Show arguments and commands, without limits on line length. Requires super access.
p4 monitor show -a	Show arguments and commands, limited to 80 characters per line of output. Requires super access.
p4 monitor terminate 123	Instruct the Perforce service to mark process 123 for termination. Requires super access.
p4 monitor clear all	Clears the monitor table of all entries. Requires super access.

Related Commands

To turn on monitoring	p4 configure set monitor=1
To turn off monitoring	p4 configure set monitor=0