Implementation:Confident ai Deepeval Update Current Span

Metadata

Knowledge Sources	DeepEval
Domains	LLM_Evaluation Observability Tracing
Last Updated	2026-02-14 09:00 GMT

Overview

The update_current_span function enriches the currently active traced span with evaluation data at runtime. It allows application code to attach test case fields -- such as retrieval context, expected output, tools called, and metadata -- to the span that is currently executing, enabling per-component metric evaluation within a traced pipeline.

Description

When a function decorated with @observe is executing, it has an active span in the tracing context. The update_current_span function provides a mechanism to enrich that span with additional data fields that are required by evaluation metrics but are not directly available from the function's input/output signature.

Key behaviors:

• Context-local resolution -- The function automatically resolves the current span from the tracing context (via contextvars). No explicit span reference is required.
• Selective field update -- Only the fields that are explicitly passed are updated. Fields left as None are not modified, preserving any previously set values.
• Test case composition -- A complete LLMTestCase object can be passed via the test_case parameter, which sets all test case fields at once. Individual field parameters (input, output, etc.) can also be used for partial updates.
• Retrieval context attachment -- The retrieval_context parameter is particularly important for RAG pipelines, where the retrieved documents must be attached to the retriever span for faithfulness and contextual metrics.

Usage

Call update_current_span from within any @observe-decorated function to attach evaluation data:

from deepeval.tracing import update_current_span

Typically called after the component has produced its result but before the function returns, so that the span captures both the output and the supplementary evaluation data.

Code Reference

Source Location

• Repository: confident-ai/deepeval
• File: deepeval/tracing/context.py (lines 18--60)

Signature

def update_current_span(
    input=None,
    output=None,
    retrieval_context=None,
    context=None,
    expected_output=None,
    tools_called=None,
    expected_tools=None,
    metadata=None,
    name=None,
    test_case=None,
):
    ...

Import

from deepeval.tracing import update_current_span

I/O Contract

Inputs

Input Contract

Name	Type	Description
input	Optional[str]	Override the auto-captured input for this span's test case.
output	Optional[str]	Override the auto-captured output for this span's test case.
retrieval_context	Optional[List[str]]	List of retrieved document texts. Essential for faithfulness and contextual metrics on retriever spans.
context	Optional[List[str]]	Ground truth context for the evaluation (distinct from retrieval_context).
expected_output	Optional[str]	The expected (ground truth) output for correctness evaluation.
tools_called	Optional[List[str]]	List of tools that were actually called during this span's execution.
expected_tools	Optional[List[str]]	List of tools that should have been called, for tool correctness metrics.
metadata	Optional[Dict]	Arbitrary key-value metadata to attach to the span.
name	Optional[str]	Override the span name.
test_case	Optional[LLMTestCase]	A complete test case object that sets all fields at once. When provided, individual field parameters may still override specific fields.

Outputs

Output Contract

Name	Type	Description
Enriched span	None (side effect)	The currently active span is mutated in-place with the provided evaluation data. The function returns None.

Usage Examples

Example 1: Attaching Retrieval Context to a Retriever Span

Enriching a retriever span with the retrieved document texts so that contextual metrics can evaluate retrieval quality.

from deepeval.tracing import observe, update_current_span

@observe(type="retriever")
def retrieve(query):
    docs = vector_store.search(query)
    update_current_span(retrieval_context=[d.text for d in docs])
    return docs

• The retrieval_context field is attached to the current retriever span.
• Metrics such as contextual precision and contextual recall can now evaluate this span using the attached retrieval context.

Example 2: Providing Expected Output for Correctness

Attaching a ground truth answer so that correctness metrics can score the generator's output.

from deepeval.tracing import observe, update_current_span

@observe(type="llm")
def generate(query: str, context: list, expected: str) -> str:
    response = llm.invoke(query, context=context)
    update_current_span(
        expected_output=expected,
        retrieval_context=[c.text for c in context]
    )
    return response

• Both expected_output and retrieval_context are attached in a single call.
• The auto-captured input and output remain as the function's arguments and return value, respectively.

Example 3: Using a Complete Test Case Object

Passing a full LLMTestCase to set all evaluation fields at once.

from deepeval.tracing import observe, update_current_span
from deepeval.test_case import LLMTestCase

@observe(type="llm")
def generate(query: str) -> str:
    response = llm.invoke(query)
    update_current_span(
        test_case=LLMTestCase(
            input=query,
            actual_output=response,
            expected_output="The expected answer",
            retrieval_context=["Relevant document text"]
        )
    )
    return response

• The test_case parameter sets all test case fields from a single LLMTestCase object.

Related Pages

• Principle:Confident_ai_Deepeval_Span_Level_Test_Cases