# Kensa docs

> Every page of the Kensa documentation. The index is at /llms.txt.

# Introduction

> Kensa finds and fixes issues in your agents.

Kensa reads your agent's production traces, detects issues and gives your coding agent, like Claude Code or Codex, the context to fix them. After you ship a fix, Kensa monitors whether the issue reccurs.

Think of Kensa less as an observability platform and more as a behavior monitoring tool that catches bugs, alerts you, and fixes issues in production.

Give this prompt to your coding agent:

```text
Fetch https://kensa.sh/install and follow it.
```

Follow the [Quickstart](/docs/quickstart) to send your first request and explore your issues.

The core input is a **trace**: a record of an agent request, including captured inputs, model calls, tool calls, and outputs.

## How it works

1. [Connect your traces](/docs/quickstart).
2. Tell Kensa [what your agent should do](/docs/concepts). This is optional.
3. [Look at an issue](/docs/issues) and confirm or dismiss it.
4. [Give it to your coding agent](/docs/agent-workflow) to fix.
5. Ship the fix and report it. Kensa watches for recurrence.

## Coding agents

Kensa works with any coding agent that supports MCP, such as Claude Code, Codex, and Cursor. See [Agent workflow](/docs/agent-workflow) to connect
yours.

# Quickstart

> Connect Kensa, check the connection, and explore your issues.

## 1. Connect Kensa

Open your app's repository and give your coding agent this prompt:

```text
Fetch https://kensa.sh/install and follow it.
```

Follow the sign-in flow. Your coding agent will help configure the right connection.

### If you already have traces

You can connect the tracing you already use to Kensa. Choose the path that matches your setup:

- **Langfuse:** Connect your Langfuse project. Kensa imports existing traces automatically.
- **OpenTelemetry:** Add Kensa as another destination for your traces. Apply the configuration through
  your normal deployment process.

### If you're setting up tracing

Your coding agent will add the Kensa SDK and enable tracing in your agent framework. Open a pull
request, review the changes, and merge it. Configure your Kensa API key in your deployment environment,
then deploy your app.

## 2. Check the connection

For Langfuse, Kensa starts by importing recent traces. For SDK or OpenTelemetry setups, use your
deployed app, such as sending your chatbot a message or running an agent task.

Then ask your coding agent:

```text
Check that Kensa is receiving production traces.
```

## 3. Explore your issues

Open **Issues** to review what Kensa finds. Each issue includes [evidence and the expected
behavior](/docs/issues).

Choose **Copy agent prompt** to give an issue to your coding agent.

<Accordion title="Troubleshooting setup">

### API keys

If you use the SDK or OpenTelemetry, you need the project's API key. The Connect screen creates one
if the project doesn't have one yet. You can also make one on the page where you chose
**Connect agent**: open **Configure tracing credentials** and choose **Generate new key**. Save it
as `KENSA_API_KEY` in your secret store when it's shown.

For manual setup, follow [Tracing](/docs/tracing).

### Check a specific request

