Skip to main content

Record and Inspect Live Traffic

Overview​

This guide explains how to observe live traffic flowing through your sandboxes in real-time. Understanding actual request and response payloads is essential before making API changes, especially when documentation is outdated or incomplete.

Before you can change an API, you need to understand it. Stale documentation and out-of-date OpenAPI specs don't provide the full picture of how services actually communicate in your system.

Requirements

This feature requires Signadot CLI v1.3.0+ and Signadot Operator v1.2.0+ on your cluster.

Prerequisites​

  • Signadot CLI installed and authenticated
  • An existing sandbox that you have access to (can contain fork, virtual, or local workloads)
tip

Use virtual workloads to record baseline traffic at near zero cost without creating actual service forks.

Implementation Steps​

1. Record Live Traffic​

Use the signadot traffic record command to capture request and response payloads:

signadot traffic record --sandbox alice-traffic-observation

This command:

  • Temporarily alters the sandbox to add traffic recording middleware
  • Captures all HTTP and gRPC traffic destined for the sandbox
  • Removes the changes upon termination
  • Provides a passive, read-only view into live system behavior

For interactive inspection while recording:

signadot traffic record --sandbox alice-traffic-observation --inspect

The --inspect flag launches an interactive TUI (text user interface) to browse traffic in real-time.

You can control where and how traffic is recorded:

# Specify custom output directory
signadot traffic record --sandbox my-sandbox --out-dir ./custom-traffic

# Clean previous recordings before starting new one
signadot traffic record --sandbox my-sandbox --clean

# Record only activity log without full request/response data
signadot traffic record --sandbox my-sandbox --short --to-file activity.json

By default, traffic record appends to existing data, allowing you to collect traffic from different sandboxes over time.

2. Working with Recorded Data​

Recorded traffic is stored in the file system in a human-readable format. You can:

Inspect interactively: Use signadot traffic inspect to browse recorded traffic in an interactive TUI:

signadot traffic inspect

Build automation: Directly read the request/response files to build automation, such as:

  • Creating tests from recorded traffic
  • Generating API documentation
  • Replaying requests for debugging
  • Comparing traffic between different versions

See the CLI reference for details on the traffic data format.

Common Use Cases​

  • Understanding API behavior: Observe actual request/response payloads to understand how services communicate, beyond what documentation claims
  • Validating changes: Record baseline traffic before changes, then compare with traffic after changes to validate behavior
  • Debugging integration issues: Inspect traffic to identify mismatches between expected and actual payloads
  • Onboarding: Help new team members understand service dependencies by observing real interactions

Advanced Patterns​

Recording Baseline Traffic with Virtual Workloads​

Use virtual workloads in your sandbox to record baseline traffic at near zero cost without creating service forks:

name: "baseline-traffic-recording"
spec:
  cluster: "staging-cluster"
  ttl:
    duration: 24h
  description: "Recording baseline traffic for order service"
  virtual:
  - workload:
      kind: Deployment
      namespace: "backend"
      name: "order-service"

Advantages:

  • Zero resource overhead: Virtual workloads don't create new pods, they simply point to the existing baseline service
  • Cost-effective: No additional compute resources required for traffic recording
  • Production-like traffic: Captures real traffic patterns without service modifications
  • Safe observation: Read-only view with no risk of impacting baseline service behavior

This is ideal for understanding current API behavior before making changes, or for long-running traffic collection to build test suites.

Conclusion​

Recording and inspecting live traffic provides essential visibility into how your services actually communicate. This approach eliminates reliance on outdated documentation and reveals actual API behavior in real scenarios without requiring service mesh expertise.

Use traffic recording as a standard practice when working with APIs to build a deeper understanding of your system and make more confident changes.

See Also​