Python SDK | Docs

The SDK sends your app's traces to Kensa. Your existing tracing code still creates them. You need Python 3.12 or later.

Install

pip install kensa-sdk

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

Start it

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

Traces are sent in the background, and any left over are sent when your app exits normally. In a serverless function, send them before the response ends:

kensa.flush()

Without an API key, init() logs a warning and does nothing. The SDK never raises errors into your app.

Send a first trace

With KENSA_API_KEY set in your environment, save this as first_trace.py and run python first_trace.py. It creates one span, prints its trace ID, and flushes after the span ends:

import os
 
import kensa
from opentelemetry import trace
 
kensa.init(api_key=os.environ["KENSA_API_KEY"], service_name="kensa-example")
tracer = trace.get_tracer("kensa-example")
 
with tracer.start_as_current_span("connection-check") as span:
    print(f"Trace ID: {span.get_span_context().trace_id:032x}")
 
kensa.flush()

Pass the printed ID to get_setup_status. This confirms trace delivery. Next, enable your agent framework's instrumentation and verify a real request with model inputs, outputs, and tool calls using its trace ID. See OpenTelemetry's Python instrumentation guide for creating spans around application work.

Settings

Setting	How to set it	Default
API key	`init(api_key=...)` or `KENSA_API_KEY`	Required
Service name	`init(service_name=...)` or `OTEL_SERVICE_NAME`	`unknown_service`
Kensa address	`KENSA_ENDPOINT`	`https://ingest.kensa.sh/v1/traces`

Commit and environment

When init() creates your tracer provider, it automatically detects the commit and environment on Vercel and Railway. On Render, it detects the commit. Kensa uses these details to check fixes against production traffic.

Other platforms and manual overrides

For other platforms, or to override detected values, set these before calling init():

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

Use your deployed commit SHA for service.version and your actual environment name for deployment.environment.name. On Render, only the environment needs to be supplied. Use production for production deployments and a name such as development for local runs.

The SDK reads these platform variables automatically:

Platform	Commit	Environment
Vercel	`VERCEL_GIT_COMMIT_SHA`	`VERCEL_ENV`
Railway	`RAILWAY_GIT_COMMIT_SHA`	`RAILWAY_ENVIRONMENT_NAME`
Render	`RENDER_GIT_COMMIT`	Set through `OTEL_RESOURCE_ATTRIBUTES`

If your app already uses OpenTelemetry

init() adds Kensa to the tracer provider your app already set up, so call it after that setup. If your provider isn't registered globally, pass it in:

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

Kensa uses your provider's existing service name, commit, and environment. It logs a warning if the commit or environment is missing.

Configure missing commit or environment details

Set service.version to your deployed commit SHA and deployment.environment.name to your actual environment on your provider's resource. Existing correct values need no changes. In this setup, service_name passed to init() is ignored; the service name comes from your provider too.