opentelemetry-based application instrumentation with automatic span generation
Wraps LLM application methods using the @instrument decorator to automatically generate structured OpenTelemetry spans (RECORD_ROOT, GENERATION, RETRIEVAL, EVAL) without modifying application logic. Uses TracerProvider to capture execution context, method inputs/outputs, and timing metadata across framework-specific wrappers (TruChain for LangChain, TruLlama for LlamaIndex, TruGraph for LangGraph, TruBasicApp for custom code). Spans are hierarchically organized to represent call chains and enable distributed tracing across microservices.
Unique: Uses framework-specific wrapper classes (TruChain, TruLlama, TruGraph) that intercept method calls at the application layer rather than bytecode instrumentation, enabling zero-modification wrapping of existing LLM chains while maintaining full OTEL compatibility and custom span type taxonomy (RECORD_ROOT, GENERATION, RETRIEVAL, EVAL)
vs alternatives: More lightweight and framework-aware than generic OTEL instrumentation libraries; avoids bytecode manipulation overhead while providing LLM-specific span semantics that generic APM tools cannot infer
llm-based feedback function evaluation with multi-provider support
Computes evaluation metrics (groundedness, relevance, coherence, toxicity) by executing structured prompts against LLM APIs through a pluggable LLMProvider interface. Supports OpenAI, Anthropic (Bedrock), Snowflake Cortex, HuggingFace, and LiteLLM as evaluation backends. Feedback functions accept span data (context, response, retrieved documents) as input and return numerical scores or boolean verdicts. Evaluation can run synchronously during application execution or asynchronously via background Evaluator thread for deferred processing.
Unique: Implements pluggable LLMProvider interface with native bindings for OpenAI, Bedrock, Cortex, HuggingFace, and LiteLLM, enabling evaluation backend switching without code changes. Feedback functions are composable, reusable classes that decouple evaluation logic from application code and support both synchronous and asynchronous (background Evaluator thread) execution modes
vs alternatives: More flexible than hardcoded evaluation metrics; supports any LLM as evaluator and enables custom metrics via Feedback class extension, while background evaluation mode prevents latency impact unlike synchronous-only alternatives
snowflake cortex server-side evaluation pipeline with event table export
Exports OTEL spans directly to Snowflake account event tables via SnowflakeEventTableDB, enabling server-side evaluation using Snowflake Cortex LLM functions. Evaluation queries run within Snowflake data warehouse without pulling data to Python, reducing latency and cost. Integrates with Snowflake's native SQL functions for groundedness, relevance, and toxicity evaluation. Supports both real-time span export and batch ingestion. Enables cost-effective evaluation at scale by leveraging Snowflake compute.
Unique: Enables server-side evaluation within Snowflake data warehouse via direct event table export and Cortex LLM functions, eliminating data movement and leveraging Snowflake compute for cost-effective evaluation at scale. Integrates OTEL span export with Snowflake's native SQL evaluation functions
vs alternatives: More cost-effective than external LLM API evaluation for high-volume applications; server-side evaluation eliminates data movement latency and enables evaluation queries to join with other warehouse data
run management system with experiment metadata tracking and comparison
RunManager tracks experiment metadata (model name, prompt version, parameters, timestamp) for each application execution. Enables comparison of runs across different configurations, prompt variations, and model selections. Stores run-level aggregations of evaluation metrics and costs. Integrates with leaderboard dashboard to display run rankings and enable filtering/sorting by metrics. Supports tagging runs for organization and retrieval.
Unique: Integrates run metadata tracking with leaderboard visualization, enabling side-by-side comparison of experiments without manual aggregation. RunManager stores run-level metrics and costs, enabling cost-quality analysis across configurations
vs alternatives: More lightweight than dedicated experiment tracking platforms; RunManager integrates directly with TruLens database and leaderboard, avoiding external service dependencies while providing LLM-specific comparison features
multi-backend persistence with database abstraction layer
Stores instrumentation spans and evaluation results via DBConnector interface with implementations for SQLite (default), PostgreSQL, MySQL, and Snowflake event tables. SQLAlchemyDB provides ORM-based persistence for relational databases with automatic schema migration and versioning. SnowflakeEventTableDB exports OTEL spans directly to Snowflake account event tables, enabling server-side evaluation pipelines and integration with Snowflake Cortex. Session class manages database lifecycle, connection pooling, and transaction semantics.
Unique: Implements dual persistence strategy: SQLAlchemyDB for relational databases with ORM abstraction, and SnowflakeEventTableDB for direct OTEL span export to Snowflake account event tables, enabling server-side evaluation pipelines without data movement. DBConnector interface allows custom implementations for proprietary data warehouses
vs alternatives: More flexible than single-database solutions; supports both relational and cloud data warehouse backends with unified API, while Snowflake integration enables server-side evaluation via Cortex without pulling traces to Python
experiment tracking and leaderboard visualization with streamlit dashboard
Provides Streamlit-based web interface (trulens_leaderboard()) for comparing LLM application performance across prompt variations, model changes, and configuration iterations. Dashboard displays evaluation metrics (groundedness, relevance, toxicity scores) as sortable leaderboards, record viewers for inspecting individual traces and span hierarchies, and feedback visualizations. Tracks experiment metadata (model name, prompt version, timestamp) and enables filtering/sorting by metric values. Integrates with TruSession to query persisted spans and evaluation results from configured database.
Unique: Integrates Streamlit dashboard directly with TruSession database queries, enabling real-time leaderboard updates without ETL. Provides framework-agnostic trace visualization that works across LangChain, LlamaIndex, and LangGraph applications via unified span schema
vs alternatives: More lightweight than dedicated experiment tracking platforms (Weights & Biases, MLflow); runs locally without external service dependencies while providing LLM-specific visualizations (span hierarchies, feedback scores) that generic dashboards cannot infer
custom instrumentation via @instrument decorator with span type taxonomy
Enables developers to annotate arbitrary Python methods with @instrument decorator to generate custom OpenTelemetry spans with LLM-specific span types (RECORD_ROOT, GENERATION, RETRIEVAL, EVAL). Decorator captures method inputs, outputs, exceptions, and execution timing. Supports nested instrumentation for hierarchical call chains. Integrates with TracerProvider to emit spans to configured database and OTEL exporters. Allows custom span attributes and tags for domain-specific metadata.
Unique: Provides LLM-specific span type taxonomy (RECORD_ROOT, GENERATION, RETRIEVAL, EVAL) via @instrument decorator, enabling semantic span classification without manual tagging. Decorator integrates with TracerProvider context to support nested instrumentation and automatic span hierarchy construction
vs alternatives: More ergonomic than manual OTEL span creation; decorator syntax reduces boilerplate while LLM-specific span types provide semantic meaning that generic OTEL instrumentation cannot infer
session-based lifecycle management with database and otel configuration
TruSession class provides centralized orchestration for database connections, OpenTelemetry setup, evaluation lifecycle, and run management. Manages DBConnector initialization, TracerProvider configuration, Evaluator thread spawning, and RunManager for tracking experiment metadata. Handles transaction semantics, connection pooling, and graceful shutdown. Enables context-based span emission and automatic span hierarchy construction. Supports both synchronous and asynchronous evaluation modes via background Evaluator thread.
Unique: Centralizes database, OTEL, and evaluation configuration in single TruSession class with support for both synchronous and asynchronous evaluation modes via background Evaluator thread. Manages RunManager for experiment metadata tracking and enables context-based span emission without manual context passing
vs alternatives: More integrated than separate OTEL and database configuration; TruSession handles lifecycle management, connection pooling, and evaluation orchestration in unified API, reducing boilerplate vs manual OTEL setup
+4 more capabilities