Metadata-Version: 2.4
Name: graphsignal
Version: 0.19.5
Summary: Graphsignal SDK for Python
License: Apache-2.0
License-File: LICENSE
License-File: NOTICE
Keywords: LLM observability,LLM analytics,Agent observability,Agent analytics
Author: Graphsignal, Inc.
Author-email: devops@graphsignal.com
Requires-Python: >=3.9,<4
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Scientific/Engineering
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Software Development
Classifier: Topic :: System :: Monitoring
Provides-Extra: cu12
Provides-Extra: cu13
Requires-Dist: grpcio
Requires-Dist: nvidia-cuda-cupti (>=13,<14) ; (sys_platform == "linux") and (extra == "cu13")
Requires-Dist: nvidia-cuda-cupti-cu12 (>=12,<13) ; (sys_platform == "linux") and (extra == "cu12")
Requires-Dist: nvidia-ml-py (>=12)
Requires-Dist: opentelemetry-api
Requires-Dist: opentelemetry-exporter-otlp
Requires-Dist: opentelemetry-proto
Requires-Dist: opentelemetry-sdk
Requires-Dist: opentelemetry-semantic-conventions-ai
Requires-Dist: protobuf
Requires-Dist: pydantic (>2)
Requires-Dist: python-dateutil
Requires-Dist: requests
Requires-Dist: typing-extensions (>4.7.1)
Requires-Dist: urllib3 (>=1.25.3,<3)
Requires-Dist: xxhash
Project-URL: Homepage, https://graphsignal.com
Project-URL: Repository, https://graphsignal.com
Description-Content-Type: text/markdown

# Graphsignal: Inference Observability

[![License](http://img.shields.io/github/license/graphsignal/graphsignal-python)](https://github.com/graphsignal/graphsignal-python/blob/main/LICENSE)
[![Version](https://img.shields.io/github/v/tag/graphsignal/graphsignal-python?label=version)](https://github.com/graphsignal/graphsignal-python)


Graphsignal is an inference observability platform that helps developers accelerate and troubleshoot AI systems. It provides essential visibility across the inference stack, including:

* Continuous, high-resolution profiling timelines exposing operation durations and resource utilization across inference workloads.
* LLM generation tracing with per-step timing, token throughput, and latency breakdowns for major inference frameworks.
* System-level metrics for inference engines and hardware (CPU, GPU, accelerators).
* Error monitoring for device-level failures, runtime exceptions, and inference errors.
* AI debugging to explain performance data and errors, identify bottlenecks, and recommend optimizations across the inference stack.

[![Dashboards](https://graphsignal.com/external/screenshot-dashboard.png)](https://graphsignal.com/)

Learn more at [graphsignal.com](https://graphsignal.com).


## Install

Install the Graphsignal library.

```bash
pip install -U graphsignal
```

**GPU profiling (Linux):** For CUPTI-based GPU profiling, install the extra matching your CUDA version: `pip install graphsignal[cu12]` (CUDA 12.x) or `pip install graphsignal[cu13]` (CUDA 13.x).


## Configure

Configure the Graphsignal SDK by specifying your API key directly or via the `GRAPHSIGNAL_API_KEY` environment variable.

```python
import graphsignal

graphsignal.configure(api_key='my-api-key')
# or pass the API key via the GRAPHSIGNAL_API_KEY environment variable
```

See [`configure()`](https://graphsignal.com/docs/reference/python-api/#graphsignalconfigure) API docs for all configuration parameters.


To get an API key, sign up for a free account at [graphsignal.com](https://graphsignal.com). The key can then be found in your account's [Settings / API Keys](https://app.graphsignal.com/settings/api-keys) page.

Alternatively, you can use the Graphsignal runner when running your application. Pass the API key via the `GRAPHSIGNAL_API_KEY` environment variable.

```bash
graphsignal-run <my-app>
```


## Integrate

Graphsignal works automatically and also provides an API for manual tracing and profiling. It captures performance profiles, traces, metrics, and errors. All insights are available for analysis at [app.graphsignal.com](https://app.graphsignal.com/).

Refer to the guides below for detailed information on:

* [Manual Tracing](https://graphsignal.com/docs/guides/manual-tracing/)
* [Manual Profiling](https://graphsignal.com/docs/guides/manual-profiling/)
* [Using Tags](https://graphsignal.com/docs/guides/using-tags/)

See integration documentation for libraries and inference engines:

* [PyTorch](https://graphsignal.com/docs/integrations/pytorch/)
* [vLLM](https://graphsignal.com/docs/integrations/vllm/)
* [SGLang](https://graphsignal.com/docs/integrations/sglang/)

See the [API reference](https://graphsignal.com/docs/reference/python-api/) for complete documentation.


## Analyze

[Log in](https://app.graphsignal.com/) to Graphsignal to monitor and analyze your application.


## Debug with AI

Install the Graphsignal skill to let your AI coding agent (Cursor, Claude Code, Codex, or Gemini) fetch and analyze debug context directly from your IDE. See [AI Debugging](https://graphsignal.com/docs/guides/ai-debugging/) for setup instructions.


## Overhead

The SDK has no impact on production performance that needs to be considered. Profiling uses low-overhead profiling APIs, so it runs with minimal impact on your code. Tracing is lightweight—overhead per trace is typically under 100 microseconds.


## Security and Privacy

The Graphsignal SDK 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.


## Troubleshooting

To enable debug logging, add `debug_mode=True` to `configure()`. If the debug log doesn’t provide hints for resolving the issue, 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.

