Implementation:Confident ai Deepeval Observe Decorator Tracing

Overview

Observe Decorator Tracing is the implementation of function-level tracing in DeepEval through the @observe decorator. This decorator instruments Python functions to create traced spans that capture inputs, outputs, and execution metadata, which are then posted to the Confident AI platform for observability and analysis.

API Documentation

Decorator: @observe

Source: deepeval/tracing/tracing.py:L1063-1248

Import:

from deepeval.tracing import observe

Signature:

@observe(_func=None, *, metrics=None, metric_collection=None, type=None, **observe_kwargs)

Parameters

Parameter	Type	Description
_func	Optional[Callable]	Internal parameter for bare @observe usage without parentheses.
metrics	Optional[List]	Metrics to evaluate on the span.
metric_collection	Optional[str]	Named metric collection on Confident AI to apply.
type	Literal["agent", "llm", "retriever", "tool"]	Determines span categorization. Controls which enrichment functions are available within the decorated function.

Keyword Arguments by Span Type (observe_kwargs)

The **observe_kwargs vary depending on the type parameter:

• For type="llm": model (str) -- the LLM model name
• For type="retriever": embedder (str) -- the embedding model name
• For type="tool": description (str) -- description of the tool's purpose
• For type="agent": available_tools (list), agent_handoffs (list) -- tools and agents available to the agent

Supported Function Types

The decorator supports all Python callable patterns:

• Synchronous functions -- regular def functions
• Async functions -- async def coroutines
• Generator functions -- functions using yield
• Async generator functions -- async def functions using yield

Input / Output

• Inputs: Any Python callable (function, method, coroutine, generator).
• Outputs: A decorated version of the callable that creates traced spans. Span data is posted to the Confident AI platform for dashboard visualization.

Usage Examples

Tracing an LLM Call

from deepeval.tracing import observe

@observe(type="llm", model="gpt-4o")
def call_llm(prompt: str) -> str:
    return openai_client.chat.completions.create(...)

Tracing a Retriever

from deepeval.tracing import observe

@observe(type="retriever", embedder="text-embedding-3-small")
def search_docs(query: str) -> list:
    return vector_store.similarity_search(query)

Tracing a Tool

from deepeval.tracing import observe

@observe(type="tool", description="Calculates math expressions")
def calculator(expression: str) -> float:
    return eval(expression)

Full Agent Pipeline

from deepeval.tracing import observe

@observe(type="agent", available_tools=["calculator", "search"])
def my_agent(query: str) -> str:
    docs = search_docs(query)
    result = call_llm(f"Answer based on: {docs}")
    return result

Relationships

Principle:Confident_ai_Deepeval_Function_Tracing

Metadata

DeepEval Tracing Observability LLM_Evaluation 2026-02-14 09:00 GMT