Capture the request's trace ID from your instrumentation, or copy it from Langfuse. The
[Python](/docs/sdk/python#send-a-first-trace) and [TypeScript](/docs/sdk/typescript#send-a-first-trace) examples
show how to read an OpenTelemetry trace ID. Ask your coding agent:

```text
Call get_setup_status with traceId "<the request's trace ID>".
Report traceReceived and productionMonitoringReady separately.
```

- **`traceReceived: true`** means Kensa received that request. Local traffic is enough to verify setup.
- **`productionMonitoringReady: true`** means Kensa has received a production trace with a version in
  the last 24 hours. To monitor a specific fix, ship it and report its deployed version.

### Trace delivery

Check that your app creates spans, the API key belongs to the connected project, and buffered spans
have been flushed. In a short-lived process, call `kensa.flush()` after the request finishes; await
it in TypeScript. For Langfuse, imports run every 15 minutes after the initial import.

If the trace arrives but production monitoring isn't ready, check its deployed version and
environment. Use the environment where the request actually ran, such as `development` or `production`.

</Accordion>

**Next steps:** [Describe your agent's job](/docs/concepts) · [Fix and monitor an issue](/docs/agent-workflow)

# Concepts

> The few terms you need to use Kensa.

| Term | Meaning |
|---|---|
| Project | Holds one app's traces, issues, connections, and fixes. |
| Agent's job | What your agent should do, the rules it follows, and what a good answer looks like. Change it in **Settings**. |
| Trace | A record of one request, including model calls, tool calls, and results. |
| Issue | A likely bug, shown with the traces where it happened and what should have happened instead. |
| Occurrence | One time an issue happened, in one trace. |
| Reported fix | A change you shipped to production to fix an issue. |

Kensa talks about two agents. Your **app's agent** is the one Kensa watches. Your **coding agent**
(such as Claude Code) looks into issues and reports fixes.

One issue can happen many times, and one trace can have more than one issue. For example, “Refund
approved after the deadline” is one issue. If it happened in three requests, that's three occurrences.

**Suggested validation checks** are tests you or your coding agent can run to assess the fix.
See [Issues](/docs/issues) for what each issue status means.

# Issues

> Look at issues and know what to do next.

You can find issues on the **Issues** page. The **Activity** page shows where and how often they
happen.

## Look at an issue

1. Read **What it is** and **What should happen**.
2. Check the evidence timeline. It shows each time the issue happened, which traces it was in, and
   when it was first and last seen.
3. Choose **Confirm issue** if it needs fixing, or **Dismiss** if it doesn't. You can undo either
   with **Change review** or **Reopen issue**.

## States

| State | What to do |
|---|---|
| Needs review | Confirm or dismiss it. |
| Open | You confirmed it. [Give it to your coding agent](/docs/agent-workflow). |
| Awaiting traffic | No eligible production traces have been evaluated for this fix yet. Check the version, environment, and whether the request started after the fix was reported. |
| Monitoring | Kensa is checking new production traces. Watch how often the issue comes back. |
| Recurred | The issue came back after the fix. Look into it and report a new fix. |
| Dismissed | You dismissed it, or Kensa decided it was expected. Reopen it if needed. |

After a fix, Kensa keeps monitoring production traffic and shows whether the issue recurs.

# Agent workflow

> Give your coding agent an issue, deploy the change, and report the fix.

## Give your agent an issue

Choose **Copy agent prompt** on an issue, or give your coding agent the issue's ID. Your agent can
read the evidence, investigate the cause, and make a change.

<Accordion title="Connect your coding agent first, if needed">

Open your app's repository and give your coding agent this prompt:

```text
Fetch https://kensa.sh/install and follow it.
```

Follow the sign-in flow, then give your agent the issue. See [MCP setup](/docs/mcp/connect) for connection
details and troubleshooting.

</Accordion>

## Review and deploy

Open a pull request, review the changes and test results, then merge and deploy through your normal
workflow.

## Report a fix

After your change is deployed, ask your coding agent:

```text
Report this fix to Kensa. Use the production deployment details,
and ask me for anything you can't verify.
```

Your coding agent fills in the issue and deployment details using the issue context, Git history,
and available deployment information. It asks you for any missing details, then submits the report.

Kensa then monitors production traffic from that version for recurrence.

## Check the results

Ask your coding agent:

```text
Check whether this issue has recurred since the fix.
```

Your agent can retrieve the current fix's monitoring status and recurrence counts. You can also
follow the results on the issue page. See [issue states](/docs/issues#states) for what each status means.

For tool parameters and retry behavior, see the [MCP tool reference](/docs/mcp/tools).

# Connect your coding agent

> Give your coding agent access to Kensa through MCP.

Kensa's MCP server lets your coding agent read issues and report deployed fixes.

## Connect

From your application repository, use the [setup prompt](/docs/quickstart). It adds
`https://kensa.sh/api/mcp` to your coding agent's project configuration. You can also copy the
configuration from **Settings → MCP server**. Each developer signs in separately; credentials stay
outside the repository.

| Coding agent | Sign in |
|---|---|
| Claude Code | Open `/mcp` and sign in. |
| Codex | Run `codex mcp login kensa`. |
| Cursor | Click Connect in its MCP settings. |
| OpenCode | Run `opencode mcp auth kensa`. |

A browser opens for you to choose a project and approve access. Check that the connected project is
the one you intended. If Kensa's tools don't appear, restart your agent session.

To send traces, set up a project API key or Langfuse connection separately. See
[Tracing](/docs/tracing).

## Use Kensa

Ask your coding agent:

```text
Show me the issues in this project.
```

For a specific issue, use its ID:

```text
Investigate and fix Kensa issue <issue ID> in this repo. Once the fix is deployed, report the deployed version to Kensa.
```

See the [Agent workflow](/docs/agent-workflow) for investigating issues and the
[Tool reference](/docs/mcp/tools) for available tools.

# Tool reference

> Inputs and behavior for Kensa's MCP tools.

Your coding agent calls these tools through the [MCP connection](/docs/mcp/connect). All tools operate on
the connected project. `list_issues`, `get_issue`, and `get_setup_status` read data; `report_fix`
records a deployed fix.

## list_issues

Lists issues with their expected behavior, occurrence counts, and first and last observation times.

| Input | Description |
|---|---|
| `status` | Optional filter: `expected`, `unexpected`, or `dismissed`. Omit to list all statuses. |

Example input:

```json
{ "status": "unexpected" }
```

Returns an `issues` array.

## get_issue

Reads one issue's evidence, suggested checks, occurrences, and current fix with monitoring results.

| Input | Description |
|---|---|
| `issueId` | Required issue UUID. |

Example input:

```json
{ "issueId": "7cde2790-b9c2-49e8-90bd-ef4352f953bb" }
```

Returns an `issue` object. When a fix has been reported, `activeFix.evidence` includes its monitoring
status, the number of eligible traces evaluated, and recurrence and non-recurrence counts. Use these
results to check how the deployed fix is performing.

## get_setup_status

Reads connection details and checks whether a specific request reached Kensa.

| Input | Description |
|---|---|
| `traceId` | Optional original application or Langfuse trace ID. Include it to verify a specific request; omit to inspect connection details. |

Example input:

```json
{ "traceId": "0123456789abcdef0123456789abcdef" }
```

Returns the project, connection URL, OTLP endpoint, and trace status:

- `traceReceived` confirms receipt of the supplied trace ID.
- `lastTraceAt` shows the latest trace update time.
- `productionMonitoringReady` means Kensa received a production trace with a version in the last
  24 hours. Monitoring a particular fix starts when that deployed fix is reported.

## report_fix

Records a production deployment and starts monitoring for recurrence. Your coding agent assembles
these inputs from the issue and verified deployment details. See [Report a fix](/docs/agent-workflow#report-a-fix)
for the everyday workflow.

| Input | Description |
|---|---|
| `issueId` | Required issue UUID. |
| `deployedVersion` | Required deployed version, matching `service.version` on the traces. The Kensa SDK's automatic detection uses the commit SHA. |
| `deploymentEnvironment` | Required: `"production"`. |
| `deployedAt` | Required deployment time as an ISO timestamp. |
| `commitSha` | Required: the 40-character lowercase commit SHA, or `null` when unavailable. |
| `idempotencyKey` | Required unique string generated for this report. Reuse it when retrying the same report. |

Example input:

```json
{
  "issueId": "7cde2790-b9c2-49e8-90bd-ef4352f953bb",
  "deployedVersion": "0123456789abcdef0123456789abcdef01234567",
  "deploymentEnvironment": "production",
  "deployedAt": "2026-09-22T04:00:00Z",
  "idempotencyKey": "refund-window-fix-2026-09-22",
  "commitSha": "0123456789abcdef0123456789abcdef01234567"
}
```

Returns a `fix` object with its deployment details and monitoring evidence.

### Retries and subsequent fixes

Retry the same report with the same inputs and `idempotencyKey`. Reusing that key with different
details returns `idempotency_key_reused`. Use a new key for a new report, which supersedes the
previous fix for that issue. Reopen a dismissed issue before reporting a fix.

Kensa evaluates traces from the reported version and production environment that start after the
report. See [issue states](/docs/issues#states) for the monitoring results.

# Python SDK

> Send traces to Kensa from a Python app.

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

## Install

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

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

## Start it

```python
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:

```python
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:

```python
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](https://opentelemetry.io/docs/languages/python/instrumentation/)
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.

<Accordion title="Other platforms and manual overrides">

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

```bash
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` |

</Accordion>

## 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:

```python
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.

<Accordion title="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.

</Accordion>

# TypeScript SDK

> Send traces to Kensa from a Node.js app.

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

```bash
npm install kensa-sdk
```

## Start it

```ts
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:

```ts
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:

```bash
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:

```js
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](https://opentelemetry.io/docs/languages/js/instrumentation/)
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.

<Accordion title="Other platforms and manual overrides">

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

```bash
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` |

</Accordion>

## 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`:

```ts
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.

<Accordion title="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.

</Accordion>

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.

# Tracing

> Send traces to Kensa from Langfuse, the Kensa SDK, or OpenTelemetry.

Kensa adds one more place to send your traces. Keep the tracing you already have. Your app still
creates the traces.

To check fixes, every trace needs two labels: `service.version` (for example, the commit you shipped)
and `deployment.environment.name`. When it creates the tracer provider, the SDK fills in both on Vercel and Railway, and the version
on Render. When you're done, [check that a real request arrives](/docs/quickstart).

## Langfuse

On the Connect screen, choose **Yes, I have observability**, then **Langfuse**. Pick your region,
enter your Langfuse project's public and secret keys, and choose **Connect Langfuse**. Use keys made
just for Kensa, so you can turn off Kensa's access without affecting anything else.

Kensa first imports the last 24 hours of traces. After that, it checks for new ones every 15 minutes.
To check setup, use the trace ID from Langfuse.

To monitor a fix, Kensa reads two fields from your Langfuse observations:

| Langfuse field | Required value |
|---|---|
| `release` | The deployed version you pass to `report_fix.deployedVersion` |
| `environment` | `production` |

Keep these values consistent across observations in the same trace. Conflicting versions or
environments prevent Kensa from identifying its deployment.

## Kensa SDK

Your agent framework's instrumentation captures model and tool calls. The Kensa SDK sends those
traces to Kensa.

If your app already creates spans, keep that instrumentation. Otherwise, enable tracing in your
agent framework before checking setup. See the [Python](/docs/sdk/python) or [TypeScript](/docs/sdk/typescript) SDK.

## OpenTelemetry

Copy the address from the Connect screen or from `get_setup_status.otlpEndpoint`. Then set these
variables:

```bash
# Use the TRACES variable. The address already ends in /v1/traces.
export OTEL_EXPORTER_OTLP_TRACES_ENDPOINT="https://ingest.kensa.sh/v1/traces"
export OTEL_EXPORTER_OTLP_TRACES_PROTOCOL=http/protobuf
# %20 is the space after "Bearer".
export OTEL_EXPORTER_OTLP_TRACES_HEADERS="authorization=Bearer%20${KENSA_API_KEY}"
export OTEL_SERVICE_NAME=support-agent
export OTEL_RESOURCE_ATTRIBUTES="service.version=<commit sha>,deployment.environment.name=production"
```

If these variables already point to another tool, add Kensa as a second exporter instead of changing
them. Each request to Kensa can be up to 4 MiB. Make sure your app sends its last traces before it
exits.

# Privacy

> How Kensa handles your keys and trace data.

## Keys

- Keep your project API key in a secret store. Never put it in chat, code you commit, or a URL. You
  only see it once. Making a new key turns off the old one.
- Your coding agent's access is separate from the API key. Remove it from
  [Agent connections](https://kensa.sh/oauth/connections) without changing the key.
- Use Langfuse keys made just for Kensa. Langfuse keys can do more than read. Kensa stores them
  encrypted and never shows them again.
- If some data must never reach Kensa, remove it before it leaves your systems.

## Trace data

- Kensa removes all PII and sensitive data from traces before processing them. It only stores the redacted traces.
- Connecting GitHub is optional. Kensa uses it only to read your code when drafting your agent's job and defining what good looks like.
- To delete an account and all its data, email [support@kensa.sh](mailto:support@kensa.sh).
- We never train on your data.
- See the [Privacy Policy](https://kensa.sh/privacy) and [Security](https://kensa.sh/security) pages for
the full details.

# Changelog

> What's new in Kensa.

## Initial release

Kensa finds bugs in your AI agent's production traces, helps your coding agent fix them, and checks whether they come back.

- Send traces from Langfuse, OpenTelemetry, or the `kensa-sdk` package for Python and TypeScript. Kensa removes sensitive data before saving them.
- Look at each issue's evidence, then confirm or dismiss it.
- Set up with your coding agent through `https://kensa.sh/install`. Your agent can then read issues and report fixes, and Kensa watches production for the bug coming back.