Observability

Langfuse integration for tracing LLM calls and tool executions

Observability

SimpleLLMFunc integrates with Langfuse 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

# .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:

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:

@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:

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:

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.