Docs4dev
Docs
mongodb / v3.6 / reference / reference-program-mongoreplay.html

mongoreplay

On this page

Synopsis

New in version 3.4.

Availability

Available for Linux and macOS.

mongoreplay is a traffic capture and replay tool for MongoDB that you can use to inspect and record commands sent to a MongoDB instance, and then replay those commands back onto another host at a later time.

mongoreplay can help you preview how your MongoDB deployment will perform a production workload under a different environment, such as with a different storage engine, on different hardware, or with a different operating system configuration. mongoreplay can also help reproduce and investigate an issue by recording and replaying the operations that trigger the issue. Finally, mongoreplay serves as a more flexible version of the legacy mongosniff tool to help you investigate database activity.

Run mongoreplay from the system command line, not the mongo shell.

Required Access

mongoreplay requires access to the network interface that the record or monitor commands will listen on. You may need to run mongoreplay with root privileges to access the network device.

mongoreplay will not work with MongoDB instances using an SSL connection.

Warning

Only use root privileges when connecting to trusted sources.

If you are using play to connect to a MongoDB deployment that enforces access control, you must connect as a user with the required privileges to execute the recorded operations. Include the user’s credentials in the --host MongoDB connection string.

Options

mongoreplay
--verbosity , -v

Increases the amount of internal reporting returned on standard output or in log files. Increase the verbosity with the -v form by including the option multiple times, (e.g. -vvvvv.)

--debug , -d

Increases the amount of detail about mongoreplay operations and errors recorded in log files. Increase the debugging detail with the -d form by including the option multiple times, (e.g. -ddd.)

--silent , -s

When set, mongoreplay does not produce any log output.

--help

Returns information on the options and use of mongoreplay.

Commands

mongoreplay includes the following commands to record, play back, and monitor MongoDB network traffic.

record

record produces a playback file based on network traffic. record supports collecting network traffic directly or can accept a pcap file to produce the playback file. The playback file contains a list of all requests sent to the mongod instance during the recording as well as all responses transmitted to the client during the recording. The playback file also records metadata for each request, such as the connection identifier and timestamp.

The following prototype uses mongoreplay to record data on the loopback network interface and creates a playback file located at ~/recordings/playback.

mongoreplay record -i eth0 -e "port 27017" -p ~/recordings/playback

Similarly, the following prototype uses mongoreplay to produce a playback file from an existing pcap file:

mongoreplay record -f traffic.pcap -p ~/recordings/playback

record supports the following options:

mongoreplay record
record
-f <path>

Specifies the path to a pcap file that record should read to produce a playback file.

Use -f as an alternative to capturing network traffic using -i. You must specify either -f or -i. If you include both options, mongoreplay record produces an error.

-b <number>

Size of heap used to merge separate streams together.

--expr <filter expression> , -e <filter expression>

An expression in Berkeley Packet Filter (BPF) syntax to apply to incoming traffic to record. Required if you are capturing traffic from a network interface using -i.

For example, to capture traffic from a MongoDB instance running on port 27017, you would specify -e 'port 27017'.

-i <interface>

Specifies the network interface that record should listen on to capture network traffic.

Use with -e.

Use -i as an alternative to reading an existing pcap file with -i. You must specify either -f or -i. If you include both options, mongoreplay record produces an error.

--gzip <boolean>

If specified, record compresses the playback file with gzip.

--playback-file <path> , -p <path>

Specifies the path to which to write the playback file.

The produced playback file is a BSON file.

See

Use record for examples of using mongoreplay with the record command.

play

play replays a playback file created with record against a mongod instance.

The following prototype uses mongoreplay to replay the ~/recordings/playback playback file to the mongod instance running on 192.168.0.4:27018:

mongoreplay play -p ~/recordings/playback --report ~/reports/replay_stats.json --host mongodb://192.168.0.4:27018

play supports the following options:

mongoreplay play
play
--collect <json|format|none>

Default: format

Specifies the output format for the collected statistics.

  • json: outputs stat information as json
  • format: uses the formatting specified in the --format option to produce the output file.
  • none: does not provide any output
--report <path>

Specifies the path to which to write an execution report. Use --collect to specify the output format for the report.

If you do not specify --report, play writes to STDOUT.

--no-truncate

If specified, disables truncation of large reply payload data in the play log output.

--format

Default: %F{blue}%t%f %F{cyan}(Connection: %o:%i)%f %F{yellow}%l%f %F{red}%T %c%f %F{white}%n%f %F{green}%Q{Request:}%f%q%F{green}%R{Response:}%f%r)

Specifies the format for terminal output. You can specify arguments immediately after the format ‘verbs’ by wrapping them in curly braces, as in %Q{<arg>}.

If you specify --format, also specify format as the value for the --collect option.

--format supports the following verbs:

  • %n: namespace
  • %l: latency
  • %t: time. You may optionally specify the date layout using the Go Programming Language’s time formatting . Go uses Mon Jan 2 15:04:05 MST 2006 as its reference time. You must specify the time format using the reference time. Thus, if you wanted to print the date in format yyyy-mm-dd hh:mm, you would specify %t{2006-01-02 15:04}. Refer to the Go time formatting documentation for more information.
  • %T: op time
  • %c: command
  • %o: number of connections
  • %i: request ID
  • %q: request. You may optinally specified a dot-delimited field within the JSON structure, as in, %q{command_args.documents}.
  • %r: response. You may optinally specified a dot-delimited field within the JSON structure, as in, %q{command_args.documents}.
  • %Q{<arg>}: display <arg> on presence of request data
  • %R{<arg>}: display <arg> on presence of response data

In addition, --format supports the following start/end ANSI escape sequences:

  • %B/%b: bold
  • %U/%u: underline
  • %S/%s: standout
  • %F/%f: text color (required arg – word or number, 8-color)
  • %K/%k: background color (required arg – same as %F/%f)
--no-colors

When set, removes colors from the default format.

--playback-file <path> , -p <path>

Specifies the path from which to read the playback file.

If the playback