Instrument with traceAI Helpers

traceAI OTEL Tracing

Learn how to leverage traceAI OTEL tracing decorators and methods to instrument your functions, chains, agents, and tools with OpenTelemetry. These utilities complement or replace standard OpenTelemetry instrumentation code, making the process more straightforward and efficient.

Installation

Ensure you have FI Instrumentation Library installed:

pip install fi-instrumentation-otel

npm install @traceai/fi-core

Setting Up Tracing

Initialize your tracing environment with the following setup:

from fi_instrumentation import register, FITracer
from fi_instrumentation.fi_types import ProjectType

# Setup OTel via our register function
trace_provider = register(
    project_type=ProjectType.EXPERIMENT,
    project_name="FUTURE_AGI",
    project_version_name="openai-exp",
)

tracer = FITracer(trace_provider.get_tracer(__name__))

const { trace, context, SpanStatusCode, propagation } = require("@opentelemetry/api");
const { AsyncLocalStorageContextManager } = require("@opentelemetry/context-async-hooks");
const { register, ProjectType } = require("@traceai/fi-core");
const { registerInstrumentations } = require("@opentelemetry/instrumentation");
const { suppressTracing } = require("@opentelemetry/core");

context.setGlobalContextManager(new AsyncLocalStorageContextManager());

const tracerProvider = register({
    projectName: "manual-instrumentation-example",
    projectType: ProjectType.OBSERVE,
    sessionName: "manual-instrumentation-example-session"
});

const tracer = tracerProvider.getTracer("manual-instrumentation-example");

Using your Tracer

The tracer object provides two main approaches for instrumentation:

1. Function Decoration

Use decorators to trace complete functions:

Python

@tracer.chain
def my_func(input: str) -> str:
    return "output"

When using this method, the entire function execution will be visible as a Span in Future AGI. Function parameters and return values automatically populate input and output attributes, while the status is set automatically.

2. Code Block Tracing

Utilize context managers to trace specific code segments:

Python

from opentelemetry.trace.status import Status, StatusCode

with tracer.start_as_current_span(
    "my-span-name",
    fi_span_kind="chain",
) as span:
    span.set_input("input")
    span.set_output("output")
    span.set_status(Status(StatusCode.OK))

The code within this clause will be captured as a Span in Future AGI. Here the input, output, and status must be set manually. This method is particularly useful when you need to monitor specific portions of your code rather than entire functions.

FI Span Kinds

FI Span Kinds denote the possible types of spans you might capture, and will be rendered different in the Future AGI UI. The possible values are:

Span Kind	Use
CHAIN	General logic operations, functions, or code blocks
LLM	Making LLM calls
TOOL	Completing tool calls
RETRIEVER	Retrieving documents
EMBEDDING	Generating embeddings
AGENT	Agent invocations - typically a top level or near top level span
RERANKER	Reranking retrieved context
UNKNOWN	Unknown
GUARDRAIL	Guardrail checks
EVALUATOR	Evaluators

Chains

Using Context Managers

from opentelemetry.trace.status import Status, StatusCode

with tracer.start_as_current_span(
    "my-span-name",
    fi_span_kind="chain",
) as span:
    span.set_input("input")
    span.set_output("output")
    span.set_status(Status(StatusCode.OK))

tracer.startActiveSpan("my-span-name", { attributes: { "fi.span.kind": "chain" } }, (span) => {
    span.setAttribute("input", "input");
    span.setAttribute("output", "output");
    span.setStatus({ code: SpanStatusCode.OK });
    span.end();
});

Using Decorators

Python

@tracer.chain
def decorated_chain_with_plain_text_output(input: str) -> str:
    return "output"

decorated_chain_with_plain_text_output("input")

Using JSON Output

Python

@tracer.chain
def decorated_chain_with_json_output(input: str) -> Dict[str, Any]:
    return {"output": "output"}

decorated_chain_with_json_output("input")

Overriding Span Name

Python

@tracer.chain(name="decorated-chain-with-overriden-name")
def this_name_should_be_overriden(input: str) -> Dict[str, Any]:
    return {"output": "output"}

this_name_should_be_overriden("input")

Agents

Using Context Managers

