Skip to content
Graphsignal Docs

Profiler CLI

Graphsignal observes your workload from a sidecar process — the profiler. It never shares an address space with CUDA. graphsignal-run launches a workload with the profiler attached.

Install the CLI as an isolated uv tool so it doesn’t pollute the workload environment:

Terminal window
uv tool install 'graphsignal[cu12]'   # CUDA 12.x
# or
uv tool install 'graphsignal[cu13]'   # CUDA 13.x

This puts graphsignal-run on your PATH. The CUPTI injection library ships inside the wheel and the launcher references it by absolute path, so the workload doesn’t need Graphsignal installed in its own environment.

graphsignal-run

Section titled “graphsignal-run”

Wrap any launch command. graphsignal-run spawns the profiler sidecar, sets up CUPTI injection in the environment, and then execs the workload — replacing itself with the target so process management (init systems, container runtimes, etc.) sees only the workload.

Terminal window
graphsignal-run <command> [args...]

Examples:

Terminal window
graphsignal-run vllm serve <model> --port 8001
graphsignal-run python -m sglang.launch_server --model-path <model>
graphsignal-run python myapp.py
graphsignal-run app.py

Behavior:

  • Selects a built-in launcher based on the command (vLLM, SGLang, TensorRT-LLM, or a generic fallback).
  • For OTEL-aware workloads (vLLM, SGLang), injects flags to export traces to a local OTLP/gRPC port managed by the sidecar.
  • Sets CUDA_INJECTION64_PATH to the bundled libgscuptiprof.so so CUPTI activity records are produced as soon as CUDA initializes.
  • execs the workload after the sidecar is spawned in a new session (the sidecar survives the exec).

The profiler reads its configuration from environment variables. Set these before invoking graphsignal-run (or before calling graphsignal.watch()).

VariablePurpose
GRAPHSIGNAL_API_KEY (required)Your account API key.
GRAPHSIGNAL_API_BASEOverride the API endpoint (defaults to https://api.graphsignal.com).
GRAPHSIGNAL_TAG_<KEY>=<value>Arbitrary tag attached to all signals (e.g. GRAPHSIGNAL_TAG_DEPLOYMENT=us-prod).

To get an API key, sign up for a free account at graphsignal.com; the key is in Settings / API Keys.