tracectrl-enterprise 0.1.0

TraceCtrl Enterprise SDK — agentic AI security observability for the enterprise platform

tracectrl-enterprise

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

Apache 2.0 licensed. Thin wrapper over the OSS tracectrl package — tracectrl does the OpenTelemetry SDK heavy lifting; this package adds enterprise-specific defaults (collector endpoint, required ingest-key auth, fail-loud behaviour) and the tag_agent() API for self-identifying agent spans.

Install

pip install tracectrl-enterprise

Quickstart

import os
from tracectrl_enterprise import configure, tag_agent

configure(ingest_key=os.environ["TRACECTRL_INGEST_KEY"])

@tag_agent(
    id="payment-bot",
    name="PaymentAgent",
    framework="strands",  # framework you're running on; informational
    role="payment_processing",
)
def run_payment(query: str) -> str:
    # ... your agent logic ...
    return "ok"

Every call to run_payment creates an OpenTelemetry span with the canonical TraceCtrl attributes (openinference.span.kind=AGENT, tracectrl.agent.id, tracectrl.agent.name, etc.), exported via OTLP/gRPC with Authorization: Bearer <ingest_key> to your TraceCtrl Enterprise collector. The collector resolves your ingest key to a tenant and stamps tracectrl.tenant_id on every span — your SDK doesn't (and can't) set tenancy itself; the collector is the trust boundary.

Configuration

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

Argument	Env var	Default	Required
ingest_key	TRACECTRL_INGEST_KEY	—	yes — fails loud if not set
endpoint	TRACECTRL_ENDPOINT	https://app.tracectrl.ai/ingest	no
service_name	TRACECTRL_SERVICE_NAME	tracectrl-agent	no

If you call configure() without an ingest_key argument, it reads TRACECTRL_INGEST_KEY from the environment. If neither is set, it raises ValueError — unlike the OSS SDK which can be configured to fail silently, enterprise installs always fail loud on missing auth.

Framework instrumentation

For automatic tracing of supported frameworks (Strands, etc.), install the OSS instrumentor package alongside this one:

pip install tracectrl-instrumentation-strands

The instrumentor hooks into the same global OpenTelemetry TracerProvider that tracectrl-enterprise.configure() sets up, so spans from instrumented framework calls are exported the same way as your @tag_agent-decorated functions.

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/tracectrl/tracectrl-enterprise/issues