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
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__))
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:
@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:
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))
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
@tracer.chain
def decorated_chain_with_plain_text_output(input: str) -> str:
return "output"
decorated_chain_with_plain_text_output("input")
Using JSON Output
@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
@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))
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
@tracer.agent
def decorated_agent(input: str) -> str:
return "output"
decorated_agent("input")
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))
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
@tracer.tool
def decorated_tool(input1: str, input2: int) -> None:
"""
tool-description
"""
pass
decorated_tool("input1", 1)
@tracer.tool(
name="decorated-tool-with-overriden-name",
description="overriden-tool-description",
)
def this_tool_name_should_be_overriden(input1: str, input2: int) -> None:
"""
this tool description should be overriden
"""
pass
this_tool_name_should_be_overriden("input1", 1)
Additional Features
Suppress Tracing
with suppress_tracing():
with tracer.start_as_current_span(
"THIS-SPAN-SHOULD-NOT-BE-TRACED",
fi_span_kind="chain",
) as span:
span.set_input("input")
span.set_output("output")
span.set_status(Status(StatusCode.OK))
with suppress_tracing():
with tracer.start_as_current_span(
"THIS-SPAN-SHOULD-NOT-BE-TRACED",
fi_span_kind="chain",
) as span:
span.set_input("input")
span.set_output("output")
span.set_status(Status(StatusCode.OK))
suppressTracing(() => {
tracer.startActiveSpan(
"THIS-SPAN-SHOULD-NOT-BE-TRACED",
{ attributes: { "fi.span.kind": "chain" } },
(span) => {
span.setAttribute("input", "input");
span.setAttribute("output", "output");
span.setStatus({ code: SpanStatusCode.OK });
span.end();
}
);
});
Using Context Attributes
with using_attributes(session_id="123"):
with tracer.start_as_current_span(
"chain-span-with-context-attributes",
fi_span_kind="chain",
) as span:
span.set_input("input")
span.set_output("output")
span.set_status(Status(StatusCode.OK))
with using_attributes(session_id="123"):
with tracer.start_as_current_span(
"chain-span-with-context-attributes",
fi_span_kind="chain",
) as span:
span.set_input("input")
span.set_output("output")
span.set_status(Status(StatusCode.OK))
const newContext = propagation.setBaggage(
context.active(),
propagation.createBaggage({ "session_id": { value: "123" } })
);
context.with(newContext, () => {
tracer.startActiveSpan(
"chain-span-with-context-attributes",
{ attributes: { "fi.span.kind": "chain" } },
(span) => {
span.setAttribute("input", "input");
span.setAttribute("output", "output");
span.setStatus({ code: SpanStatusCode.OK });
span.end();
}
);
});
This guide demonstrates the comprehensive capabilities of Future AGI OTEL tracing decorators for instrumenting chains, agents, and tools.
