kensa-sdk

Send your agent's OpenTelemetry traces to Kensa.

pip install kensa-sdk

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

Quick start

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.

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:

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

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:

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:

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

Requires Python 3.12 or later.