Implementation:Truera Trulens TruSession Init

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

Overview

Concrete tool for establishing a centralized observability session provided by the trulens-core library.

Description

The TruSession class is the main entry point to TruLens. It is a Pydantic singleton that manages database connections, evaluator orchestration, and OpenTelemetry tracing configuration. Once initialized, all subsequent TruLens operations (wrapping apps, running feedback, viewing dashboards) use this session instance. The singleton pattern ensures consistent state across the application lifecycle.

Usage

Import and instantiate TruSession at the very beginning of any TruLens evaluation pipeline. The session must be initialized before creating any app wrappers (TruChain, TruApp, TruGraph) or running feedback functions. For local development, use the default configuration (SQLite). For production, pass a SnowflakeConnector or other DBConnector.

Code Reference

Source Location

• Repository: trulens
• File: src/core/trulens/core/session.py
• Lines: L66-293

Signature

class TruSession(core_experimental._WithExperimentalSettings, python_utils.PydanticSingleton):
    def __init__(
        self,
        connector: Optional[core_connector.DBConnector] = None,
        experimental_feature_flags: Optional[
            Union[
                Mapping[core_experimental.Feature, bool],
                List[core_experimental.Feature],
            ]
        ] = None,
        _experimental_otel_exporter: Optional[SpanExporter] = None,
        **kwargs,
    ):
        """
        Args:
            connector: Database connector to use. If not provided, a default
                DefaultDBConnector is created (SQLite-backed).
            experimental_feature_flags: Experimental feature flags for
                enabling/disabling features like OTEL tracing.
            _experimental_otel_exporter: Optional OTEL SpanExporter for
                custom span export (requires OTEL_TRACING feature flag).
            **kwargs: Arguments forwarded to DefaultDBConnector if no
                connector is provided.
        """

Import

from trulens.core.session import TruSession

I/O Contract

Inputs

Name	Type	Required	Description
connector	DBConnector	No	Database connector (defaults to SQLite via DefaultDBConnector)
experimental_feature_flags	Union[Mapping, List]	No	Feature flags for experimental settings (e.g., OTEL_TRACING)
**kwargs	dict	No	Forwarded to DefaultDBConnector (e.g., database_url, database_prefix)

Outputs

Name	Type	Description
return	TruSession	Singleton session instance managing database, evaluators, and OTEL tracing

Usage Examples

Basic Local Session

from trulens.core.session import TruSession

# Default: SQLite database in current directory
session = TruSession()

Session with Custom Database URL

from trulens.core.session import TruSession

# Use a specific database URL
session = TruSession(database_url="sqlite:///my_evals.db")

Session with Snowflake Connector

from trulens.core.session import TruSession
from trulens.connectors.snowflake import SnowflakeConnector

connector = SnowflakeConnector(
    account="my_account",
    user="my_user",
    password="my_password",
    database="MY_DB",
    schema="MY_SCHEMA",
    warehouse="MY_WH",
)
session = TruSession(connector=connector)

Related Pages

Implements Principle

• Principle:Truera_Trulens_Session_Initialization

Requires Environment

• Environment:Truera_Trulens_Python_Core_Environment