graphsignal-context

name	graphsignal-context
description	Fetch Graphsignal signal summary and signal context via the graphsignal-context CLI. Use when the user needs a performance summary or findings, signal context, time-range queries for signals/profiles/errors, signal guide content, or CLI access to the context APIs.

graphsignal-context commands

Fetch signal summary, signal context, and signal guide content from Graphsignal (api.graphsignal.com).

When to use

• User asks for Graphsignal signal context, signal output, or time-range data.
• User wants to inspect signals, profiles, or errors for a specific window.
• User wants a quick performance summary, bottleneck findings, or flag recommendations for an inference workload.
• User needs to call the signal_context API from the command line or from agent workflows.

Prerequisites

1. Install (from PyPI):

   pip install graphsignal-context
   

2. Login (once). API key is stored in ~/.graphsignal/config.yml:

   graphsignal-context login
   

   Alternatively, set GRAPHSIGNAL_API_KEY in the environment; the CLI uses it if present.

If not logged in, summary, signals, and guide exit with: "Not logged in. Run: graphsignal-context login".

Command

graphsignal-context summary --start <ISO8601> --end <ISO8601> --tags "run.uid:<uid>[;key:value;...]"

Fetch the pre-computed, scalar-only signal summary (performance analysis) for the time range: engine (name/version, model, startup flags, plus all engine metrics reduced to scalars with rising/flat/falling trend hints), host (info plus host.* metrics), traffic (tokens, latency percentiles, concurrency, KV cache), GPU (time by kernel class, memory usage/headroom per device, plus all NVML metrics reduced to scalars), prefill/decode phases, per-GPU imbalance, rule-generated bottleneck findings with descriptions, anomalies, and grouped errors. Same options as signals. Start here — it is small and already reduced; fetch full signals context only to drill down or verify a finding.

The summary describes a single engine run: --tags must include the run.uid tag, otherwise the API returns an error. run.uid is set automatically by the profiler per engine process launch; find values in meta.available_tags of a signals response. The companion workload_command_hash tag is shared by all runs of the same workload command — use it to find previous runs of the same configuration (e.g. before/after flag comparisons).

The CLI calls GET https://api.graphsignal.com/api/v1/context/summary/ with start_time_ns, end_time_ns, and tags (must include run.uid), and prints the response summary field as JSON.

Command

graphsignal-context signals --start <ISO8601> --end <ISO8601> [--tags "key:value;..."]

• --start (required): Start of time range, ISO 8601 with Z (UTC). Example: 2026-03-10T00:00:00Z.
• --end (required): End of time range, same format. Must be after --start.
• --tags (optional): Filter by tags; semicolon-separated key:value pairs. Example: env:prod;service:api. Tags must be known exactly—they are the same tags emitted by the Graphsignal Profiler (e.g. set via GRAPHSIGNAL_TAG_<KEY>=<value> when launching graphsignal-run or graphsignal.watch()).

The CLI calls GET https://api.graphsignal.com/api/v1/context/signals/ with start_time_ns, end_time_ns, and optional tags, and prints the response context field.

Command

graphsignal-context guide

Fetch guide content about signals and print it to stdout.

The CLI calls GET https://api.graphsignal.com/api/v1/context/guide/ and prints the returned text content.

Examples

# Full signal context for the last two days (adjust dates to your window);
# meta.available_tags in the response lists run.uid values
graphsignal-context signals --start 2026-03-10T00:00:00Z --end 2026-03-12T00:00:00Z

# Performance summary for one engine run (run.uid required)
graphsignal-context summary --start 2026-03-10T00:00:00Z --end 2026-03-12T00:00:00Z --tags "run.uid:1a2b3c4d5e6f"

Agent workflow

1. For performance questions (bottlenecks, latency, GPU utilization, flag recommendations), run graphsignal-context summary first with the appropriate --start and --end (ISO 8601 UTC), always passing the required run tag (--tags "run.uid:<uid>"; find values in meta.available_tags of a signals response) — the API returns an error without it. Check meta.source_signals to see which underlying signals were available. Its findings are rule-generated bottleneck hypotheses with scalar evidence — verify them before acting; null means not measured, 0 means measured zero. The top-level metrics map contains every collected metric series reduced to scalars with trend hints and a source of engine / gpu / host / process — use it for anything the named sections don't cover (queue depth, generation throughput plateaus, memory-bandwidth utilization, power).
2. Run graphsignal-context signals for the same window when you need full-resolution data: to verify a summary finding, walk profile timelines/traces/metrics, or answer a question the summary doesn't cover.
3. If the user needs general guide content about signals, run graphsignal-context guide.
4. If a command fails with "Not logged in", tell the user to run graphsignal-context login or set GRAPHSIGNAL_API_KEY.
5. Use the signals output JSON to answer questions about profiles, errors, traces, or metrics in that window.
6. The signals response includes meta.available_tags — all metric tag keys with their most recent values. Use these to re-fetch with --tags for a specific host, process, GPU device, etc. when you need more targeted optimization (e.g. --tags "host.name:gpu-server-01" or --tags "device.index:0").