OpenTelemetry

Export spans through OTLP/HTTP or a Threadify SDK exporter. Report each operation once; do not duplicate its span with an SDK step report.

Direct OTLP/HTTP ingestion

Configure a standard exporter with your Engine’s URL and an Engine API key:

export OTEL_EXPORTER_OTLP_TRACES_ENDPOINT='https://threadify.example.com/v1/traces'
export OTEL_EXPORTER_OTLP_TRACES_PROTOCOL='http/protobuf'
export OTEL_EXPORTER_OTLP_TRACES_HEADERS="X-API-Key=$THREADIFY_API_KEY"

Set equivalent SDK options if your exporter does not read these variables.

Requirement	Value
Endpoint	`POST /v1/traces`
Format	OTLP Protobuf, `Content-Type: application/x-protobuf`
Authentication	`X-API-Key` with an Engine API key
Compression	Optional gzip
Batch limit	64 MiB compressed and decoded; 10,000 spans

JSON and gRPC are not accepted here. A separate collector can forward gRPC input as OTLP/HTTP. Plan bandwidth allowances also apply.

Threadify SDK exporter

The JavaScript exporter uses your existing Threadify WebSocket connection:

import { Threadify } from '@threadify/sdk';
import { trace } from '@opentelemetry/api';
import { BasicTracerProvider, BatchSpanProcessor } from '@opentelemetry/sdk-trace-base';

const connection = await Threadify.connect(process.env.THREADIFY_API_KEY, 'processor', {
  engineUrl: 'https://threadify.example.com'
});
const exporter = connection.createSpanExporter({
  refs: { customer_id: 'customer.id' },
  filters: ['internal.*'],
  useWorkflowRunId: true
});
const provider = new BasicTracerProvider({
  spanProcessors: [new BatchSpanProcessor(exporter)]
});
trace.setGlobalTracerProvider(provider);

Flush/shut down the provider before closing the connection when your process exits. See filtering to exclude spans or remove sensitive fields. For Go, install github.com/ThreadifyDev/go-sdk/otel and use threadifyotel.NewSpanExporter(conn, threadifyotel.SpanExporterOptions{...}). Use RefsMap for attribute-to-ref mappings; Refs is a list of attribute names. For Python, install threadify-sdk[otel] and use connection.create_span_exporter(options={...}) with your tracer provider.

Filter trace data

Drop whole spans

Configure the Threadify SDK exporter:

const exporter = connection.createSpanExporter({
  filters: ['healthcheck', 'internal.*']
});

exporter := threadifyotel.NewSpanExporter(conn, threadifyotel.SpanExporterOptions{
    Filters: []string{"healthcheck", "internal.*"},
})

exporter = connection.create_span_exporter(options={
    "filters": ["healthcheck", "internal.*"]
})

healthcheck drops that exact span name.
internal.* drops names beginning with internal..
Matching is case-sensitive, against the original span name, before threadify.step_name mapping.
Only a trailing * is supported; these are not regex patterns.

Each span is filtered independently. Dropping a parent does not drop its children. Keep steps required by contracts and spans carrying the run’s completion signal.

Filter every OTLP exporter at the Engine

Open Settings → Trace ingestion. Enter one exact name or trailing-* prefix per line, preview sample names, then save. An administrator must save changes. Empty rules keep all spans. These rules apply only to POST /v1/traces, before threads or steps are created. Threadify SDK WebSocket events and SDK span exporters are unaffected. Rules match original span names, before threadify.step_name mapping. With the CLI:

threadify-cli ingestion-rules get > rules.json
# Edit filters; preserve revision from the response.
threadify-cli ingestion-rules set --file rules.json

Preview without saving using preview.yaml:

filters: [healthcheck, "internal.*"]
span_names: [healthcheck, internal.cache, refund]

threadify-cli ingestion-rules preview --file preview.yaml

Saves apply to the next batch across replicas sharing Valkey. In-flight batches can finish under their previous rules; existing history is unchanged.
Rules and counts persist in Valkey without a TTL. Preserve its data volume.
Stale saves return 409; reload and review before retrying.
Unavailable rules storage returns 503 instead of bypassing filtering.
Filtered exports succeed, including batches with no remaining spans. The X-Threadify-Filtered-Spans response header reports each batch’s drop count.
The settings page shows cumulative evaluated and dropped delivery attempts, including retries. Preview does not change counts. Counter-write failures are logged, so these are diagnostic counts, not billing totals.
Received bytes still count toward input bandwidth. Keep contract-required steps and run completion signals in your retained spans.

