What is traceAI?

Your agent calls an LLM, retrieves context, invokes a tool, and returns an answer. When that answer is wrong, you need to know exactly where it broke - which retrieval missed, which tool returned stale data, which prompt drifted.

traceAI captures every LLM call, prompt, token count, retrieval step, and agent decision as structured OpenTelemetry traces. Your traces live natively in Datadog, Grafana, Future AGI, Jaeger, or any OTel-compatible backend. No new vendor. No new dashboard.

• Drop-in instrumentation for 50+ AI frameworks across 4 languages
• OpenTelemetry-native - works with any OTel-compatible backend
• Semantic conventions for LLM calls, agents, tools, retrieval, and vector databases
• Python, TypeScript, Java, and C# with consistent APIs

Table of Contents

• Key Features
• Quickstart
  • Python
  • TypeScript
  • Java
  • C#
• Supported Frameworks
  • Python
  • TypeScript
  • Java
  • C#
• Compatibility Matrix
• Architecture
• Roadmap
• Contributing
• Contributors
• Resources
• Connect With Us

Key Features

Quickstart

Python Quickstart

1. Install

pip install traceai-openai

2. Instrument your application

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

# Set up environment variables
os.environ["FI_API_KEY"] = "<your-api-key>"
os.environ["FI_SECRET_KEY"] = "<your-secret-key>"
os.environ["OPENAI_API_KEY"] = "<your-openai-key>"

# Register tracer provider
trace_provider = register(
    project_type=ProjectType.OBSERVE,
    project_name="my_ai_app"
)

# Instrument OpenAI
OpenAIInstrumentor().instrument(tracer_provider=trace_provider)

# Use OpenAI as normal - traces are captured automatically
response = openai.chat.completions.create(
    model="gpt-4.1",
    messages=[{"role": "user", "content": "Hello!"}]
)

Tip: Swap traceai-openai for any supported framework (e.g., traceai-langchain, traceai-anthropic)

TypeScript Quickstart

1. Install

npm install @traceai/openai @traceai/fi-core

2. Instrument your application

import { register, ProjectType } from "@traceai/fi-core";
import { OpenAIInstrumentation } from "@traceai/openai";
import { registerInstrumentations } from "@opentelemetry/instrumentation";
import OpenAI from "openai";

// Register tracer provider
const tracerProvider = register({
  projectName: "my_ai_app",
  projectType: ProjectType.OBSERVE,
});

// Register OpenAI instrumentation (before creating client!)
registerInstrumentations({
  tracerProvider,
  instrumentations: [new OpenAIInstrumentation()],
});

// Use OpenAI as normal - traces are captured automatically
const openai = new OpenAI({ apiKey: process.env.OPENAI_API_KEY });

const response = await openai.chat.completions.create({
  model: "gpt-4.1",
  messages: [{ role: "user", content: "Hello!" }],
});

Java Quickstart

1. Add dependency (via JitPack)

<dependency>
    <groupId>com.github.future-agi.traceAI</groupId>
    <artifactId>traceai-java-openai</artifactId>
    <version>v1.0.0</version>
</dependency>

2. Instrument your application

import ai.traceai.TraceAI;
import ai.traceai.TraceConfig;
import ai.traceai.openai.TracedOpenAIClient;

// Initialize tracing
TraceAI.init(TraceConfig.builder()
    .apiKey("your-api-key")
    .secretKey("your-secret-key")
    .projectName("my_ai_app")
    .build());

// Wrap your OpenAI client
var tracedClient = new TracedOpenAIClient(openAIClient);

// Use as normal - traces are captured automatically
var response = tracedClient.createChatCompletion(request);

C# Quickstart

1. Install

dotnet add package fi-instrumentation-otel

2. Instrument your application

using FIInstrumentation;
using FIInstrumentation.Types;

// Register tracer
var tracer = TraceAI.Register(opts =>
{
    opts.ProjectName = "my_ai_app";
    opts.ProjectType = ProjectType.Observe;
    opts.ApiKey = "your-api-key";
    opts.SecretKey = "your-secret-key";
});

