> ## Documentation Index
> Fetch the complete documentation index at: https://docs.decimal.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Tracing

> Decorators and helpers to record LLM calls, tool calls, and trace boundaries from Python.

The tracing API has four entry points: `@trace`, `start_trace`, `log_llm_call`, and `log_tool_call`. Plus `@tool` to register a function as a tracked tool. Use the framework-specific [auto-instrumentation](/sdk/python/frameworks) instead when possible — these are the manual escape hatches.

***

## `@decimalai.trace()`

Decorator to trace a function as a complete agent run.

```python theme={null}
@decimalai.trace(agent_name="my-agent")
def run_agent(query: str) -> str:
    response = openai.chat.completions.create(
        model="gpt-4o",
        messages=[{"role": "user", "content": query}],
    )
    return response.choices[0].message.content

# Every call to run_agent() creates a trace
result = run_agent("What is the capital of France?")
```

<ParamField path="agent_name" type="str" required>
  Name of the agent (appears in dashboard sidebar).
</ParamField>

***

## `decimalai.start_trace()`

Context manager for manual trace boundaries.

```python theme={null}
with decimalai.start_trace(agent_name="my-agent") as ctx:
    # Everything inside this block is part of one trace
    decimalai.log_llm_call(
        model="gpt-4o",
        input=[{"role": "user", "content": "Hello"}],
        output={"content": "Hi there!"},
    )
```

***

## `decimalai.log_llm_call()`

Log an individual LLM call inside a trace.

```python theme={null}
decimalai.log_llm_call(
    model="gpt-4o",
    input=[{"role": "user", "content": "Hello"}],
    output={"content": "Hi there!"},
    input_tokens=5,
    output_tokens=3,
    latency_ms=320,
)
```

<ParamField path="model" type="str" required>
  Model identifier (e.g., `"gpt-4o"`, `"claude-sonnet-4-6"`).
</ParamField>

<ParamField path="input" type="list | dict | str">
  Input messages or prompt.
</ParamField>

<ParamField path="output" type="dict | str">
  LLM response.
</ParamField>

<ParamField path="input_tokens" type="int">
  Prompt token count.
</ParamField>

<ParamField path="output_tokens" type="int">
  Completion token count.
</ParamField>

<ParamField path="latency_ms" type="int">
  Call latency in milliseconds.
</ParamField>

***

## `decimalai.log_tool_call()`

Log a tool invocation inside a trace.

```python theme={null}
decimalai.log_tool_call(
    name="search_flights",
    input={"from": "SFO", "to": "NRT"},
    output={"results": [...]},
    latency_ms=150,
)
```

***

## `@decimalai.tool`

Decorator that registers a function as a tracked tool.

```python theme={null}
@decimalai.tool
def search_flights(origin: str, destination: str) -> list:
    """Search for available flights."""
    return flight_api.search(origin, destination)

# Tool calls are auto-logged when used inside a traced function
```

***

## What's next

<CardGroup cols={2}>
  <Card title="Manifests" icon="layer-group" href="/sdk/python/manifests">
    Track which version of your agent produced each trace.
  </Card>

  <Card title="Frameworks" icon="puzzle-piece" href="/sdk/python/frameworks">
    Skip the manual calls — auto-instrument LangChain, OpenAI Agents, and more.
  </Card>
</CardGroup>