Skip to content

rewrite manual tracing instrument with traceAI helpers #555

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
hadarishav merged 1 commit into from
Apr 4, 2026
Merged

rewrite manual tracing instrument with traceAI helpers #555

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
156 changes: 66 additions & 90 deletions src/pages/docs/observe/features/manual-tracing/instrument-with-traceai-helpers.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -3,17 +3,19 @@ title: "Instrument with traceAI Helpers"
description: "Future AGI's traceAI library offers convenient abstractions to streamline your manual instrumentation process."
---

## What it is
## About

**Instrument with traceAI Helpers** gives you a set of Python and JS/TS utilities that sit on top of OpenTelemetry and make manual instrumentation faster and more expressive. Instead of writing raw OTEL boilerplate, you use `FITracer` — a Future AGI wrapper around the standard tracer — to decorate functions or wrap code blocks as typed spans (chain, agent, tool, LLM, retriever). Spans automatically capture inputs, outputs, and status; span kinds control how they render in the Future AGI UI.
Manual tracing with raw OpenTelemetry means writing a lot of setup code for every function you want to track. traceAI helpers solve this. Add a one-line decorator like `@tracer.chain` or `@tracer.tool` to a function, and inputs, outputs, and status are captured automatically. For more control, wrap a code block with a context manager and set values yourself. Each span gets a type (chain, agent, tool, LLM, retriever) that determines how it appears in the dashboard, so you can tell at a glance what each step in a trace is doing.

## Use cases
---

## When to use

- **Function-level tracing** — Decorate a function with `@tracer.chain`, `@tracer.agent`, or `@tracer.tool` and the entire call is captured as a span with automatic input/output.
- **Code block tracing** — Wrap any code segment with `tracer.start_as_current_span` for precise control over what gets captured without instrumenting a whole function.
- **Typed spans** — Use FI Span Kinds (`chain`, `agent`, `tool`, `llm`, `retriever`) so spans are rendered with the right icon and label in the dashboard.
- **Tool metadata** — Attach tool name, description, and parameters to tool spans so the dashboard shows full tool call context.
- **Mixed workflows** — Combine decorators (for complete functions) and context managers (for sub-operations) in the same codebase.
- **Function-level tracing**: Decorate a function with `@tracer.chain`, `@tracer.agent`, or `@tracer.tool` and the entire call is captured as a span with automatic input/output.
- **Code block tracing**: Wrap any code segment with `tracer.start_as_current_span` for precise control over what gets captured.
- **Typed spans**: Use FI Span Kinds (`chain`, `agent`, `tool`, `llm`, `retriever`) so spans render with the right icon and label in the dashboard.
- **Tool metadata**: Attach tool name, description, and parameters to tool spans so the dashboard shows full tool call context.
- **Mixed workflows**: Combine decorators (for complete functions) and context managers (for sub-operations) in the same codebase.

---

Expand All @@ -23,11 +25,11 @@ description: "Future AGI's traceAI library offers convenient abstractions to str
<Step title="Install the instrumentation package">
<CodeGroup>

```bash Python
```python Python
pip install fi-instrumentation-otel
```

```bash JS/TS
```javascript JS/TS
npm install @traceai/fi-core
```

Expand Down Expand Up @@ -235,83 +237,57 @@ description: "Future AGI's traceAI library offers convenient abstractions to str
</Tab>

<Tab title="LLM">
Use LLM spans for direct LLM calls.

<Tabs>
<Tab title="Using Context Managers">
<CodeGroup>

```python Python
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))
```

```javascript JS/TS
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();
});
```

</CodeGroup>
</Tab>
<Tab title="Using Decorators">
```python Python
@tracer.llm
def decorated_llm(input: str) -> str:
return "output"

decorated_llm("input")
```
</Tab>
</Tabs>
Use LLM spans for direct LLM calls. LLM spans only support context managers (no decorator available).

<CodeGroup>

```python Python
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))
```

```javascript JS/TS
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();
});
```

</CodeGroup>
</Tab>

<Tab title="Retriever">
Use retriever spans for document retrieval operations.

<Tabs>
<Tab title="Using Context Managers">
<CodeGroup>

```python Python
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))
```

```javascript JS/TS
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();
});
```

</CodeGroup>
</Tab>
<Tab title="Using Decorators">
```python Python
@tracer.retriever
def decorated_retriever(input: str) -> str:
return "output"

decorated_retriever("input")
```
</Tab>
</Tabs>
Use retriever spans for document retrieval operations. Retriever spans only support context managers (no decorator available).

<CodeGroup>

```python Python
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))
```

```javascript JS/TS
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();
});
```

</CodeGroup>
</Tab>
</Tabs>
</Step>
Expand All @@ -321,11 +297,11 @@ description: "Future AGI's traceAI library offers convenient abstractions to str

## Key concepts

- **`FITracer`** — Future AGI wrapper around the standard OTel tracer. Adds `set_input()` / `set_output()` / `set_tool()` on spans, automatic context injection, and typed decorators (`@tracer.chain`, `@tracer.agent`, `@tracer.tool`, `@tracer.llm`, `@tracer.retriever`).
- **FI Span Kinds** — Typed labels that control how spans are rendered in the Future AGI UI. Set via `fi_span_kind` in Python or `fi.span.kind` attribute in JS/TS.
- **Decorators** — Wrap entire functions; input/output/status are captured automatically from function args and return values.
- **Context managers** — Wrap specific code blocks; you must call `set_input()`, `set_output()`, and `set_status()` manually.
- **`set_tool()`** — Sets `tool.name`, `tool.description`, and `tool.parameters` on a tool span for full call context in the dashboard.
- **`FITracer`**: Future AGI wrapper around the standard OTel tracer. Adds `set_input()` / `set_output()` / `set_tool()` on spans, automatic context injection, and typed decorators (`@tracer.chain`, `@tracer.agent`, `@tracer.tool`, `@tracer.llm`, `@tracer.retriever`).
- **FI Span Kinds**: Typed labels that control how spans are rendered in the Future AGI UI. Set via `fi_span_kind` in Python or `fi.span.kind` attribute in JS/TS.
- **Decorators**: Wrap entire functions. Input/output/status are captured automatically from function args and return values.
- **Context managers**: Wrap specific code blocks. You call `set_input()`, `set_output()`, and `set_status()` manually.
- **`set_tool()`**: Sets `tool.name`, `tool.description`, and `tool.parameters` on a tool span for full call context in the dashboard.

**FI Span Kinds reference:**

Expand All @@ -344,7 +320,7 @@ description: "Future AGI's traceAI library offers convenient abstractions to str

---

## What you can do next
## Next Steps

<CardGroup cols={2}>
<Card title="Set Up Tracing" icon="gear" href="/docs/observe/features/manual-tracing/set-up-tracing">
Expand Down