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

# Observability

> Langfuse integration for tracing LLM calls and tool executions

# Observability

SimpleLLMFunc integrates with [Langfuse](https://langfuse.com) for tracing LLM generations, tool calls, and agent sessions.

## Setup

### 1. Install (included with SimpleLLMFunc)

Langfuse client is bundled. No extra install needed.

### 2. Configure Environment

```bash theme={null}
# .env
LANGFUSE_PUBLIC_KEY=pk-lf-...
LANGFUSE_SECRET_KEY=sk-lf-...
LANGFUSE_BASE_URL=https://cloud.langfuse.com
LANGFUSE_ENABLED=true
LANGFUSE_EXPORT_ALL_SPANS=true
```

### 3. Use Normally

Once configured, tracing is automatic. Every decorated `@llm_function` and `@llm_chat` invocation creates:

* A **trace** for the full invocation
* **Generations** for each LLM call
* **Spans** for tool executions

## What Gets Traced

| Component            | Langfuse Entity | Contains                          |
| -------------------- | --------------- | --------------------------------- |
| `@llm_function` call | Trace           | Full invocation lifecycle         |
| `@llm_chat` call     | Trace           | Full ReAct loop                   |
| Each LLM API call    | Generation      | Messages in/out, tokens, latency  |
| Each tool execution  | Span            | Tool name, args, result, duration |
| ReAct iterations     | Span            | Iteration boundaries              |

## Trace IDs

Each invocation gets a unique `trace_id` propagated through all nested operations:

```python theme={null}
from SimpleLLMFunc.logger import get_current_trace_id

# Inside a tool or custom code
trace_id = get_current_trace_id()
```

## Custom Trace Names

The trace name defaults to the decorated function name. Override with:

```python theme={null}
@llm_function(llm_interface=llm)
async def my_func(text: str) -> str:
    """Process text."""
    pass

# The trace will be named "my_func" in Langfuse
```

## Flushing

Observations are batched and sent asynchronously. Force flush at shutdown:

```python theme={null}
from SimpleLLMFunc.observability import flush_all_observations

await flush_all_observations()
```

## Disabling

Set `LANGFUSE_ENABLED=false` or simply don't configure the keys. The framework gracefully degrades — no errors, just no traces.

## Log Levels

Control framework logging independently:

```bash theme={null}
LOG_LEVEL=WARNING   # Recommended: suppress noisy internal logs
LOG_DIR=logs        # File output location
```

Available levels: `DEBUG`, `INFO`, `WARNING`, `ERROR`, `CRITICAL`.

Use `DEBUG` only when investigating framework behavior. `WARNING` is the recommended default for production.