Flow Commands
The sbn-media flow command tree queries the flow log store and the live flow event stream for cross-service call and session tracing. It answers "what happened to trace ID X" without shell access to the host.
Local invocations talk directly to the Flow Server over NATS. Remote invocations (-e/--environment) go through the API Proxy over HTTPS instead, so a support engineer's workstation never needs a NATS connection to the target deployment — only the API proxy URL and a token.
Remote environments (-e)
Every subcommand below that touches live data accepts -e <environment> to target a remote deployment instead of the local broker. Environments are declared under diagnose.environments.<name> in the configuration:
An environment entry needs the server address and a token issued for that deployment. With the entry in place, -e staging routes the command over HTTPS to that deployment.
Subcommands
Command | Purpose |
|---|---|
| Print all flow entries for a trace ID |
| Print SIP wire-level messages for a trace ID |
| Search flow traces by device, service, time, or text |
| Print raw log lines correlated to a trace ID |
| Live-stream flow entries as they arrive |
| Show a flow statistics dashboard |
| Interactive terminal UI for browsing flow traces |
trace
Fetch and print the flow log entries for a given trace ID.
Flag | Short | Description |
|---|---|---|
|
| Remote environment (routes via the API proxy over HTTPS; otherwise uses local NATS) |
Without --environment, the command publishes a NATS request directly to the local Flow Server. With --environment, the request goes over HTTPS to that deployment's API proxy /api/flow/trace/{traceId} endpoint.
sip
Fetch and print the SIP wire-level messages for a given trace ID.
Flag | Short | Description |
|---|---|---|
|
| Remote environment |
|
| Show full SIP message body (headers + SDP) |
Multi-leg calls are resolved transitively via RelatedCallID, so a B2BUA scenario (for example, a callback that hairpins through a second leg) shows messages from every linked call leg, not just the one matching the trace ID.
search
Search for flow traces matching the given filters.
Flag | Description |
|---|---|
| Filter by device ID |
| Filter by service name |
| Substring match on entry body |
| Show only traces with errors |
| Lookback window (for example |
| Max results (default |
| Remote environment |
Returns one summary line per trace: timestamp, trace ID, services involved, error flag, and duration. Use this when you don't have a trace ID yet — for example, narrowing down which trace belongs to a reported call by device or time window.
logs
Fetch and print the raw log lines that share the given trace ID.
Flag | Short | Description |
|---|---|---|
| Filter by service name | |
| Filter by log level (for example | |
|
| Show all fields, suppressing repeated values from the previous line |
|
| Remote environment |
By default only high-signal fields (status, direction, payload, error) are shown inline. Use this as the fallback when flow trace and flow sip don't carry enough context and you need the underlying log lines themselves.
tail
Stream flow log entries in real time.
Flag | Description |
|---|---|
| Filter by device ID |
| Filter by service name |
| Remote environment |
Uses NATS locally, or server-sent events over HTTPS when --environment is set. Press Ctrl-C to stop. Useful for watching a reproduction live instead of retro-fetching a trace after the fact.
stats
Show a compact dashboard with trace counts, error counts, slowest traces, and noisiest devices for a given time window.
Flag | Description |
|---|---|
| Lookback window in hours (default |
| Remote environment |
ui
Launch a three-pane interactive terminal UI for browsing, searching, and live-tailing flow traces.
Flag | Short | Description |
|---|---|---|
|
| Remote environment |
Uses NATS locally, or HTTPS when --environment is set. Prefer this over chaining search/trace/sip by hand when exploring an unfamiliar incident interactively.
Relationship to log trace and log flow
The older sbn-media log trace and sbn-media log flow commands read the plain-text service log files directly and predate the flow store. They still work and remain useful when a host's flow data hasn't been ingested yet, but flow trace, flow sip, and flow search are the preferred path for remote support use because they don't require log-file access on the target host — only the API proxy endpoint.