Quick Start
Install
Section titled “Install”UV_TOOL_BIN_DIR=/usr/local/bin uv tool install 'graphsignal[cu12]' # CUDA 12.x# orUV_TOOL_BIN_DIR=/usr/local/bin uv tool install 'graphsignal[cu13]' # CUDA 13.xAlternative: install into your workload environment
Section titled “Alternative: install into your workload environment”If you prefer a single environment, or you use the graphsignal.watch() Python API (which requires graphsignal importable by your application), install it directly into your workload’s environment instead:
pip install 'graphsignal[cu12]' # CUDA 12.x# orpip install 'graphsignal[cu13]' # CUDA 13.xProfile
Section titled “Profile”Wrap your launch command with graphsignal-run:
export GRAPHSIGNAL_API_KEY=<my-api-key>graphsignal-run vllm serve <model> --port 8001Environment variables read by the profiler:
| Variable | Purpose |
|---|---|
GRAPHSIGNAL_API_KEY (required) | Your account API key. |
GRAPHSIGNAL_TAG_<KEY>=<value> | Arbitrary tag attached to all signals (e.g. GRAPHSIGNAL_TAG_DEPLOYMENT=us-prod). |
Sign up for a free account at graphsignal.com; you’ll find the API key in Settings / API Keys.
See the Profiler CLI reference for the full set of options.
Applications that bootstrap themselves can call graphsignal.watch() from Python instead — see the Profiler API reference.
See integration documentation for libraries and inference engines:
Optimize
Section titled “Optimize”Log in to Graphsignal to monitor and analyze your application.
Optimize with AI
Section titled “Optimize with AI”Install the Graphsignal skill to let your AI coding agent (Claude Code, Codex, or Gemini) fetch and analyze signal context directly from your agent. See AI Optimization for setup instructions.
Overhead
Section titled “Overhead”The profiler has minimal impact on production performance. CUDA kernel activity is collected via CUPTI with low-overhead APIs, and analysis and upload happen in the sidecar process.
Security and Privacy
Section titled “Security and Privacy”The profiler runs as a sidecar process and does not require root or elevated privileges. It only establishes outbound connections to api.graphsignal.com to send data; inbound connections or commands are not possible.
Content and sensitive information, such as prompts and completions, are not recorded.
See Security and Privacy for details.
Troubleshooting
Section titled “Troubleshooting”If something doesn’t look right, report it to our support team via your account.
In case of connection issues, please make sure outgoing connections to https://api.graphsignal.com are allowed.