with tracer.start_as_current_span(
    "agent-span-with-plain-text-io",
    fi_span_kind="agent",
) as span:
    span.set_input("input")
    span.set_output("output")
    span.set_status(Status(StatusCode.OK))

tracer.startActiveSpan("agent-span-with-plain-text-io", { attributes: { "fi.span.kind": "agent" } }, (span) => {
    span.setAttribute("input", "input");
    span.setAttribute("output", "output");
    span.setStatus({ code: SpanStatusCode.OK });
    span.end();
});

Using Decorators

Python

@tracer.agent
def decorated_agent(input: str) -> str:
    return "output"

decorated_agent("input")

Tools

Using Context Managers

with tracer.start_as_current_span(
    "tool-span",
    fi_span_kind="tool",
) as span:
    span.set_input("input")
    span.set_output("output")
    span.set_tool(
        name="tool-name",
        description="tool-description",
        parameters={"input": "input"},
    )
    span.set_status(Status(StatusCode.OK))

tracer.startActiveSpan("tool-span", { attributes: { "fi.span.kind": "tool" } }, (span) => {
    span.setAttribute("input", "input");
    span.setAttribute("output", "output");
    span.setAttribute("tool.name", "tool-name");
    span.setAttribute("tool.description", "tool-description");
    span.setAttribute("tool.parameters", JSON.stringify({"input": "input"}));
    span.setStatus({ code: SpanStatusCode.OK });
    span.end();
});

Using Decorators

Python

@tracer.tool(
    name="tool-name",
    description="tool-description",
    parameters={"input": "input"},
)
def decorated_tool(input: str) -> str:
    return "output"

decorated_tool("input")

LLM

Using Context Managers

with tracer.start_as_current_span(
    "llm-span",
    fi_span_kind="llm",
) as span:
    span.set_input("input")
    span.set_output("output")
    span.set_status(Status(StatusCode.OK))

tracer.startActiveSpan("llm-span", { attributes: { "fi.span.kind": "llm" } }, (span) => {
    span.setAttribute("input", "input");
    span.setAttribute("output", "output");
    span.setStatus({ code: SpanStatusCode.OK });
    span.end();
});

Using Decorators

Python

@tracer.llm
def decorated_llm(input: str) -> str:
    return "output"

decorated_llm("input")

Retriever

Using Context Managers

with tracer.start_as_current_span(
    "retriever-span",
    fi_span_kind="retriever",
) as span:
    span.set_input("input")
    span.set_output("output")
    span.set_status(Status(StatusCode.OK))

tracer.startActiveSpan("retriever-span", { attributes: { "fi.span.kind": "retriever" } }, (span) => {
    span.setAttribute("input", "input");
    span.setAttribute("output", "output");
    span.setStatus({ code: SpanStatusCode.OK });
    span.end();
});

Using Decorators

Python

@tracer.retriever
def decorated_retriever(input: str) -> str:
    return "output"

decorated_retriever("input")

Get Started

Guides

traceAI OTEL Tracing

Installation

Setting Up Tracing

Using your Tracer

1. Function Decoration

2. Code Block Tracing

FI Span Kinds

Chains

Using Context Managers

Using Decorators

Using JSON Output

Overriding Span Name

Agents

Using Context Managers

Using Decorators

Tools

Using Context Managers

Using Decorators

LLM

Using Context Managers

Using Decorators

Retriever

Using Context Managers

Using Decorators

​traceAI OTEL Tracing

​Installation

​Setting Up Tracing

​Using your Tracer

​1. Function Decoration

​2. Code Block Tracing

​FI Span Kinds

​Chains

​Using Context Managers

​Using Decorators

​Using JSON Output

​Overriding Span Name

​Agents

​Using Context Managers

​Using Decorators

​Tools

​Using Context Managers

​Using Decorators

​LLM

​Using Context Managers

​Using Decorators

​Retriever

​Using Context Managers

​Using Decorators

traceAI OTEL Tracing

Installation

Setting Up Tracing

Using your Tracer

1. Function Decoration

2. Code Block Tracing

FI Span Kinds

Chains

Using Context Managers

Using Decorators

Using JSON Output

Overriding Span Name

Agents

Using Context Managers

Using Decorators

Tools

Using Context Managers

Using Decorators

LLM

Using Context Managers

Using Decorators

Retriever

Using Context Managers

Using Decorators