Skip to main content

signadot traffic

Note

The examples here work with v1.3.0+ of the Signadot CLI and require Operator v1.2.0+ on associated clusters.

The traffic command lets you record and inspect the requests and responses of traffic destined for a sandbox.

Recording Traffic​

To record traffic destined for a sandbox on runs the traffic record command:

signadot traffic record --sandbox <sandbox-name> [ --inspect ]

traffic record will by default temporarily alter the sandbox, adding, or setting the trafficwatch middleware with the desired values if necessary. Upon termination, it will remove any changes it made. Moreover, if the configuration of the trafficwatch middleware changes during a session, the command will terminate with an error reporting what differences came about.

When traffic record is run with --inspect, the traffic inspect TUI is launched instead of just showing logs of requests.

--clean​

By default traffic record records data to a directory in append mode, so that one may collect traffic from different sandboxess over time for further processing, such as debugging analysis, replaying requests or generating tests. To manage what data is kept and what is not, traffic watch provides a --clean flag, which will cause it to erase any pre-existing traffic prior to recording new traffic.

The directory in which traffic is recorded may be set with --out-dir.

Note

traffic record can easily record baseline traffic at near zero cost with virtual workloads

Inspecting Traffic​

Running the traffic inspect command will launch a TUI browser of the recorded traffic

signadot traffic inspect

One can also directly access the recorded traffic which are stored in a human-readable format described below.

Traffic Format​

The format in which recorded traffic is saved consists of a log of request/response activity and a directory for each request/response pair.

Activity Log​

The activity log consists of a JSON or YAML stream, where each entry refers to a single request/response communication by an id called middlewareRequestID. This identifier is a unique descriptor for requests flowing through sandbox middleware.

There are two kinds of entries for each request. The first entry is sent when the request first enters the trafficwatch middleware in your cluster:

{
  "middlewareRequestID": "f482a6f5",
  "when": "2025-10-24T15:16:53.538428008Z",
  "routingKey": "rwn8f3rf3flww",
  "destWorkload": "Deployment/hotrod-devmesh/location",
  "proto": "HTTP/1.1",
  "method": "GET",
  "host": "location.hotrod-devmesh.svc:8081",
  "requestURI": "http://location.hotrod-devmesh.svc:8081/",
  "userAgent": "curl/8.7.1",
  "watchOptions": "+stream/+stream"
}

The second entry records when the request/response has completed being brokered to traffic record clients by the Signadot control plane:

{
  "middlewareRequestID": f482a6f5,
  "doneAt": "2025-10-24T17:16:53.651051+02:00"
}
  • The time stamps are in RFC3339Nano format.
  • The destWorkload is in the format <kind>/<namespace>/<name>.
  • The proto:, method:, and requestURI fields are taken from the wire format of the request.
  • The watchOptions: field gives the watch options associated with the request, which may differ from the watch options provided to the CLI.

Request/Response Directory​

Each request/response directory is named by its middleware request id and contains 3 files

  • meta.json (or meta.yaml if -o yaml is specified)
  • request
  • response

meta.json contains the same main log entry as in the activity log. However rather than having 2 objects, when the request has completed, the main entry will also contain the doneAt field:

middlewareRequestID: f482a6f5
when: "2025-10-24T15:16:53.538428008Z"
routingKey: rwn8f3rf3flww
destWorkload: Deployment/hotrod-devmesh/location
doneAt: "2025-10-24T17:16:53.651051+02:00"
proto: HTTP/1.1
method: GET
host: location.hotrod-devmesh.svc:8081
requestURI: http://location.hotrod-devmesh.svc:8081/
userAgent: curl/8.7.1
watchOptions: +stream/+stream

The request and response files contain the wire format of the request and responses, including the HTTP protocol line, headers and body. The wire format is precise for the protocol line and message bodies. The headers are reconstructed via Go's http.Header.Write. These files are written as streams in real time as the communication of the watched in-cluster request occurs.

--short Usage​

When run with --short and --to-file, only the log of request/response activity is produced, and there are no directories associated with each request/response pair. In this case, the output goes to the specified file, clobbering any pre-existing data in that file.

Watch Options​

Watch Options describe what information about a request/response pair is communicated. The caller of signadot traffic record specifies watch options as a function of the provided flags. By default all data is streamed in real time.

The options are in the form <header-options><body-options>/<header-options><body-options>. Before the /, we have the request options and after the / we have the response options.

Header Options​

The header options may either be + or -, meaning record (or not) the protocol line and headers of the message.

Body Options​

The body options may either be stream or trunc(<n>). If it is stream, that means stream the payload in real time. If it is trunc(<n>), that means stream the first n bytes of the data in real time.

Limitations/Known Bugs​

Currently, traffic record often truncates large messages.

Considerations​

Latency Costs​

It is inevitable that rendering traffic observable will incur some latency costs on the completion of requests. As a result, traffic watch has limited capabilities to report on performance. The degree to which this is the case depends on many factors including the load of the cluster in which the watched request occurs.

Best Effort​

Traffic record is best effort only. Priority is always given to completing the request being watched in the event of errors or delays in the traffic watch machinery on the path from the cluster to your workstation.

Inactivity Timeouts​

If traffic record runs without any traffic for a substantial period of time, our servers will automatically close the connection. As traffic watch usage patterns are discovered, we reserve the right to change the delay which triggers a connection closure.

CI Overwrites​

Often sandboxes are used in CI flows, and traffic record is a useful tool for debugging CI behavior. However, CI itself is often set up to overwrite sandboxes upon each commit. This can lead to a scenario in which the changes made to the sandbox by traffic record disappear. This scenario is detected by traffic record and will cause it to exit reporting the error.

Watch Options​

Although it seems unlikely or even counter-intuitive, it is possible for a traffic watch client to receive a message with different watch options than requested, for example if the middleware for the sandbox ends up with a different configuration or if a middleware config is injected into a message header.