Remove fields from retained spans

Span filters do not redact attributes, prompts, payloads, or event data. refs maps attributes to references; it is not an attribute allowlist. Omit unwanted values in your instrumentation or remove them before export. Threadify has no built-in field-redaction option. Check span and resource attributes, events, and status messages; preserve fields needed by contracts.

Choose the thread identity

The correlation precedence is:

threadify.thread_id: an existing internal Threadify thread ID.
threadify.thread_key: your application-owned session or process key.
workflow.run_id: used by default when no explicit key is supplied.
OpenTelemetry trace ID: the fallback when none of the above applies.

The key uses the same Engine resolver as connection.thread(threadKey, options?). The stored contract and pinned version are loaded on resume, so subsequent spans can omit threadify.contract. A different supplied contract is rejected. Initialize contracted sessions before reporting spans; a new key without a contract creates a free-form thread. A shared thread key combines traces into one thread. Use a unique value per run, consistently set on its spans or dedicated resource. Thread keys must be nonblank strings of at most 1024 UTF-8 bytes after trimming. Existing threads are not merged retroactively. Conflicting identities or contracts are rejected.

Keep one trace per thread

Disable the workflow-run fallback on the direct traces URL:

https://threadify.example.com/v1/traces?use_workflow_run_id=false

Or on the exporter:

const exporter = connection.createSpanExporter({ useWorkflowRunId: false });

useWorkflow := false
exporter := threadifyotel.NewSpanExporter(conn, threadifyotel.SpanExporterOptions{
    UseWorkflowRunID: &useWorkflow,
})

exporter = connection.create_span_exporter(options={"useWorkflowRunId": False})

This only disables workflow.run_id; explicit threadify.thread_id and threadify.thread_key still take precedence. Omit those too for trace-ID grouping.

Mapping operations

OpenTelemetry data	Threadify use
Correlated run or trace	Thread
Span	Step; its span name is used unless overridden
Span event	Sub-step
`OK` status	Successful outcome
`ERROR` status	Failed outcome
`UNSET` status	Successful outcome when no error was recorded

Outcome is not contract compliance. A successful span can still violate a rule.

Attribute	Purpose
`threadify.thread_key`	Application session/process identity, shared with the JavaScript, Python, and Go SDKs
`threadify.contract`	Contract name, optionally with `:version`
`threadify.step_name`	Stable contract step name when the span name varies
`threadify.label`	Human-readable thread label
`threadify.role`	Contract party for Engine OTLP ingestion
`threadify.ref.customer_id`	Attach a business reference
`threadify.context.amount`	Attach step content for a rule
`threadify.invocation_id`	Correlate a span with an existing permission grant
`threadify.run.complete`	Explicit completion signal for a correlated run

span.setAttribute('threadify.thread_key', 'refund-run-2026-001');
span.setAttribute('threadify.contract', 'refund_review');
span.setAttribute('threadify.step_name', 'refund');
span.setAttribute('threadify.ref.customer_id', 'CUST-001');
span.setAttribute('threadify.context.amount', 42);

For a shared run, ending one root span does not necessarily finish the whole thread. Signal final completion with threadify.run.complete: true; contracted threads complete through their contract rules. Completion waits for all accepted spans in the current export. Terminal threads reject further writes, including delayed spans; keep the thread open until all session work has arrived. Preserve source trace/span IDs when investigating retries.

Observe or enforce

Passive export records operations after they happen. To prevent an agent tool call or backend action, use an SDK execution wait before running it, then let the span report its outcome with the invocation ID. Do not also report the same outcome through thread.step() unless it is a distinct event.

Getting Started

Core Concepts

Integrity and access

API Reference

Direct OTLP/HTTP ingestion

Threadify SDK exporter

Filter trace data

Drop whole spans

Filter every OTLP exporter at the Engine

Remove fields from retained spans

Choose the thread identity

Keep one trace per thread

Mapping operations

Observe or enforce

​Direct OTLP/HTTP ingestion

​Threadify SDK exporter

​Filter trace data

​Drop whole spans

​Filter every OTLP exporter at the Engine

​Remove fields from retained spans

​Choose the thread identity

​Keep one trace per thread

​Mapping operations

​Observe or enforce

Direct OTLP/HTTP ingestion

Threadify SDK exporter

Filter trace data

Drop whole spans

Filter every OTLP exporter at the Engine

Remove fields from retained spans

Choose the thread identity

Keep one trace per thread

Mapping operations

Observe or enforce