path: root/debian/mongoreplay.1

.\" Man page generated from reStructuredText.
.
.TH "MONGOREPLAY" "1" "Oct 29, 2019" "4.2" "mongodb-manual"
.SH NAME
mongoreplay \- MongoDB Traffic Capture and Replay Tool
.
.nr rst2man-indent-level 0
.
.de1 rstReportMargin
\\$1 \\n[an-margin]
level \\n[rst2man-indent-level]
level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
-
\\n[rst2man-indent0]
\\n[rst2man-indent1]
\\n[rst2man-indent2]
..
.de1 INDENT
.\" .rstReportMargin pre:
. RS \\$1
. nr rst2man-indent\\n[rst2man-indent-level] \\n[an-margin]
. nr rst2man-indent-level +1
.\" .rstReportMargin post:
..
.de UNINDENT
. RE
.\" indent \\n[an-margin]
.\" old: \\n[rst2man-indent\\n[rst2man-indent-level]]
.nr rst2man-indent-level -1
.\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
.in \\n[rst2man-indent\\n[rst2man-indent-level]]u
..
.SS On this page
.INDENT 0.0
.IP \(bu 2
\fI\%Synopsis\fP
.IP \(bu 2
\fI\%Availability\fP
.IP \(bu 2
\fI\%Required Access\fP
.IP \(bu 2
\fI\%Options\fP
.IP \(bu 2
\fI\%Commands\fP
.IP \(bu 2
\fI\%mongoreplay Report Format\fP
.IP \(bu 2
\fI\%Examples\fP
.UNINDENT
.SH SYNOPSIS
.sp
New in version 3.4.

.INDENT 0.0
.INDENT 3.5
.IP "Availability"
.sp
Available for Linux and macOS.
.UNINDENT
.UNINDENT
.sp
\fI\%mongoreplay\fP 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.
.sp
\fI\%mongoreplay\fP 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.
\fI\%mongoreplay\fP can also help reproduce and investigate an issue by
recording and replaying the operations that trigger the issue.
Finally, \fI\%mongoreplay\fP serves as a more flexible version of
the legacy \fBmongosniff\fP tool to help you investigate database activity.
.sp
Run \fI\%mongoreplay\fP from the system command line, not the \fBmongo\fP shell.
.SH AVAILABILITY
.sp
The \fI\%mongoreplay\fP tool is part of the MongoDB tools package. Consult the
installation guide for your platform for
instructions on how to install the tools package as part of your
MongoDB installation.
.sp
The tools package is also available from the
\fI\%MongoDB Download Center\fP,
either as a separate \fBtools\fP download, or contained within the
\fBTGZ\fP or \fBZIP\fP downloads, depending on platform. The \fBmongoreplay\fP tool is not available on Windows.
.INDENT 0.0
.INDENT 3.5
.SH TIP
.sp
If downloading the \fBTGZ\fP or \fBZIP\fP files from the Download
Center, you may want to update your \fBPATH\fP environment
variable to include the directory where you installed these tools.
See the installation guide
for your platform for more information.
.UNINDENT
.UNINDENT
.SH REQUIRED ACCESS
.sp
\fI\%mongoreplay\fP requires access to the network interface that
the \fI\%record\fP or \fI\%monitor\fP commands will
listen on. You may need to run \fI\%mongoreplay\fP with root privileges
to access the network device.
.sp
\fI\%mongoreplay\fP will not work with MongoDB instances using an SSL connection.
.sp
\fBWARNING:\fP
.INDENT 0.0
.INDENT 3.5
Only use root privileges when connecting to trusted sources.
.UNINDENT
.UNINDENT
.sp
If you are using \fI\%play\fP 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\(aqs credentials in the
\fI\%\-\-host\fP MongoDB connection string.
.SH OPTIONS
.INDENT 0.0
.TP
.B mongoreplay
.UNINDENT
.INDENT 0.0
.TP
.B \-\-verbosity, \-v
Increases the amount of internal reporting returned on standard output
or in log files. Increase the verbosity with the \fB\-v\fP form by
including the option multiple times, (e.g. \fB\-vvvvv\fP\&.)
.UNINDENT
.INDENT 0.0
.TP
.B \-\-debug, \-d
Increases the amount of detail about \fBmongoreplay\fP operations
and errors recorded
in log files. Increase the debugging detail with the \fB\-d\fP form by
including the option multiple times, (e.g. \fB\-ddd\fP\&.)
.UNINDENT
.INDENT 0.0
.TP
.B \-\-silent, \-s
When set, \fBmongoreplay\fP does not produce any log output.
.UNINDENT
.INDENT 0.0
.TP
.B \-\-help
Returns information on the options and use of \fBmongoreplay\fP\&.
.UNINDENT
.SH COMMANDS
.sp
\fI\%mongoreplay\fP includes the following \fIcommands\fP to record,
play back, and monitor MongoDB network traffic.
.SS \fBmongoreplay record\fP
.sp
\fI\%record\fP produces a playback file based on
network traffic. \fI\%record\fP supports collecting network
traffic directly or can
accept a \fI\%pcap file\fP
to produce the playback file.
The playback file contains a list of all requests sent to the
\fBmongod\fP 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.
.sp
The following prototype uses \fI\%mongoreplay\fP to record data
on the loopback network interface and creates a playback file
located at \fB~/recordings/playback\fP\&.
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
mongoreplay record \-i eth0 \-e "port 27017" \-p ~/recordings/playback
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Similarly, the following prototype uses \fI\%mongoreplay\fP
to produce a playback file from an existing pcap file:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
mongoreplay record \-f traffic.pcap \-p ~/recordings/playback
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
\fBrecord\fP supports the following options:
.INDENT 0.0
.TP
.B mongoreplay record
.UNINDENT
.INDENT 0.0
.TP
.B record
.UNINDENT
.INDENT 0.0
.TP
.B \-f <path>
Specifies the path to a pcap file that \fI\%record\fP should read to
produce a playback file.
.sp
Use \fB\-f\fP as an alternative to capturing network traffic using
\fB\-i\fP\&. You must specify \fIeither\fP \fB\-f\fP or \fB\-i\fP\&. If you include
both options, \fBmongoreplay record\fP produces an error.
.UNINDENT
.INDENT 0.0
.TP
.B \-b <number>
Size of heap used to merge separate streams together.
.UNINDENT
.INDENT 0.0
.TP
.B \-\-expr <filter expression>, \-e <filter expression>
An expression in \fI\%Berkeley Packet Filter (BPF) syntax\fP to apply to incoming traffic to
record. Required if you are capturing traffic from a network interface using
\fI\%\-i\fP\&.
.sp
For example, to capture traffic from a MongoDB instance running on
port 27017, you would specify \fB\-e \(aqport 27017\(aq\fP\&.
.UNINDENT
.INDENT 0.0
.TP
.B \-i <interface>
Specifies the network interface that \fI\%record\fP should listen on to
capture network traffic.
.sp
Use with \fI\%\-e\fP\&.
.sp
Use \fB\-i\fP as an alternative to reading an existing pcap file with
\fB\-i\fP\&. You must specify \fIeither\fP \fB\-f\fP or \fB\-i\fP\&. If you include
both options, \fBmongoreplay record\fP produces an error.
.UNINDENT
.INDENT 0.0
.TP
.B \-\-gzip <boolean>
If specified, \fI\%record\fP compresses the playback file with gzip.
.UNINDENT
.INDENT 0.0
.TP
.B \-\-playback\-file <path>, \-p <path>
Specifies the path to which to write the playback file.
.sp
The produced playback file is a BSON file.
.UNINDENT
.INDENT 0.0
.INDENT 3.5
.SS See
.sp
\fI\%Use record\fP for examples of using
\fI\%mongoreplay\fP with the \fBrecord\fP command.
.UNINDENT
.UNINDENT
.SS \fBmongoreplay play\fP
.sp
\fBNOTE:\fP
.INDENT 0.0
.INDENT 3.5
Starting in MongoDB 4.0, \fI\%mongoreplay play\fP supports a new
\fBMONGOREPLAY_HOST\fP environment variable that specifies the
MongoDB connection string. The new environment
vairable can be used instead of the command\-line \fI\%\-\-host\fP option.
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B play
\fI\%play\fP replays a playback file created with
\fI\%record\fP against a \fBmongod\fP instance.
.UNINDENT
.sp
For example, the following uses \fI\%mongoreplay play\fP to replay the
\fB~/recordings/playback\fP playback file to the \fBmongod\fP instance running on
\fB192.168.0.4:27018\fP:
.INDENT 0.0
.IP \(bu 2
Using the \fI\%\-\-host\fP option:
.INDENT 2.0
.INDENT 3.5
.sp
.nf
.ft C
mongoreplay play \-p ~/recordings/playback \-\-report ~/reports/replay_stats.json \-\-host mongodb://192.168.0.4:27018
.ft P
.fi
.UNINDENT
.UNINDENT
.IP \(bu 2
Using the \fBMONGOREPLAY_HOST\fP environment variable (Available starting in MongoDB 4.0):
.INDENT 2.0
.INDENT 3.5
.sp
.nf
.ft C
export MONGOREPLAY_HOST="mongodb://192.168.0.4:27018"
mongoreplay play \-p ~/recordings/playback \-\-report ~/reports/replay_stats.json
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.SS \fBplay\fP Options
.sp
\fBplay\fP supports the following options:
.INDENT 0.0
.TP
.B mongoreplay play
.UNINDENT
.INDENT 0.0
.TP
.B \-\-collect <json|format|none>
\fIDefault\fP: format
.sp
Specifies the output format for the collected statistics.
.INDENT 7.0
.IP \(bu 2
\fBjson\fP: outputs stat information as json
.IP \(bu 2
\fBformat\fP: uses the formatting specified in the \fB\-\-format\fP option
to produce the output file.
.IP \(bu 2
\fBnone\fP: does not provide any output
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B \-\-report <path>
Specifies the path to which to write an execution report.
Use \fI\%\-\-collect\fP to specify the output format for the report.
.sp
If you do not specify \fB\-\-report\fP, \fI\%play\fP writes to STDOUT.
.UNINDENT
.INDENT 0.0
.TP
.B \-\-no\-truncate
If specified, disables truncation of large reply payload data in the
\fI\%play\fP log output.
.UNINDENT
.INDENT 0.0
.TP
.B \-\-format
\fIDefault\fP: \fB%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)\fP
.sp
Specifies the format for terminal output.
You can specify arguments immediately after the format \(aqverbs\(aq by wrapping
them in curly braces, as in \fB%Q{<arg>}\fP\&.
.sp
If you specify \fI\%\-\-format\fP, also specify \fBformat\fP as the value for the
\fI\%\-\-collect\fP option.
.sp
\fI\%\-\-format\fP supports the following verbs:
.INDENT 7.0
.IP \(bu 2
\fB%n\fP: namespace
.IP \(bu 2
\fB%l\fP: latency
.IP \(bu 2
\fB%t\fP: time. You may optionally specify the date layout using the
Go Programming Language\(aqs \fI\%time formatting\fP\&. Go
uses \fBMon Jan 2 15:04:05 MST 2006\fP as its reference time. You
must specify the time format using the reference time. Thus, if you
wanted to print the date in format \fByyyy\-mm\-dd hh:mm\fP, you would
specify \fB%t{2006\-01\-02 15:04}\fP\&. Refer to the Go \fI\%time formatting\fP
documentation for more information.
.IP \(bu 2
\fB%T\fP: op time
.IP \(bu 2
\fB%c\fP: command
.IP \(bu 2
\fB%o\fP: number of connections
.IP \(bu 2
\fB%i\fP: request ID
.IP \(bu 2
\fB%q\fP: request. You may optinally specified a dot\-delimited field
within the JSON structure, as in, \fB%q{command_args.documents}\fP\&.
.IP \(bu 2
\fB%r\fP: response. You may optinally specified a dot\-delimited field
within the JSON structure, as in, \fB%q{command_args.documents}\fP\&.
.IP \(bu 2
\fB%Q{<arg>}\fP: display \fB<arg>\fP on presence of request data
.IP \(bu 2
\fB%R{<arg>}\fP: display \fB<arg>\fP on presence of response data
.UNINDENT
.sp
In addition, \fI\%\-\-format\fP supports the following start/end ANSI escape sequences:
.INDENT 7.0
.IP \(bu 2
\fB%B\fP/\fB%b\fP: bold
.IP \(bu 2
\fB%U\fP/\fB%u\fP: underline
.IP \(bu 2
\fB%S\fP/\fB%s\fP: standout
.IP \(bu 2
\fB%F\fP/\fB%f\fP: text color (required arg \-\- word or number, 8\-color)
.IP \(bu 2
\fB%K\fP/\fB%k\fP: background color (required arg \-\- same as %F/%f)
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B \-\-no\-colors
When set, removes colors from the \fI\%default format\fP\&.
.UNINDENT
.INDENT 0.0
.TP
.B \-\-playback\-file <path>, \-p <path>
Specifies the path from which to read the playback file.
.sp
If the playback file was created using the \fI\%\-\-gzip\fP option, you must also specify \fB\-\-gzip\fP
when running \fI\%play\fP\&.
.UNINDENT
.INDENT 0.0
.TP
.B \-\-speed number
\fIDefault\fP: 1.0
.sp
Specifies a multiplier to adjust playback speed. \fB\-\-speed 1.0\fP
processes the playback file in real time; \fB\-\-speed 0.5\fP at half
speed; \fB\-\-speed 3.0\fP at triple speed.
.sp
The specified speed is a \fItarget\fP speed. If \fBmongoreplay play\fP encounters
a bottleneck, playback may be slower than the specified multiplier.
.UNINDENT
.INDENT 0.0
.TP
.B \-\-host <uri connection string>
\fIDefault\fP: mongodb://localhost:27017
.sp
Specifies a MongoDB connection string
for the MongoDB deployment to which to
play back the captured network traffic.
.sp
By default, \fI\%play\fP
attempts to connect to a \fBmongod\fP instance running on the localhost on
port number \fB27017\fP\&.
.sp
\fBNOTE:\fP
.INDENT 7.0
.INDENT 3.5
Starting in MongoDB 4.0, \fI\%mongoreplay play\fP supports a new
\fBMONGOREPLAY_HOST\fP environment variable that specifies the
connection string for the MongoDB deployment. The new environment
vairable can be used instead of the command\-line \fI\%\-\-host\fP option.
.sp
If \fI\%\-\-host\fP command\-line option is
specified, the \fI\%\-\-host\fP value overrides
the environment variable.
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B \-\-repeat number
\fIDefault\fP: 1
.sp
Specifies the number of times to play the playback file.
.UNINDENT
.INDENT 0.0
.TP
.B \-\-queueTime number
\fIDefault\fP: 15
.sp
Specifies the maximum time, in seconds, to queue operations in advance
of transmitting them.
.UNINDENT
.INDENT 0.0
.TP
.B \-\-no\-preprocess
When set, \fI\%play\fP does not preprocess the input file to pre\-map
data such as MongoDB cursor IDs.
.UNINDENT
.INDENT 0.0
.TP
.B \-\-gzip <boolean>
If specified, \fI\%play\fP decompresses the playback file with gzip.
.UNINDENT
.INDENT 0.0
.INDENT 3.5
.SS See
.sp
\fI\%Use play\fP for examples of using
\fI\%mongoreplay\fP with the \fI\%play\fP command.
.UNINDENT
.UNINDENT
.SS \fBmongoreplay monitor\fP
.sp
\fI\%monitor\fP inspects live or pre\-recorded
MongoDB network traffic.
.sp
The following prototype uses \fI\%mongoreplay\fP to produce a
JSON report based on the \fBplayback.bson\fP playback file in the \fB~/recordings\fP directory:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
mongoreplay monitor \-\-collect json \-\-report ~/reports/monitor\-report.json \-p ~/recordings/playback.bson
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
\fBmonitor\fP supports the following options:
.INDENT 0.0
.TP
.B mongoreplay monitor
.UNINDENT
.INDENT 0.0
.TP
.B monitor
.UNINDENT
.INDENT 0.0
.TP
.B \-\-collect <json|format|none>
\fIDefault\fP: format
.sp
Specifies the output format for the collected statistics.
.INDENT 7.0
.IP \(bu 2
\fBjson\fP: outputs stat information as json
.IP \(bu 2
\fBformat\fP: uses the formatting specified in the \fB\-\-format\fP option
to produce the output file.
.IP \(bu 2
\fBnone\fP: does not provide any output
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B \-\-report <path>
Specifies the path to which to write an execution report.
Use \fI\%\-\-collect\fP to specify the output format for the report.
.sp
If you do not specify \fB\-\-report\fP, \fI\%monitor\fP writes to STDOUT.
.UNINDENT
.INDENT 0.0
.TP
.B \-\-no\-truncate
If specified, disables truncation of large reply payload data in the
\fI\%monitor\fP log output.
.UNINDENT
.INDENT 0.0
.TP
.B \-\-format
\fIDefault\fP: \fB%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)\fP
.sp
Specifies the format for terminal output.
You can specify arguments immediately after the format \(aqverbs\(aq by wrapping
them in curly braces, as in \fB%Q{<arg>}\fP\&.
.sp
If you specify \fI\%\-\-format\fP, also specify \fBformat\fP as the value for the
\fI\%\-\-collect\fP option.
.sp
\fI\%\-\-format\fP supports the following verbs:
.INDENT 7.0
.IP \(bu 2
\fB%n\fP: namespace
.IP \(bu 2
\fB%l\fP: latency
.IP \(bu 2
\fB%t\fP: time. You may optionally specify the date layout using the
Go Programming Language\(aqs \fI\%time formatting\fP\&. Go
uses \fBMon Jan 2 15:04:05 MST 2006\fP as its reference time. You
must specify the time format using the reference time. Thus, if you
wanted to print the date in format \fByyyy\-mm\-dd hh:mm\fP, you would
specify \fB%t{2006\-01\-02 15:04}\fP\&. Refer to the Go \fI\%time formatting\fP
documentation for more information.
.IP \(bu 2
\fB%T\fP: op time
.IP \(bu 2
\fB%c\fP: command
.IP \(bu 2
\fB%o\fP: number of connections
.IP \(bu 2
\fB%i\fP: request ID
.IP \(bu 2
\fB%q\fP: request. You may optinally specified a dot\-delimited field
within the JSON structure, as in, \fB%q{command_args.documents}\fP\&.
.IP \(bu 2
\fB%r\fP: response. You may optinally specified a dot\-delimited field
within the JSON structure, as in, \fB%q{command_args.documents}\fP\&.
.IP \(bu 2
\fB%Q{<arg>}\fP: display \fB<arg>\fP on presence of request data
.IP \(bu 2
\fB%R{<arg>}\fP: display \fB<arg>\fP on presence of response data
.UNINDENT
.sp
In addition, \fI\%\-\-format\fP supports the following start/end ANSI escape sequences:
.INDENT 7.0
.IP \(bu 2
\fB%B\fP/\fB%b\fP: bold
.IP \(bu 2
\fB%U\fP/\fB%u\fP: underline
.IP \(bu 2
\fB%S\fP/\fB%s\fP: standout
.IP \(bu 2
\fB%F\fP/\fB%f\fP: text color (required arg \-\- word or number, 8\-color)
.IP \(bu 2
\fB%K\fP/\fB%k\fP: background color (required arg \-\- same as %F/%f)
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B \-\-no\-colors
When set, removes colors from the \fI\%default format\fP\&.
.UNINDENT
.INDENT 0.0
.TP
.B \-f <path>
Specifies the path to a pcap file that \fI\%monitor\fP should read to
produce a playback file.
.sp
Use \fB\-f\fP as an alternative to capturing network traffic using
\fB\-i\fP\&. You must specify \fIeither\fP \fB\-f\fP or \fB\-i\fP\&. If you include
both options, \fBmongoreplay monitor\fP produces an error.
.UNINDENT
.INDENT 0.0
.TP
.B \-b <number>
Size of heap used to merge separate streams together.
.UNINDENT
.INDENT 0.0
.TP
.B \-\-expr <filter expression>, \-e <filter expression>
An expression in \fI\%Berkeley Packet Filter (BPF) syntax\fP to apply to incoming traffic to
record. Required if you are capturing traffic from a network interface using
\fI\%\-i\fP\&.
.sp
For example, to capture traffic from a MongoDB instance running on
port 27017, you would specify \fB\-e \(aqport 27017\(aq\fP\&.
.UNINDENT
.INDENT 0.0
.TP
.B \-i <interface>
Specifies the network interface that \fI\%monitor\fP should listen on to
capture network traffic.
.sp
Use with \fI\%\-e\fP\&.
.sp
Use \fB\-i\fP as an alternative to reading an existing pcap file with
\fB\-i\fP\&. You must specify \fIeither\fP \fB\-f\fP or \fB\-i\fP\&. If you include
both options, \fBmongoreplay monitor\fP produces an error.
.UNINDENT
.INDENT 0.0
.TP
.B \-\-paired
When specified, \fI\%monitor\fP outputs one line for each request/reply pair record.
.UNINDENT
.INDENT 0.0
.TP
.B \-\-gzip <boolean>
If specified, \fI\%monitor\fP decompresses the playback file with gzip.
.UNINDENT
.INDENT 0.0
.TP
.B \-\-playback\-file <path>, \-p <path>
Specifies the path from which to read the playback file.
.UNINDENT
.INDENT 0.0
.INDENT 3.5
.SS See
.sp
\fI\%Use monitor\fP for examples of using
\fI\%mongoreplay\fP with the \fI\%monitor\fP command.
.UNINDENT
.UNINDENT
.SH MONGOREPLAY REPORT FORMAT
.sp
\fI\%monitor\fP and \fI\%play\fP can produce
reports based on a playback file when run with the \fB\-\-report\fP option.
.SS Sample Record
.sp
The following is an example record from a JSON\-formatted
\fI\%monitor\fP report:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
{
   "order" : 21,
   "op" : "op_msg",
   "command" : "aggregate",
   "ns" : "test",
   "request_data" : {
      "sections" : [
         {
            "payload" : {
               "$db" : "test",
               "aggregate" : "foo",
               "cursor" : {},
               "lsid" : {
                  "id" : {
                     "$binary" : "eBZNIaAbRTiAoWkaNZ0T8Q==",
                     "$type" : "04"
                  }
               },
               "pipeline" : [
                  { "$match" : { "borough" : "Queens" } },
                  { "$group" : { "_id" : "$cuisine", "count" : { "$sum": 1 } } }
               ]
            },
            "payloadType" : 0
         }
      ]
   },
   "connection_num" : 0,
   "seen" : "2018\-11\-15T14:07:07.136794\-05:00",
   "request_id" : 25
}
.ft P
.fi
.UNINDENT
.UNINDENT
.SS Fields
.sp
\fI\%mongoreplay\fP reports can include the following fields:
.INDENT 0.0
.TP
.B order
A monotonically increasing key indicating the order in which the
operations were recorded and played back. This can be used to
reconstruct the ordering of the series of operations executed on a
connection, since the order in which they appear in the report file
may not match the playback order.
.UNINDENT
.INDENT 0.0
.TP
.B op
The type of operation represented by the request: i.e. "query",
"insert", "command", "getmore".
.UNINDENT
.INDENT 0.0
.TP
.B command
The name of the database command performed, such as \fBisMaster\fP or
\fBgetLastError\fP\&. This field is left blank for operations that are not
commands, such as queries and inserts.
.UNINDENT
.INDENT 0.0
.TP
.B ns
The namespace on which the request was executed.
.UNINDENT
.INDENT 0.0
.TP
.B request_data
The payload of the operation.
.INDENT 7.0
.IP \(bu 2
Query operations: \fBrequest_data\fP contains the actual
query that was issued.
.IP \(bu 2
Insert operations: \fBrequest_data\fP contains the documents
being inserted.
.IP \(bu 2
Update operations: \fBrequest_data\fP contains the query
selector and the update modifier.
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B reply_data
The payload of the reply to the request.
.UNINDENT
.INDENT 0.0
.TP
.B nreturned
The number of documents returned as a result of the operation.
.UNINDENT
.INDENT 0.0
.TP
.B played_at
The time at which the \fI\%play\fP command executed
the operation.
.UNINDENT
.INDENT 0.0
.TP
.B play_at
The time at which the operation was supposed to be executed by
the \fI\%play\fP command.
.UNINDENT
.INDENT 0.0
.TP
.B playbacklag_us
The difference in microseconds in time between \fBplayed_at\fP
and \fBplay_at\fP\&. Higher values generally indicate that the
target server is not able to keep up with the rate at which requests
need to be executed according to the playback file.
.UNINDENT
.INDENT 0.0
.TP
.B connection_num
A key that identifies the connection on which the request was
executed. All requests/replies that executed on the same connection
have the same value for \fBconnection_num\fP\&.
.sp
The \fBconnection_num\fP value
does \fInot\fP match the connection ID logged on the server side.
.UNINDENT
.INDENT 0.0
.TP
.B latency_us
The time difference in microseconds between when the request was
sent by the client and when a response from the server was received.
.UNINDENT
.INDENT 0.0
.TP
.B errors
Lists any errors returned from the server.
.UNINDENT
.INDENT 0.0
.TP
.B msg
Lists the error message returned from the server.
.UNINDENT
.INDENT 0.0
.TP
.B seen
The time at which the operation was originally captured.
.UNINDENT
.INDENT 0.0
.TP
.B request_id
The ID of the MongoDB operation. The \fBrequest_id\fP for a request
operation is the same as the \fBresponse_id\fP for the corresponding
reply.
.UNINDENT
.SS Output Formatting with \fB\-\-format\fP
.sp
\fI\%monitor\fP and \fI\%play\fP output to either the
terminal or, when run with \fB\-\-report\fP (i.e. \fI\%monitor \-\-report\fP or \fI\%play \-\-report\fP), to a file.
.sp
Use the \fB\-\-collect\fP (\fI\%monitor \-\-collect\fP or \fI\%play \-\-collect\fP)
option to specify the format of the output:
.INDENT 0.0
.IP \(bu 2
\fB\-\-collect json\fP produces JSON output,
.IP \(bu 2
\fB\-\-collect format\fP outputs the data based on the formatting
specified by the \fB\-\-format\fP option for \fI\%monitor\fP and \fI\%play\fP .
.UNINDENT
.SH EXAMPLES
.SS Use \fI\%record\fP
.SS Capture TCP data with \fBrecord\fP
.sp
To create a recording of traffic, use the \fI\%record\fP command. The
following operation records traffic through port \fB27017\fP on the
\fBeth0\fP network interface and writes the captured traffic to
\fB~/recordings/recording.bson\fP:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
mongoreplay record \-i eth0 \-e "port 27017" \-p ~/recordings/recording.bson
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
The produced playback file contains everything needed to re\-execute
the workload on another system.
.SS Record a Playback File from Existing pcap Data
.sp
If you do not wish to use \fI\%mongoreplay\fP to capture traffic, you
can capture traffic using a utility such as \fBtcpdump\fP and then create a
\fI\%mongoreplay\fP recording from the static pcap file.
.sp
\fBWARNING:\fP
.INDENT 0.0
.INDENT 3.5
Only use root privileges when connecting to a trusted source.
.UNINDENT
.UNINDENT
.sp
The following operation uses \fBtcpdump\fP to capture traffic through
port \fB27017\fP on the \fBeth0\fP network interface and writes the captured
data to a pcap file called \fBtraffic.pcap\fP:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
sudo tcpdump \-B $((100*1024)) \-i eth0 \-n "port 27017" \-w traffic.pcap
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
To create the \fI\%mongoreplay\fP playback file, you can use
\fI\%record\fP with the \fI\%\-f\fP
option to specify the pcap file from which to create the playback file,
as in the following:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
mongoreplay record \-f traffic.pcap \-p ~/recordings/playback.bson
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
The produced playback file contains everything needed to re\-execute
the workload on another system.
.SS Use \fI\%play\fP
.SS Execute a Playback File Against a Target Host
.sp
\fI\%play\fP takes a playback file and executes the
recorded operations against the \fBmongodb://example.com:27018\fP host.
Since the \fBmongod\fP enforces authentication, the
connection string specified to
\fI\%\-\-host\fP also includes the username, password, and authentication
database so that \fI\%mongoreplay\fP can write to the database.
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
mongoreplay play \-p ~/recordings/recording.bson \-\-host mongodb://username:password@example.com:27018/admin
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
By default, \fB~bin.play\fP executes the playback
file at the rate of the recording. \fI\%\-\-speed\fP lets you modify
the playback speed. For example, the following operation executes
the operations in \fBrecording.bson\fP at twice the recording speed:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
mongoreplay play \-p ~/recordings/recording.bson \-\-speed=2.0 \-\-host mongodb://username:password@example.com:27018/admin
.ft P
.fi
.UNINDENT
.UNINDENT
.SS Log Metrics About Execution Performance during Playback
.sp
\fI\%play\fP can produce a report with detailed metrics
about the performance of each operation executed during playback.
.sp
The following example executes playback against the
\fBmongodb://example.com:27017\fP host and produces a JSON report written to
\fB~/reports/playback\-report.json\fP
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
mongoreplay play \-p ~/recordings/recording.bson \-\-report ~/reports/playback\-report.json \-\-collect json \-\-host mongodb://example.com:27017
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
The \fBplay\fP report contents would resemble:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
{
   "order" : 0,
   "op" : "op_msg",
   "command" : "isMaster",
   "ns" : "test",
   "request_data" : {
      "sections" : [
         {
            "payload" : {
               "$db" : "test",
               "forShell" : 1,
               "isMaster" : 1
            },
            "payloadType" : 0
         }
      ]
   },
   "reply_data" : {
      "sections" : [
         {
            "payload" : {
               "ismaster" : true,
               "localTime" : {
                  "$date" : "2018\-11\-15T21:35:01.843Z"
               },
               "logicalSessionTimeoutMinutes" : 30,
               "maxBsonObjectSize" : 16777216,
               "maxMessageSizeBytes" : 48000000,
               "maxWireVersion" : 7,
               "maxWriteBatchSize" : 100000,
               "minWireVersion" : 0,
               "ok" : 1,
               "readOnly" : false
            },
            "payloadType" : 0
         }
      ]
   },
   "played_at" : "2018\-11\-15T16:35:01.84304\-05:00",
   "play_at" : "2018\-11\-15T16:35:01.842903\-05:00",
   "playbacklag_us" : 137,
   "connection_num" : 1,
   "latency_us" : 151,
   "seen" : "2018\-11\-15T21:30:33.379675Z",
   "request_id" : 21
}
{
   "order" : 2,
   "op" : "op_msg",
   "command" : "listCollections",
   "ns" : "test",
   "request_data" : {
      "sections" : [
         {
            "payload" : {
               "$db" : "test",
               "authorizedCollections" : true,
               "filter" : {

               },
               "listCollections" : 1,
               "lsid" : {
                  "id" : {
                     "$binary" : "esmcqhiXSIWSpKGb4sOekw==",
                     "$type" : "04"
                  }
               },
               "nameOnly" : true
            },
            "payloadType" : 0
         }
      ]
   },
   "reply_data" : {
      "sections" : [
         {
            "payload" : {
               "cursor" : {
                  "firstBatch" : [ ],
                  "id" : {
                     "$numberLong" : "0"
                  },
                  "ns" : "test.$cmd.listCollections"
               },
               "ok" : 1
            },
            "payloadType" : 0
         }
      ]
   },
   "played_at" : "2018\-11\-15T16:35:08.715002\-05:00",
   "play_at" : "2018\-11\-15T16:35:08.713539\-05:00",
   "playbacklag_us" : 1463,
   "connection_num" : 1,
   "latency_us" : 331,
   "seen" : "2018\-11\-15T21:30:40.250311Z",
   "request_id" : 22
}
{
   "order" : 4,
   "op" : "op_msg",
   "command" : "isMaster",
   "ns" : "test",
   "request_data" : {
      "sections" : [
         {
            "payload" : {
               "$db" : "test",
               "forShell" : 1,
               "isMaster" : 1
            },
            "payloadType" : 0
         }
      ]
   },
   "reply_data" : {
      "sections" : [
         {
            "payload" : {
               "ismaster" : true,
               "localTime" : {
                  "$date" : "2018\-11\-15T21:35:08.715Z"
               },
               "logicalSessionTimeoutMinutes" : 30,
               "maxBsonObjectSize" : 16777216,
               "maxMessageSizeBytes" : 48000000,
               "maxWireVersion" : 7,
               "maxWriteBatchSize" : 100000,
               "minWireVersion" : 0,
               "ok" : 1,
               "readOnly" : false
            },
            "payloadType" : 0
         }
      ]
   },
   "played_at" : "2018\-11\-15T16:35:08.715554\-05:00",
   "play_at" : "2018\-11\-15T16:35:08.71471\-05:00",
   "playbacklag_us" : 844,
   "connection_num" : 1,
   "latency_us" : 208,
   "seen" : "2018\-11\-15T21:30:40.251482Z",
   "request_id" : 23
}
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Refer to \fI\%mongoreplay Report Format\fP for a description of each field.
.SS Use \fI\%monitor\fP
.SS Inspect Recorded Operations
.sp
\fI\%monitor\fP can create a report based on the
contents of a playback file. \fI\%monitor\fP\(aqs report includes
\fIall\fP operations and some metadata about each operation\(aqs execution.
.sp
The following operation uses \fI\%monitor\fP to create a JSON
report based on the contents of the \fBrecording.bson\fP playback file
located in the \fB~/recordings\fP directory and write the report to
\fB~/reports/monitoring\-report.json\fP:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
mongoreplay monitor \-p ~/recordings/recording.bson \-\-report ~/reports/monitoring\-report.json \-\-collect json
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
The report contents would resemble:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
{
   "order" : 0,
   "op" : "op_msg",
   "command" : "isMaster",
   "ns" : "test",
   "request_data" : {
      "sections" : [
         {
            "payload" : {
               "$db" : "test",
               "forShell" : 1,
               "isMaster" : 1
            },
            "payloadType" : 0
         }
      ]
   },
   "connection_num" : 0,
   "seen" : "2018\-11\-15T21:30:33.379675Z",
   "request_id" : 21
}
{
   "order" : 1,
   "op" : "op_msg",
   "command" : "aggregate",
   "ns" : "test",
   "request_data" : {
      "sections" : [
         {
            "payload" : {
               "$db" : "test",
               "aggregate" : "restaurants",
               "cursor" : {

               },
               "lsid" : {
                  "id" : {
                     "$binary" : "esmcqhiXSIWSpKGb4sOekw==",
                     "$type" : "04"
                  }
               },
               "pipeline" : [
                  {
                     "$match" : {
                        "borough" : "Manhattan"
                     }
                  },
                  {
                     "$group" : {
                        "_id" : "$cuisine"
                     }
                  }
               ]
            },
            "payloadType" : 0
         }
      ]
   },
   "connection_num" : 0,
   "seen" : "2018\-11\-15T16:28:52.870007\-05:00",
   "request_id" : 13
}
{
   "order" : 1,
   "op" : "op_msg",
   "command" : "reply",
   "reply_data" : {
      "sections" : [
         {
            "payload" : {
               "ismaster" : true,
               "localTime" : {
                  "$date" : "2018\-11\-15T21:30:33.379Z"
               },
               "logicalSessionTimeoutMinutes" : 30,
               "maxBsonObjectSize" : 16777216,
               "maxMessageSizeBytes" : 48000000,
               "maxWireVersion" : 7,
               "maxWriteBatchSize" : 100000,
               "minWireVersion" : 0,
               "ok" : 1,
               "readOnly" : false
            },
            "payloadType" : 0
         }
      ]
   },
   "connection_num" : 0,
   "latency_us" : 174,
   "seen" : "2018\-11\-15T21:30:33.379849Z",
   "request_id" : 21
}
{
   "order" : 2,
   "op" : "op_msg",
   "command" : "listCollections",
   "ns" : "test",
   "request_data" : {
      "sections" : [
         {
            "payload" : {
               "$db" : "test",
               "authorizedCollections" : true,
               "filter" : {

               },
               "listCollections" : 1,
               "lsid" : {
                  "id" : {
                     "$binary" : "esmcqhiXSIWSpKGb4sOekw==",
                     "$type" : "04"
                  }
               },
               "nameOnly" : true
            },
            "payloadType" : 0
         }
      ]
   },
   "connection_num" : 0,
   "seen" : "2018\-11\-15T21:30:40.250311Z",
   "request_id" : 22
}
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Refer to \fI\%mongoreplay Report Format\fP for a description of each field.
.SS Inspect Live MongoDB Traffic
.sp
\fI\%monitor\fP can also inspect live traffic and, optionally,
create a report based on the observed operations.
.sp
To monitor traffic in real time in your terminal, omit the
\fI\%\-\-report\fP option, as in the
following:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
mongoreplay monitor \-i eth0 \-e \(aqport 27017\(aq \-\-collect json
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Optionally, you can create a report based on the operations observed
using \fI\%monitor\fP\&. The following example creates a JSON
report written to \fB~/reports/monitor\-live.json\fP based on the traffic
through port \fB27017\fP on the \fBeth0\fP network interface:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
mongoreplay monitor \-i eth0 \-e \(aqport 27017\(aq \-\-report ~/reports/monitor\-live.json \-\-collect json
.ft P
.fi
.UNINDENT
.UNINDENT
.SH AUTHOR
MongoDB Documentation Project
.SH COPYRIGHT
2008-2019
.\" Generated by docutils manpage writer.
.