Principle:Truera Trulens Method Instrumentation
| Knowledge Sources | |
|---|---|
| Domains | Observability, Tracing |
| Last Updated | 2026-02-14 08:00 GMT |
Overview
A decorator-based instrumentation pattern that attaches OpenTelemetry tracing to individual methods, creating typed spans with configurable attributes.
Description
Method Instrumentation provides a Python decorator (@instrument) that wraps functions and methods to automatically create OpenTelemetry spans when they are invoked within a recording context. Each span captures:
- Span type: Categorizes the operation (RETRIEVAL, GENERATION, TOOL, AGENT, UNKNOWN)
- Function metadata: Module, class, function name, arguments, and return value
- Custom attributes: User-defined key-value pairs for domain-specific data
This is the primary mechanism for instrumenting custom Python applications (as opposed to framework-specific wrappers like TruChain). The decorator supports synchronous functions, async coroutines, sync generators, and async generators.
The instrumentation is opt-in and recording-aware — decorated methods only create spans when called within a recording context (i.e., inside a with tru_app as recording block). Outside recording contexts, the decorator is a no-op.
Usage
Use this principle when building custom Python applications that you want to evaluate with TruLens. Apply @instrument to methods that represent meaningful steps in your application pipeline (retrieval, generation, tool use). Combine with TruApp wrapper for recording.
Theoretical Basis
Method Instrumentation implements the Aspect-Oriented Programming (AOP) paradigm — cross-cutting concerns (tracing) are applied declaratively via decorators without modifying the core business logic.
Pseudo-code Logic:
# Abstract instrumentation pattern
@instrument(span_type=SpanType.RETRIEVAL)
def retrieve(self, query: str) -> List[str]:
# Original logic unchanged
return self.vector_store.query(query)
# When called within recording context:
# 1. Create OTEL span with type=RETRIEVAL
# 2. Record function name, args (query), return value
# 3. Attach custom attributes
# 4. Close span on function exit
The typed span system follows Semantic Conventions from OpenTelemetry, extended with TruLens-specific span types for LLM evaluation workflows.