Navigation
This is an upcoming (i.e. in progress) version of the manual.

startRecordingTraffic

Definition

startRecordingTraffic

New in version 4.2.

Starts the MongoDB traffic recorder on the mongod or mongos instance. The recorder captures all incoming wire protocol traffic to the instance (and the corresponding responses) and outputs to a specified file.

Important

To enable startRecordingTraffic, the trafficRecordingDirectory parameter must be set on start-up.

Warning

The recording file contains unencrypted user traffic information. If possible, limit the retention of this file.

The command has the following form:

db.runCommand( { startRecordingTraffic: 1, filename: <string>, bufferSize: <int64>, maxFileSize: <int64>} )

The startRecordingTraffic command can take the following optional fields:

Field Type Description
filename string

The name of the output file for the recorder. The file is located in the trafficRecordingDirectory.

Warning

The recording file contains unencrypted user traffic information. If possible, limit the retention of this file.

If a file with the same name exists in the trafficRecordingDirectory, the recorder overwrites the file.

bufferSize long

Optional. The maximum size of the in-memory buffer for traffic records in bytes.

The default size is 128MiB.

maxFileSize long

Optional. The maximum size of the output file in bytes.

The default size is 4GiB.

To stop the traffic recorder, use the stopRecordingTraffic command.

Behavior

The recorder may encounter errors when running. For example:

  • If the recorder exceeded the maximum size for the output file.
  • If the recorder exceeded the maximum size of the in-memory buffer for traffic records.
  • If the recorder encountered an I/O error.

However, these errors will not be reported until stopRecordingTraffic stops the recorder. The stopRecordingTraffic stops the recorder and reports on errors that may have occurred during the recording.

To view statistics on the traffic recorder, run db.serverStatus() while the recorder is running to see trafficRecording metrics.

Required Access

When running with access control, the user must have the trafficRecord privilege action on the cluster resource. That is, the user must have a role that grants the following privilege:

{ resource: { cluster: true }, actions: [ "trafficRecord" ] }

The built-in hostManager role provides the required privileges.

Example

The following example begins recording all traffic to the mongod/mongos instance as well as the instance’s responses to that traffic.

db.runCommand( { startRecordingTraffic: 1, filename: "output.txt" } )

Warning

The recording file contains unencrypted user traffic information. If possible, limit the retention of this file.

To stop recording, run the stopRecordingTraffic command:

db.runCommand( { stopRecordingTraffic: 1 } )