Profiler API

Graphsignal observes your workload from a sidecar process — the profiler. It never shares an address space with CUDA. There are two ways to start it: the graphsignal-run CLI (see the Quick Start) and the graphsignal.watch() function documented below.

watch

watch(otel_collector_port: Optional[int] = None) -> Optional[subprocess.Popen]

Spawn the profiler sidecar to observe the current process.

watch() does two things:

Sets up the CUPTI environment variables (CUDA_INJECTION64_PATH, LD_LIBRARY_PATH) in the current process so the CUPTI injection library attaches when CUDA initializes.
Spawns the profiler subprocess targeting the current PID.

It must be called before any CUDA work happens in the current process. The returned Popen object lets the caller wait() or terminate() the sidecar.

import graphsignal

graphsignal.watch()
# ... your application code (PyTorch, vLLM, SGLang, etc.) ...

Arguments:

otel_collector_port: Optional TCP port for a local OTLP/gRPC collector that the sidecar will start. If your workload exports OTEL traces, point them at localhost:<otel_collector_port> so the profiler receives them. If omitted, no collector is started.

Returns:

subprocess.Popen for the spawned sidecar process, or None if the spawn failed.

Environment variables

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

Variable	Purpose
`GRAPHSIGNAL_API_KEY` (required)	Your account API key.
`GRAPHSIGNAL_API_BASE`	Override 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.