Implementation:Truera Trulens Selector Init

Knowledge Sources	TruLens TruLens Docs
Domains	Observability, Data_Extraction
Last Updated	2026-02-14 08:00 GMT

Overview

Concrete tool for targeting and extracting specific data from OpenTelemetry spans for use in feedback evaluation provided by the trulens-core library.

Description

The Selector class is a dataclass that describes how to select spans from a trace and what data to extract from them. It supports filtering spans by type (RETRIEVAL, GENERATION, TOOL, etc.), function name, or span name, then extracting specific attributes. The Selector works with the Feedback/Metric system to provide precise data routing from traces to evaluation functions.

Convenience static methods (select_record_input, select_record_output, select_context) provide pre-configured selectors for common use cases.

Usage

Import and use Selector when defining feedback functions for custom instrumented applications. Use the convenience methods for standard use cases (input/output/context). Use the full constructor when targeting specific span types or custom attributes in complex applications.

Code Reference

Source Location

• Repository: trulens
• File: src/core/trulens/core/feedback/selector.py
• Lines: L467-692

Signature

@dataclass
class Selector:
    def __init__(
        self,
        trace_level: bool = False,
        function_name: Optional[str] = None,
        span_name: Optional[str] = None,
        span_type: Optional[str] = None,
        span_attributes_processor: Optional[Callable[[Dict[str, Any]], Any]] = None,
        span_attribute: Optional[str] = None,
        function_attribute: Optional[str] = None,
        ignore_none_values: bool = False,
        collect_list: bool = True,
        match_only_if_no_ancestor_matched: bool = False,
    ):
        """
        Args:
            trace_level: If True, matches all spans (not just one).
            function_name: Filter by function name.
            span_name: Filter by span name.
            span_type: Filter by span type (e.g., "retrieval", "generation").
            span_attributes_processor: Custom callable to process span attributes.
            span_attribute: Specific span attribute key to extract.
            function_attribute: Function argument or "return" to extract.
            ignore_none_values: Skip evaluation when extracted value is None.
            collect_list: If True, pass entire list to feedback; if False, evaluate each.
            match_only_if_no_ancestor_matched: Only match first call in recursive chains.
        """

    # Convenience methods:
    @staticmethod
    def select_record_input(ignore_none_values: bool = True) -> Selector: ...
    @staticmethod
    def select_record_output(ignore_none_values: bool = True) -> Selector: ...
    @staticmethod
    def select_context(*, collect_list: bool, ignore_none_values: bool = True) -> Selector: ...

Import

from trulens.core.feedback.selector import Selector

I/O Contract

Inputs

Name	Type	Required	Description
trace_level	bool	No	Match all spans vs single span (default: False)
span_type	str	No	Filter by span type (e.g., SpanAttributes.SpanType.RETRIEVAL)
function_name	str	No	Filter by function name
span_attribute	str	No	Specific attribute key to extract from span
function_attribute	str	No	Function arg name or "return" to extract
collect_list	bool	No	Pass list vs evaluate individually (default: True)

Outputs

Name	Type	Description
return	Selector	Configured selector for use with Feedback.on() bindings

Usage Examples

Using Convenience Methods

from trulens.core.feedback.selector import Selector

# Get record input (from RECORD_ROOT span)
input_selector = Selector.select_record_input()

# Get record output
output_selector = Selector.select_record_output()

# Get retrieved contexts (from RETRIEVAL spans)
context_selector = Selector.select_context(collect_list=True)

Custom Selector for Instrumented Methods

from trulens.core.feedback.selector import Selector
from trulens.core import Feedback

# Target a specific function's return value in RETRIEVAL spans
f_context_relevance = Feedback(provider.context_relevance).on(**{
    "question": Selector.select_record_input(),
    "context": Selector(
        span_type="retrieval",
        function_name="retrieve",
        function_attribute="return",
        collect_list=False,  # Evaluate each context separately
    ),
})

Trace-Level Selector for Agent Evaluation

from trulens.core.feedback.selector import Selector

# Pass entire trace to evaluation function
f_tool_selection = Feedback(
    provider.tool_selection_with_cot_reasons
).on(**{
    "trace": Selector(trace_level=True),
})

Related Pages

Implements Principle

• Principle:Truera_Trulens_Selector_Based_Data_Extraction

Requires Environment

• Environment:Truera_Trulens_Python_Core_Environment