Skip to content

Trace with plain OpenTelemetry.

Works today from any language: your standard OTLP exporter, four environment variables and one attribute per AI call. A two-line helper for TypeScript and Python is coming soon.

1. Get an ingest token

In the Suture app, open setup, choose OpenTelemetry and press Create a token. It starts with sut_ing_ and is shown once. Put it in your secret manager or hosting env vars, never in code.

2. Point your exporter at Suture

Use your language’s standard OpenTelemetry OTLP/HTTP exporter and set these four variables. <token> is the ingest token. Keep the %20: the header value is URL-encoded, and %20 is the space after Bearer.

shell / .env
OTEL_EXPORTER_OTLP_TRACES_ENDPOINT=https://app.trysuture.com/api/otlp/v1/traces
OTEL_EXPORTER_OTLP_TRACES_HEADERS=Authorization=Bearer%20<token>
OTEL_EXPORTER_OTLP_TRACES_PROTOCOL=http/protobuf
OTEL_SERVICE_NAME=<your-agent>

The endpoint takes protobuf (http/protobuf) or JSON (http/json), gzipped or not. Exporter setup for Python and TypeScript is in the quickstart; Go, Java and Ruby work the same way.

3. Name the feature on each AI call

Set suture.prompt_id to the feature’s slug on the span that calls the model. Suture also reads gen_ai.agent.name, and the model, tokens, errors and timing from the OpenTelemetry GenAI and OpenInference attribute names, so most LLM instrumentation libraries need nothing else.

one attribute
# Python: on the span that calls the model
span.set_attribute("suture.prompt_id", "post-writer")

// TypeScript
span.setAttribute('suture.prompt_id', 'post-writer');

Use the same slugs as your feature doc

The slug is how Suture knows which checks a trace should pass. Use the feature names from your SUTURE_AI_FEATURES.md. The AI features prompt writes that file and lists every AI call that does not carry its slug yet.

Already on Langfuse?

Skip the exporter: connect Langfuse in the app with your project keys and Suture pulls your traces, no code. Already exporting OpenTelemetry somewhere else? Keep it, and add Suture’s exporter next to it.

[soon]The two-line helper: suture-trace

Coming soon: not on npm or PyPI yet, so the install lines below will not resolve today. Everything above works without it. When it ships it does the same as steps 2 and 3 in code: one init, then one line per AI call that names the feature.

env
SUTURE_API_KEY=sut_ing_...          # required: the project's ingest token
SUTURE_CAPTURE_CONTENT=true         # optional: also send prompt and response text
SUTURE_ENDPOINT=https://app.trysuture.com   # optional: base URL only, for a self-hosted or preview app
npm i suture-trace · coming soon: not on npm or PyPI yet
import { initSuture, suture } from 'suture-trace';

initSuture({ apiKey: process.env.SUTURE_API_KEY });            // once, at startup

const res = await suture('post-writer', () =>                  // around each AI call
  openai.chat.completions.create({ model: 'gpt-5-mini', messages }),
);
typescript / optional
// Vercel AI SDK v5, v6 or v7: one span per model step, tagged with the feature
await generateText({ model, prompt, experimental_telemetry: sutureTelemetry('post-writer') });
// (v7 also accepts the key `telemetry`. v7 runs per-call integrations instead of global ones,
//  so if you registered your own, merge them into sutureTelemetry(...).integrations.)

// Pass what went in, so Suture can judge it (sent only with captureContent)
await suture('post-writer', () => callModel(messages), { input: messages });

// Serverless (Vercel, Lambda) or a script that exits: send before it ends
await flushSuture();
pip install suture-trace · coming soon: not on npm or PyPI yet
import suture_trace

suture_trace.init()                       # once; reads SUTURE_API_KEY

@suture_trace.feature("post-writer")      # on the function that calls the model
def write_post(topic):
    return client.chat.completions.create(model="gpt-5-mini", messages=[...])
python / optional
# Or around a single call
with suture_trace.feature("post-writer", input=messages) as f:
    f.record(client.chat.completions.create(model="gpt-5-mini", messages=messages))

suture_trace.flush()   # before a script or lambda exits

What the helper records on each span:

Feature
gen_ai.agent.name and suture.prompt_id, set to the slug you pass
Model
gen_ai.response.model, read off the OpenAI, Anthropic or AI SDK result
Tokens
gen_ai.usage.input_tokens and gen_ai.usage.output_tokens
Errors
span status, error.type and the exception, then your error is rethrown untouched
Timing
start and end of the call
Text (opt-in)
gen_ai.input.messages and gen_ai.output.messages, only with captureContent

Prompt and response text stays in your app unless you set captureContent: true (capture_content=True in Python) or SUTURE_CAPTURE_CONTENT=true. Without it Suture still sees which feature ran, the model, tokens, errors and timing, but cannot judge answers. Suture redacts PII on arrival either way.

The helper never throws into your code or waits on the network: spans are sent in the background, and if Suture is down or the key is missing, your call runs as normal. A script or serverless function should await flushSuture() (suture_trace.flush()) before it exits.