traceAI

traceAI is the instrumentation SDK

traceAI is Future AGI’s open-source instrumentation SDK, built on OpenTelemetry. It’s a set of conventions and per-framework instrumentors that capture what your AI app does (model calls, tool calls, retrievals, agent steps) and map them to standardized span attributes. Add the instrumentor for your framework, and those calls become traces in Observe with no spans written by hand. traceAI runs inside your application and produces the spans; Observe is the product that reads them. They meet only at the span, a standard OpenTelemetry span on the wire, so the same output also works with any OTel-compatible backend.

Mental model

traceAI is the adapter between your framework and OpenTelemetry. The instrumentor wraps the framework, produces standardized spans, and hands them to the OTel pipeline that exports to Future AGI.

flowchart LR
accTitle: Where traceAI sits
accDescr: A framework call is wrapped by a traceAI instrumentor, which emits standardized OpenTelemetry spans that the exporter sends to Future AGI Observe.
A["Framework call: OpenAI, LangChain, ..."] --> B["traceAI instrumentor"]
B --> C["Standardized OTel spans"]
C --> D["Future AGI Observe"]

You pick the instrumentor that matches your framework, and the rest of the pipeline is the same OTel flow for everyone.

Auto and manual instrumentation

There are two ways to produce spans, and real apps use both. Auto-instrumentation is a per-framework instrumentor that wraps a library: install the one for your framework (traceAI-openai, traceAI-langchain, and so on), call .instrument(), and every framework call becomes a span with no span code in your app. Manual instrumentation covers the parts no instrumentor reaches, like your own business functions, custom retrieval, or glue logic, which you wrap as tool spans yourself.

Auto and manual spans feed the same provider, so they nest into one trace. That shared provider is what register() sets up: it builds the OpenTelemetry tracer provider, points the exporter at Future AGI, and makes it active. Nothing reaches Observe until register() has run, because before it there’s no exporter to ship spans to. Plain non-LLM work, like a database query, needs none of this: trace it with raw OpenTelemetry and it still lands in the same trace tree.

Why it matters

Raw OpenTelemetry knows nothing about LLMs. It has no concept of a prompt, a completion, token cost, or a tool call. traceAI fills that gap. It turns framework calls into LLM-shaped spans with consistent keys, so a LangChain trace and an OpenAI trace look the same in Observe and are queryable the same way. That standardization is what lets filters, evals, and dashboards work across different stacks instead of breaking every time you change frameworks.

Keep exploring