traceAI for Python

OpenTelemetry instrumentation for AI applications. Install the core and the instrumentor for the framework you use.

All languages · Integration guides · Core API and configuration

Quickstart

Use Python 3.10–3.13 for this OpenAI example.

pip install fi-instrumentation-otel traceai-openai

export FI_API_KEY="your-future-agi-api-key"
export FI_SECRET_KEY="your-future-agi-secret-key"
export OPENAI_API_KEY="your-openai-api-key"
export OPENAI_MODEL="gpt-4.1"  # Choose a model available to your account.

Save as quickstart.py, then run python quickstart.py.

import os
from openai import OpenAI
from fi_instrumentation import register
from fi_instrumentation.fi_types import ProjectType
from traceai_openai import OpenAIInstrumentor

provider = register(project_name="traceai-quickstart", project_type=ProjectType.OBSERVE)
OpenAIInstrumentor().instrument(tracer_provider=provider)
try:
    response = OpenAI().chat.completions.create(
        model=os.environ["OPENAI_MODEL"],
        messages=[{"role": "user", "content": "Say hello in one word."}],
    )
    print(response.choices[0].message.content)
finally:
    provider.shutdown()  # Flush pending spans before the process exits.

Open the traceai-quickstart project in Observe in Future AGI. provider.shutdown() flushes pending spans before exit.

Shutdown on termination

From fi-instrumentation-otel 1.2.2, register() leaves your SIGINT and SIGTERM handlers unchanged. Default SIGTERM does not run Python exit hooks, so call provider.shutdown() from your application's shutdown path to export pending spans on container stop, and allow enough termination grace time. SIGKILL cannot flush spans.

A standalone script that owns its signal policy can opt in:

import signal

def stop(signum, frame):
    provider.shutdown()
    raise SystemExit(0)  # Your application chooses the exit status.

signal.signal(signal.SIGTERM, stop)
signal.signal(signal.SIGINT, stop)

In a web server, worker or async service, use the framework's shutdown hook instead of replacing its handlers: stop accepting work, finish or cancel active requests, then call provider.shutdown(). force_flush() exports ended spans without shutting down the provider; it does not replace shutdown for operations still running.

Context and privacy

Use using_attributes(session_id=..., user_id=..., metadata=...) to attach application context. The core also provides using_session, using_user, using_tags, and suppress_tracing.

Content capture is on by default. Configure FI_HIDE_INPUTS, FI_HIDE_OUTPUTS, FI_HIDE_INPUT_MESSAGES, FI_HIDE_OUTPUT_MESSAGES, FI_HIDE_INPUT_TEXT, FI_HIDE_OUTPUT_TEXT, FI_HIDE_INPUT_IMAGES, and FI_HIDE_EMBEDDING_VECTORS before initialization. Set each to true to hide that content.

FI_HIDE_ERROR_DETAILS=true hides error descriptions, exception messages, and stack traces while keeping status and error types. When unset, it follows the input/output value, message, and text hide flags. Explicit false overrides the derived value. See the configuration implementation and the cross-language privacy guide.

Use your OpenTelemetry pipeline

Pass your own OpenTelemetry TracerProvider to OpenAIInstrumentor().instrument(tracer_provider=provider) to use an existing exporter. The register() helper configures Future AGI by default. On current source, register(span_exporter=...) replaces that destination; older published versions may not include this option.

Provider setup · Examples

Packages

Each package below links to its own installation instructions, supported SDK versions, and examples. Package availability and framework support are independent; do not assume every package supports the same upstream version.

Contributing and license

Read the contributing guide. Licensed under Apache 2.0.