tracectrl-sdk

TraceCtrl Enterprise SDK — instrument your agentic AI application to send traces to a TraceCtrl Enterprise deployment.

Apache 2.0 licensed. Built directly on OpenTelemetry and OpenInference — self-contained, with no other TraceCtrl runtime dependency. Adds enterprise-specific defaults (collector endpoint, required ingest-key auth, fail-loud behaviour) plus configure(), instrument(), and track() for deterministic, source-declared agent identity.

Install

pip install "tracectrl-sdk[strands]"   # or [agno], [langchain], [crewai], [google-adk], [all]

The framework extras pull the matching OpenInference instrumentor. The base package (pip install tracectrl-sdk, just OpenTelemetry) is enough if you only use configure() + track() without framework auto-instrumentation.

Quickstart

import os
from tracectrl_enterprise import configure, instrument, track

configure(ingest_key=os.environ["TRACECTRL_INGEST_KEY"])  # auth + endpoint
instrument("strands")                                      # framework auto-instrumentation

from strands import Agent
agent = track(Agent(name="PaymentAgent", system_prompt="..."))  # declare identity once

agent("refund order 123")   # every invocation is now a clean AGENT span

Three calls:

1. configure(ingest_key=...) — initialise the OTLP pipeline against your collector (required ingest key; fails loud if missing).
2. instrument(framework) — activate OpenInference auto-instrumentation for your framework ("strands", "agno", "langchain", "crewai", "google-adk", a list, or "auto" to pick up whatever's installed), plus the enterprise enrichment processors.
3. track(agent) — wrap an agent object once. track reads the agent's name and system prompt automatically and stamps the canonical openinference.span.kind=AGENT + tracectrl.agent.{id,name,framework} (and role/system_prompt when available) at the source — so the platform never has to guess agent identity from span names. Returns the same agent (chainable).

Override any field explicitly when the defaults aren't right (notably for LangChain/CrewAI/Google ADK, whose agents don't self-describe):

agent = track(my_chain, id="invoice-extractor", name="InvoiceExtractor",
              framework="langchain", role="document_extraction")

For multi-turn flows, group traces with the session helpers:

from tracectrl_enterprise import new_session, set_user_id
new_session(user_id="alice@example.com")   # or set_session_id("<your conversation id>")
set_user_id("bob@example.com")             # change who is driving; clear_user_id() to forget

Mark externally-triggered entry points with the ingress decorator so the platform records how a run was triggered:

from tracectrl_enterprise import ingress

@ingress(trigger_type="email")
def handle_inbound(msg): ...

Tenancy is set by the collector, never the SDK

Spans export over OTLP (gRPC by default, HTTP opt-in) with Authorization: Bearer <ingest_key>. The collector resolves your ingest key to a tenant and stamps tracectrl.tenant_id on every span — your app can't (and shouldn't) set tenancy itself; the collector is the trust boundary.

Configuration

configure(ingest_key=..., endpoint=..., service_name=..., protocol=...):

grpc dials host:port (443 for https, else 4317) and ignores any URL path. http posts to <scheme>://host[:port]/v1/traces (port 4318 for a bare host); any other path is replaced, so https://host/ingest and https://host both work. Use http when the proxy in front of TraceCtrl terminates TLS without HTTP/2 ALPN (gRPC then fails with UNAVAILABLE … missing selected ALPN property); nothing else changes — same key, same spans, same tenancy.

Migrating from 0.1.x

0.1.x exposed a tag_agent(id=, name=, framework=) decorator placed on each agent invocation. It has been removed in favour of track(), which reads identity off the agent object, captures the system prompt, and composes with the framework instrumentors. Replace @tag_agent(id="x", name="X", framework="f") on a function with agent = track(my_agent, ...) on the agent object.

License

Apache 2.0. The TraceCtrl Enterprise server-side platform (engine, collector, UI) is BUSL-licensed; the SDK is permissively licensed so it can be embedded in your proprietary code without restriction.

Reporting issues

https://github.com/Cloudsine-weborion/tracectrl-enterprise/issues