Metadata-Version: 2.5
Name: kensa-sdk
Version: 0.1.1
Summary: Monitor AI agents with Kensa. Capture traces, detect failures, and ship fixes fast.
Project-URL: Homepage, https://kensa.sh
License-Expression: MIT
License-File: LICENSE
Requires-Python: >=3.12
Requires-Dist: opentelemetry-api>=1.42.0
Requires-Dist: opentelemetry-exporter-otlp-proto-http>=1.42.0
Requires-Dist: opentelemetry-sdk>=1.42.0
Description-Content-Type: text/markdown

# kensa-sdk

Send your agent's OpenTelemetry traces to [Kensa](https://kensa.sh).

```bash
pip install kensa-sdk
```

The package installs as `kensa-sdk` and imports as `kensa`.

## Quick start

```python
import os

import kensa

kensa.init(api_key=os.environ.get("KENSA_API_KEY"))
```

Spans are sent in the background. Automatic process-exit cleanup uses OpenTelemetry's
standard shutdown, which currently waits up to 30 seconds to drain its queue. Slow exports
can therefore leave queued spans unsent, even though each export allows 120 seconds.

For a finite run, stop producing spans and call `kensa.flush()` before exiting. In a
serverless function, flush before the response ends. The installed OpenTelemetry processor
does not enforce an overall flush deadline, so multiple batches can take longer than
120 seconds to drain.

```python
kensa.flush()
```

`kensa.init()` sends spans; your existing instrumentation produces them. Without an API
key it does nothing and logs a warning, and nothing the SDK does raises into your
application.

## Already using OpenTelemetry?

`kensa.init()` attaches to the tracer provider your application installed instead of
replacing it, so call it after that provider is set up. Pass `provider=` if you have
not registered yours globally:

```python
kensa.init(api_key=os.environ.get("KENSA_API_KEY"), provider=my_provider)
```

Your provider's resource is fixed when it is created, so set the service name,
`service.version`, and `deployment.environment.name` on it yourself, from your
platform's variables (table below); Kensa logs a warning when the deployment is
missing. `service_name` only applies when Kensa installs its own provider.

## Configuration

| Setting      | Set with                                         | Default                     |
| ------------ | ------------------------------------------------ | --------------------------- |
| API key      | `init(api_key=...)` or `KENSA_API_KEY`           | Required                    |
| Service name | `init(service_name=...)` or `OTEL_SERVICE_NAME`  | `unknown_service`           |
| Deployment   | `OTEL_RESOURCE_ATTRIBUTES`                       | Detected from your platform |

Kensa checks a fix against the traces from the deployment that shipped it, so it needs
the deployed commit and the environment. `kensa.init()` detects them:

| Platform         | Commit                   | Environment                |
| ---------------- | ------------------------ | -------------------------- |
| Vercel           | `VERCEL_GIT_COMMIT_SHA`  | `VERCEL_ENV`               |
| Railway          | `RAILWAY_GIT_COMMIT_SHA` | `RAILWAY_ENVIRONMENT_NAME` |
| Render           | `RENDER_GIT_COMMIT`      |                            |

On Render, set the environment yourself (below). CI and local runs are never detected
as a deployment.

Anywhere else, or to override detection, set the standard OpenTelemetry variable:

```bash
OTEL_RESOURCE_ATTRIBUTES="service.version=<commit sha>,deployment.environment.name=production"
```

Requires Python 3.12 or later.
