TypeScript SDK | Docs

The SDK sends your app's traces to Kensa. Your existing tracing code, such as the AI SDK's OpenTelemetry integration, still creates them. You need Node.js 20 or later.

Install

npm install kensa-sdk

Start it

import { kensa } from "kensa-sdk";
 
kensa.init({ apiKey: process.env.KENSA_API_KEY });

Traces are sent in the background, and any left over are sent when your app exits normally (but not on process.exit()). In a serverless function, send them before the response ends:

await kensa.flush();

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

Send a first trace

Install the OpenTelemetry API for the imports in this example:

npm install @opentelemetry/api

With KENSA_API_KEY set in your environment, save this as first-trace.mjs and run node first-trace.mjs. Run it as a standalone script with no other tracer provider:

import { trace } from "@opentelemetry/api";
import { kensa } from "kensa-sdk";
 
kensa.init({ apiKey: process.env.KENSA_API_KEY, serviceName: "kensa-example" });
const tracer = trace.getTracer("kensa-example");
 
tracer.startActiveSpan("connection-check", (span) => {
  try {
    console.log(`Trace ID: ${span.spanContext().traceId}`);
  } finally {
    span.end();
  }
});
 
await 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 JavaScript instrumentation guide for creating spans around application work.

Settings

Setting	How to set it	Default
API key	`init({ apiKey })` or `KENSA_API_KEY`	Required
Service name	`init({ serviceName })` or `OTEL_SERVICE_NAME`	Package name under npm scripts, else `unknown_service:node`
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

If your app sets up its own tracer provider, add Kensa's span processor to it instead of calling init(). For example, with @vercel/otel:

import { registerOTel } from "@vercel/otel";
import { kensa } from "kensa-sdk";
 
registerOTel({
  serviceName: "support-agent",
  // @vercel/otel sets service.version to the deployment ID; Kensa matches fixes on the commit.
  attributes: { "service.version": process.env.VERCEL_GIT_COMMIT_SHA },
  spanProcessors: [
    "auto",
    kensa.spanProcessor({ apiKey: process.env.KENSA_API_KEY }),
  ],
});

@vercel/otel supplies the environment automatically. The example above uses the commit SHA so Kensa can match traces to reported fixes.

Commit and environment with other providers

Kensa uses your provider's existing resource attributes. If needed, set service.version to your deployed commit SHA and deployment.environment.name to your actual environment on that provider. Existing correct values need no changes.

Use kensa.init() only when your app has no registered tracer provider.

If your app already registers a provider, add kensa.spanProcessor() to that provider and preserve its existing processors. Calling init() after a provider is registered logs a conflict and does not connect Kensa.