// Use the tracer with your AI calls

Supported Frameworks

Python

Package	Description	Version
fi-instrumentation-otel	Core instrumentation library

LLM Providers

Package	Description	Version
traceAI-openai	OpenAI
traceAI-anthropic	Anthropic
traceAI-google-genai	Google Generative AI
traceAI-vertexai	Google Vertex AI
traceAI-bedrock	AWS Bedrock
traceAI-mistralai	Mistral AI
traceAI-groq	Groq
traceAI-litellm	LiteLLM
traceAI-cohere	Cohere
traceAI-ollama	Ollama
traceAI-together	Together AI
traceAI-deepseek	DeepSeek
traceAI-fireworks	Fireworks AI
traceAI-cerebras	Cerebras
traceAI-huggingface	HuggingFace
traceAI-xai	xAI (Grok)
traceAI-vllm	vLLM

Agent Frameworks

Package	Description	Version
traceAI-langchain	LangChain
traceAI-llamaindex	LlamaIndex
traceAI-crewai	CrewAI
traceAI-openai-agents	OpenAI Agents
traceAI-smolagents	SmolAgents
traceAI-autogen	AutoGen
traceAI-google-adk	Google ADK
traceAI-agno	Agno
traceAI-pydantic-ai	Pydantic AI
traceAI-claude-agent-sdk	Claude Agent SDK
traceAI-strands	AWS Strands Agents
traceAI-beeai	IBM BeeAI

Tools and Libraries

Package	Description	Version
traceAI-haystack	Haystack
traceAI-dspy	DSPy
traceAI-guardrails	Guardrails AI
traceAI-instructor	Instructor
traceAI-portkey	Portkey
traceAI-mcp	Model Context Protocol
traceAI-pipecat	Pipecat (Voice AI)
traceAI-livekit	LiveKit (Real-time)

Vector Databases

Package	Description	Version
traceAI-pinecone	Pinecone
traceAI-chromadb	ChromaDB
traceAI-qdrant	Qdrant
traceAI-weaviate	Weaviate
traceAI-milvus	Milvus
traceAI-lancedb	LanceDB
traceAI-mongodb	MongoDB Atlas Vector Search
traceAI-pgvector	pgvector (PostgreSQL)
traceAI-redis	Redis Vector Search

TypeScript

Package	Description	Version
@traceai/fi-core	Core instrumentation library
@traceai/fi-semantic-conventions	Semantic conventions

LLM Providers

Package	Description	Version
@traceai/openai	OpenAI
@traceai/anthropic	Anthropic
@traceai/google-genai	Google Generative AI
@traceai/fi-instrumentation-vertexai	Google Vertex AI
@traceai/bedrock	AWS Bedrock
@traceai/mistral	Mistral AI
@traceai/groq	Groq
@traceai/cohere	Cohere
@traceai/ollama	Ollama
@traceai/together	Together AI
@traceai/deepseek	DeepSeek
@traceai/fireworks	Fireworks AI
@traceai/cerebras	Cerebras
@traceai/huggingface	HuggingFace
@traceai/xai	xAI (Grok)
@traceai/vllm	vLLM

Agent Frameworks

Package	Description	Version
@traceai/langchain	LangChain.js
@traceai/llamaindex	LlamaIndex
@traceai/openai-agents	OpenAI Agents
@traceai/fi-instrumentation-google-adk	Google ADK
@traceai/mastra	Mastra
@traceai/beeai	IBM BeeAI
@traceai/strands	AWS Strands Agents

Tools and Libraries

Package	Description	Version
@traceai/vercel	Vercel AI SDK
@traceai/guardrails	Guardrails AI
@traceai/instructor	Instructor
@traceai/portkey	Portkey
@traceai/mcp	Model Context Protocol
@traceai/fi-instrumentation-pipecat	Pipecat (Voice AI)
@traceai/fi-instrumentation-livekit	LiveKit (Real-time)

Vector Databases

