trace-event

monitor notification events from the server

Usage

accurev trace-event [ --category <categories> ] 
[ -p <depots> ] [ -s <streams> ] [ -u <users> [ --exclude_users ] ] 
[ -k <transaction-kinds> [ --exclude_kinds ] ] [ -f <formats> ] 
[ -l <response> ]

Description

The trace-event command monitors server events by listening for messages published by the server. The server uses the Mosquitto message broker and MQTT (MQ Telemetry Transport) to publish a message for each write operation that it executes. By listening for these messages instead of polling, trace-event avoids creating any load on the server.

trace-event options apply filters to constrain which events are displayed in the output. They also enable running an external application or script in response to the events. Multiple instances of trace-event can be run on a client machine (or VM) for different purposes.

The trace-event command continues to listen for events (and respond if applicable) until the application is terminated via Ctrl-C.

Options

Note: If multiple values are specified for an option, separate the values with commas. If any of the values contains a space in it, place double quotes around the entire list of values.

--category <categories>

Specify the categories of message events to display. If this option is not specified, trace‑event displays all categories of events. Valid values are:
stream, accuwork, depot, site

Note: Note: --category <categories> cannot be used together with -k <kinds>.

-p <depots>

Specify the depots to watch for in depot-category message events.

-s <streams>

Specify the streams to watch for in stream-category message events.

-u <users>

Specify the users to watch for in all categories of message events.

--exclude_users

Use in conjunction with the -u option to indicate that the named users should be filtered out and that messages for all other users should be displayed in the output.

-k <transaction-kinds>

Specify the kinds of transactions to display. Valid values are:
add, addmember, archive, backup, chstream, chws, clear, chdepot, chgroup, chpasswd, chuser, chref, chslice, co, cpkadd, cpkremove, defunct, demote, eacl, excl, incl, incldo, keep, ln, lock, mkdepot, mkgroup, mkrules, mksnap, mkstream, mkuser, mkref, mkreplica, mktrig, mkws, modify_issue, move, new_issue, promote, purge, putconfig, reactivate_group, reactivate_ref, reactivate_stream, reactivate_user, reactivate_wspace, reclaim, remove_group, remove_ref, remove_sessions, remove_stream, remove_user, replica_sync, rmmember, rmproperty, rmreplica, rmtrig, rmws, setacl, setproperty, unarchive, undefunct, unlock

Note: -k <kinds> cannot be used with --category <categories>.

--exclude_kinds

Use in conjunction with the -k option to indicate that the named kinds of transactions should be filtered out and that messages for all other kinds of transactions should be displayed in the output.

-f <formats>

Use one or more of the following format letters:

-v: (“verbose”) Show the comment and timestamp for the transaction.
-x: (“XML”) Show the results in XML format.

-l <response>

Specify the path of an external application or script to be executed in response to each trace-event message.

The trace‑event command does simple argument substitution to enable arguments to be passed to the response application:

  • $depot – substitute the depot name
  • $kind – substitute the transaction kind
  • $principal – substitute the name of the user who executed the operation
  • $members - substitute the user(s) or group(s) that are affected by the operation (if applicable)
  • $stream – substitute the stream name (if applicable)
  • $transnum – substitute the transaction number (if applicable)
  • $issues - substitute the issue number(s) (if applicable)
  • $comment – substitute the comments (if applicable)

For example, if the response option is “-l /home/$principal/logger.py $comment”, then $principal is replaced with the message’s user name and $comment is replaced with the message’s comment.

Examples

Display all published messages:

   > accurev trace-event

Display all site-related messages and ignore messages related to streams, depots, and AccuWork:

   > accurev trace-event --category site

Display verbose messages published for depots d1 and d2:

   > accurev trace-event –p d1,d2 -fv

Display promote messages for streams release and production:

   > accurev trace-event –s release,production –k promote

Display promote messages for all users except john smith and jones:

   > accurev trace-event –u "john smith,jones" --exclude_users –k promote

Display promote and chstream messages for the stream named backing. When such events occur, execute “accurev update –m” to merge the updates:

   > accurev trace-event –s backing –k promote,chstream –l “accurev update –m”

Display promote messages for the stream named backing. When such events occur, run the python script C:\tools\promote_response.py and pass the depot name to the script:

   > accurev trace-event –s backing –k promote –l “python C:\tools\promote_response.py $depot”