SpanForge PlatformSpanForge SDK
spanforge · Python 3.9+ · In Development

The reference implementation.

pip install spanforge — zero required dependencies, all 15 spanforge namespaces, a full CLI, and integrations for OpenAI, LangChain, LlamaIndex, CrewAI, and Datadog.

Debug tooling →Read the standard →
Installation

Get started in one command.

Install the base SDK with no required dependencies. Add optional extras for the integrations and export targets you need.

pip install spanforge

Verify the installation:

bash
spanforge --version
# spanforge 1.0.8 [spanforge-Full-2.0]

Optional extras

ExtraWhat it adds
spanforge[jsonschema]Enables runtime schema validation of every emitted event against the published JSON Schema.
spanforge[openai]Auto-instrumentation for the openai Python client — wraps chat completions, embeddings, and responses.
spanforge[http]OTLP/HTTP export and webhook export targets.
spanforge[pydantic]Pydantic v2 model support for typed payload validation.
spanforge[otel]Full OpenTelemetry SDK integration — exports spans as OTLP proto via grpc or http.
spanforge[kafka]Apache Kafka export backend for streaming event pipelines.
spanforge[langchain]LangChain callback handler — instruments chain, tool, and LLM calls automatically.
spanforge[llamaindex]LlamaIndex event handler — instruments query, retrieval, and LLM calls.
spanforge[crewai]CrewAI task-and-agent lifecycle instrumentation.
spanforge[datadog]Datadog exporter — ships events to DD APM as custom spans.
spanforge[all]Installs all optional extras in a single command.
Quickstart

Your first event.

Every event in the spanforge standard is an Event object with three required arguments: event_type, source, and payload.

python
from spanforge import Event, EventType

# Minimal event
event = Event(
    event_type=EventType.TRACE_SPAN_COMPLETED,
    source="my-service@0.1.0",
    payload={"span_name": "summarise", "status": "ok"},
)

# Event is ready to emit or inspect
print(event.event_id)    # ULID e.g. 01HZQSN7PQVR2K4M0BXJD3GSTA
print(event.timestamp)   # ISO-8601 UTC
print(event.trace_id)    # W3C-compatible 128-bit hex

Typed namespace payloads

Use the typed payload classes from each namespace for full schema validation and IDE autocompletion. The classes map 1-to-1 to the published JSON Schema.

python
from spanforge import Event, EventType
from spanforge.namespaces.trace import SpanPayload, TokenUsage, ModelInfo, GenAISystem

event = Event(
    event_type=EventType.TRACE_SPAN_COMPLETED,
    source="spanforge@1.0.0",
    payload=SpanPayload(
        span_name="summarise_document",
        span_kind="LLM",
        status="ok",
        duration_ms=830,
        token_usage=TokenUsage(input_tokens=411, output_tokens=128, total_tokens=539),
        model_info=ModelInfo(system=GenAISystem.OPENAI, name="gpt-4o"),
    ).to_dict(),
    tags=["prod", "summarisation"],
)

# Export to OTLP
from spanforge.export import OTLPExporter
exporter = OTLPExporter(endpoint="http://localhost:4317")
exporter.export(event)
Integrations

Works with your existing stack.

Install the relevant extra and add one line of code. spanforge events are emitted automatically — you retain full compliance instrumentation without rewriting your existing code.

OpenAI · spanforge[openai]

OpenAI

One-line auto-instrumentation for the openai Python client. Wraps chat completions, embeddings, and the Responses API. Emits llm.trace.span and llm.cost.* events automatically.

LangChain · spanforge[langchain]

LangChain

Drop-in callback handler. Instruments chain invocations, tool calls, and LLM calls. Compatible with LangChain v0.1 and v0.2.

LlamaIndex · spanforge[llamaindex]

LlamaIndex

Event handler for the LlamaIndex instrumentation API. Captures query, retrieval, embedding, and LLM events with full trace context.

CrewAI · spanforge[crewai]

CrewAI

Task and agent lifecycle instrumentation for CrewAI. Captures agent run start/end, task assignment, and tool delegation events.

Datadog · spanforge[datadog]

Datadog

Export spanforge span events as custom Datadog APM spans. Compatible with the Datadog Agent and the dd-trace-py client.

OpenTelemetry · spanforge[otel]

OpenTelemetry

Full OTLP bridge. Converts spanforge span events to OpenTelemetry proto-compatible dicts and exports via gRPC or HTTP. Works with any OTEL-compatible backend.

Command-line interface

Operational tooling included.

The spanforge CLI is installed automatically with the SDK. Use it for health checks, schema validation, audit-chain verification, compliance evidence generation, and PII scanning.

spanforge checkEnd-to-end health check: config, event creation, schema validation, export pipeline, trace store.
spanforge check-compatValidate a batch of events against the v1.0 compatibility checklist (CHK-1 through CHK-5).
spanforge validateValidate every event in a JSONL file against the published JSON Schema.
spanforge audit-chainVerify HMAC-SHA256 signing chain integrity of events in a JSONL file.
spanforge complianceGenerate HMAC-signed compliance evidence packages mapped to EU AI Act, GDPR, SOC 2, ISO 42001, and NIST AI RMF.
spanforge auditAudit chain management: erase, rotate-key, check-health, verify.
spanforge scanScan a JSONL file for PII using built-in regex detectors.
spanforge inspectPretty-print a single event by event_id from a JSONL file.
spanforge statsPrint event-type counts, trace count, and time range for a JSONL file.
spanforge reportGenerate a static HTML trace report from a JSONL events file.
spanforge serveStart a local HTTP trace viewer at /traces (default port 8888).
spanforge check-consumersAssert all registered consumers are compatible with the installed schema.
bash
# End-to-end health check
spanforge check
# [1/5] Config ............. OK
# [2/5] Event creation ..... OK
# [3/5] Schema validation .. OK
# [4/5] Export pipeline .... OK
# [5/5] Trace store ........ OK
# All checks passed.

# Validate a JSONL event stream
spanforge validate production-events.jsonl

# Scan for PII before export
spanforge scan production-events.jsonl

# Generate compliance evidence package
spanforge compliance production-events.jsonl --framework eu-ai-act
Code quality

SDK instrumentation linter.

The built-in linter parses your Python source with ast and runs five checks to catch common instrumentation mistakes before they reach production. Integrates natively with flake8 and ruff.

AO001Event() missing one of event_type, source, or payload.
AO002Bare str literal passed to actor_id, session_id, or user_id — wrap in Redactable().
AO003event_type= string not present in registered EventType values.
AO004LLM provider API call outside a tracer.span() / agent_run() context.
AO005emit_span / emit_agent_* called outside agent_run() / agent_step() context.
Next steps

Inspect. Validate. Ship.

Use SpanForge Debug to inspect and replay compliance traces, and SpanForge Validate to enforce schema compliance in your CI pipeline.

SpanForge Debug →SpanForge Validate →
← RFC-0001 StandardSpanForge Debug →