Package	Description	Version
@traceai/pinecone	Pinecone
@traceai/chromadb	ChromaDB
@traceai/qdrant	Qdrant
@traceai/weaviate	Weaviate
@traceai/milvus	Milvus
@traceai/lancedb	LanceDB
@traceai/mongodb	MongoDB Atlas Vector Search
@traceai/pgvector	pgvector (PostgreSQL)
@traceai/redis	Redis Vector Search

Java

Available via JitPack. Add the JitPack repository:

<repositories>
    <repository>
        <id>jitpack.io</id>
        <url>https://jitpack.io</url>
    </repository>
</repositories>

LLM Providers

Agent Frameworks

Vector Databases

C#

Available on NuGet.

Package	Description	Version
fi-instrumentation-otel	Core instrumentation library

Compatibility Matrix

Legend: ✅ Supported | blank = not yet available

Architecture

traceAI is built on top of OpenTelemetry and follows standard OTel instrumentation patterns:

Full OpenTelemetry Compatibility

• Works with any OTel-compatible backend
• Standard OTLP exporters (HTTP/gRPC)
• Compatible with existing OTel setups

Bring Your Own Configuration

You can use traceAI with your own OpenTelemetry setup:

from opentelemetry import trace
from opentelemetry.sdk.trace import TracerProvider
from opentelemetry.sdk.trace.export import BatchSpanProcessor
from opentelemetry.exporter.otlp.proto.http.trace_exporter import OTLPSpanExporter
from traceai_openai import OpenAIInstrumentor

# Set up your own tracer provider
tracer_provider = TracerProvider()
trace.set_tracer_provider(tracer_provider)

# Add custom exporters (example with Future AGI)
otlp_exporter = OTLPSpanExporter(
    endpoint="https://api.futureagi.com/tracer/v1/traces",
    headers={
        "X-API-KEY": "your-api-key",
        "X-SECRET-KEY": "your-secret-key"
    }
)
tracer_provider.add_span_processor(BatchSpanProcessor(otlp_exporter))

# Instrument with traceAI
OpenAIInstrumentor().instrument(tracer_provider=tracer_provider)

import { NodeTracerProvider } from "@opentelemetry/sdk-trace-node";
import { BatchSpanProcessor } from "@opentelemetry/sdk-trace-base";
import { OTLPTraceExporter } from "@opentelemetry/exporter-trace-otlp-http";
import { Resource } from "@opentelemetry/resources";
import { registerInstrumentations } from "@opentelemetry/instrumentation";
import { OpenAIInstrumentation } from "@traceai/openai";

const provider = new NodeTracerProvider({
  resource: new Resource({ "service.name": "my-ai-service" }),
});

const exporter = new OTLPTraceExporter({
  url: "https://api.futureagi.com/tracer/v1/traces",
  headers: {
    "X-API-KEY": process.env.FI_API_KEY!,
    "X-SECRET-KEY": process.env.FI_SECRET_KEY!,
  },
});

provider.addSpanProcessor(new BatchSpanProcessor(exporter));
provider.register();

registerInstrumentations({
  tracerProvider: provider,
  instrumentations: [new OpenAIInstrumentation()],
});

What Gets Captured

traceAI automatically captures rich telemetry data:

• Prompts & Completions: Full request/response content
• Token Usage: Input, output, and total tokens
• Model Parameters: Temperature, top_p, max_tokens, etc.
• Tool Calls: Function/tool names, arguments, and results
• Streaming: Individual chunks with delta tracking
• Errors: Detailed error context and stack traces
• Timing: Latency at each step of the AI workflow

All data follows OpenTelemetry Semantic Conventions for GenAI.

Roadmap

• Go language support
• Sampling strategies for high-volume production environments
• Continuous semantic convention updates as the OTel GenAI spec evolves
• Evaluation integration connecting traces to quality measurement pipelines
• Expanded agent framework coverage

Request features or report bugs on GitHub Issues.

Contributing

We welcome contributions! Read our Contributing Guide for details.

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

Found a bug? Open an issue with a minimal reproduction.

Contributors

Resources

Connect With Us