Set Up Tracing
Connect your application to Future AGI by registering a tracer provider and adding instrumentation — either via auto-instrumentors or manual OpenTelemetry spans.
What it is
Set Up Tracing is the foundational step that connects your application to Future AGI. It uses the register() helper to configure an OpenTelemetry-compliant TracerProvider scoped to a project — either an Observe project for production monitoring or an Experiment project for prompt testing. Once registered, you add instrumentation through auto-instrumentors (for supported frameworks like OpenAI or LangChain) or through manual spans using FITracer. All spans are exported to Future AGI over HTTP or gRPC and appear in the project dashboard for trace inspection, evals, and alerts.
Use cases
- Production monitoring — Register an Observe project and auto-instrument LLM calls so every request is traced with latency, cost, and token usage.
- Experiment tracking — Register an Experiment project with eval tags and version names to compare prompt or model changes across runs.
- Custom spans — Use
FITracerto manually create spans for non-standard operations, nested workflows, or tool calls that auto-instrumentors don’t cover. - Privacy control — Use
TraceConfigto redact sensitive inputs, outputs, or messages before they leave your app. - Framework agnostic — Works with any Python or JS/TS application via OpenTelemetry; auto-instrumentors cover 20+ frameworks.
How to
Install packages
Install the core instrumentation package and any framework-specific instrumentors you need.
pip install fi-instrumentation-otel
pip install traceAI-openai # or any other framework instrumentornpm install @traceai/fi-core
npm install @traceai/openai # or any other framework instrumentor For gRPC transport, install the optional dependency:
pip install "fi-instrumentation-otel[grpc]" Set environment variables
Set your API credentials. Get your keys from the dashboard.
import os
os.environ["FI_API_KEY"] = "your-futureagi-api-key"
os.environ["FI_SECRET_KEY"] = "your-futureagi-secret-key"process.env.FI_API_KEY = FI_API_KEY;
process.env.FI_SECRET_KEY = FI_SECRET_KEY; Register a tracer provider
Call register() to initialize a configured TracerProvider. This is the single setup call that handles OTLP exporter config, project scoping, and span processing.
from traceai_openai import OpenAIInstrumentor
from fi_instrumentation import register
# Initialize OTel using our register function
trace_provider = register(
project_type=ProjectType.EXPERIMENT,
project_name="FUTURE_AGI",
project_version_name="openai-exp",
)const { register, ProjectType } = require("@traceai/fi-core");
const traceProvider = register({
project_type: ProjectType.OBSERVE,
project_name: "FUTURE_AGI"
}); register() parameters:
| Parameter | Type | Default | Description |
|---|---|---|---|
project_name | str | env var | Project identifier in the dashboard |
project_type | ProjectType | EXPERIMENT | OBSERVE for production monitoring; EXPERIMENT for prompt testing |
project_version_name | str | env var | Version label — EXPERIMENT only |
eval_tags | List[EvalTag] | — | Custom eval configs — EXPERIMENT only |
transport | Transport | HTTP | HTTP (default) or GRPC |
batch | bool | True | Use BatchSpanProcessor; set False for synchronous export |
set_global_tracer_provider | bool | False | Register as the global OTel default |
metadata | Dict | — | Custom metadata attached to the project |
verbose | bool | True | Print config details on startup |
ProjectType options:
| Value | Use for |
|---|---|
ProjectType.OBSERVE | Production monitoring — traces, sessions, evals, alerts |
ProjectType.EXPERIMENT | Prompt experiments — supports eval tags and version names |
Transport options:
| Value | Protocol | Notes |
|---|---|---|
Transport.HTTP | HTTP/REST | Default; no extra dependencies |
Transport.GRPC | gRPC | Requires fi-instrumentation-otel[grpc] |
Add instrumentation
Choose auto-instrumentation for supported frameworks, or use FITracer for manual spans.
OpenAIInstrumentor().instrument(tracer_provider=trace_provider)const { OpenAIInstrumentation } = require("@traceai/openai");
const openaiInstrumentation = new OpenAIInstrumentation({});
registerInstrumentations({
instrumentations: [openaiInstrumentation],
tracerProvider: tracerProvider,
}); Supported auto-instrumentors:
FITracer wraps the standard OTel tracer and adds Future AGI-specific features: automatic input/output capture, context injection, and decorator support.
from opentelemetry import trace
trace.set_tracer_provider(trace_provider)
tracer = trace.get_tracer(__name__)const { trace, context } = require("@opentelemetry/api");
const { AsyncLocalStorageContextManager } = require("@opentelemetry/context-async-hooks");
const { register } = require("@traceai/fi-core");
const { ProjectType } = require("@traceai/fi-core");
const { registerInstrumentations } = require("@opentelemetry/instrumentation");
// Activate a context manager for consistent context propagation
context.setGlobalContextManager(new AsyncLocalStorageContextManager());
// Initialize and get a tracer using our register function
const traceProvider = register({
project_type: ProjectType.OBSERVE,
project_name: "FUTURE_AGI"
});
const tracer = traceProvider.getTracer("manual-instrumentation-example"); Create spans (manual tracing)
Use context managers, nested spans, or decorators for full control over span structure.
def process_operation():
with tracer.start_as_current_span("span-name") as span:
# Execute operations tracked by 'span'
print("doing some work...")
# When the 'with' block goes out of scope, 'span' is automatically closedfunction processOperation() {
const q1 = () => tracer.startActiveSpan('processOperation', (span) => {
span.setAttribute('operation', 'processOperation');
span.end();
});
const q2 = () => tracer.startActiveSpan('processChildOperation', (span) => {
span.setAttribute('operation', 'processChildOperation');
span.end();
});
q1();
q2();
} def process_operation():
with tracer.start_as_current_span("parent") as parent:
# Execute parent-level operations
print("doing some work...")
# Create nested span for sub-operations
with tracer.start_as_current_span("child") as child:
# Execute child-level operations
print("doing some nested work...")
# Child span closes automatically when it's out of scopefunction processOperation() {
tracer.startActiveSpan("parent", (parentSpan) => {
console.log("doing some work...");
tracer.startActiveSpan("child", (childSpan) => {
console.log("doing some nested work...");
childSpan.end();
});
parentSpan.end();
});
} @tracer.start_as_current_span("process_operation")
def process_operation():
print("doing some work...")// JavaScript doesn't have decorators in the same way, but you can achieve similar functionality
const decoratedFunction = (fn) => {
return (...args) => {
return tracer.startActiveSpan("process_operation", (span) => {
try {
const result = fn(...args);
span.end();
return result;
} catch (error) {
span.recordException(error);
span.end();
throw error;
}
});
};
};
const processOperation = decoratedFunction(() => {
console.log("doing some work...");
}); Key concepts
register()— Single setup call that configures the OTLP exporter, span processor, and project scope. Returns aTracerProvider.FITracer— Future AGI wrapper around the standard OTel tracer. Addsset_input()/set_output()on spans, automatic context injection, and@tracer.agent()/@tracer.chain()/@tracer.tool()decorators.ProjectType.OBSERVE— Routes spans to an Observe project for production monitoring (sessions, evals, alerts). Does not support eval tags or version names.ProjectType.EXPERIMENT— Routes spans to an Experiment project. Supportseval_tagsandproject_version_namefor comparing runs.Transport—HTTP(default, no extra deps) orGRPC(requiresfi-instrumentation-otel[grpc]).TraceConfig— Optional privacy config passed to instrumentors to redact inputs, outputs, messages, images, or embedding vectors before export.
What you can do next
Auto Instrumentation
Browse all supported framework instrumentors.
Instrument with TraceAI
Use TraceAI helpers for sessions, users, and context.
Add Attributes & Metadata
Attach custom data to spans for filtering and evals.
Set Session & User ID
Group traces into sessions and link them to end users.
Mask Span Attributes
Redact sensitive data with TraceConfig before export.
Set Up Observability
Register an Observe project and start capturing traces.