Implementation:Truera Trulens Dashboard Utils

Knowledge Sources	Truera_Trulens TruLens Docs
Domains	Dashboard, Visualization
Last Updated	2026-02-14 08:00 GMT

Overview

Core utility module for the TruLens Streamlit dashboard, providing session management, data retrieval, sidebar rendering, filtering, and OTel span conversion.

Description

The dashboard_utils module is the backbone of the TruLens dashboard infrastructure. It provides cached data retrieval, session initialization, UI rendering helpers, and conversion logic for both legacy and OTel-based tracing formats. Key components include:

Session Management:

get_session() -- A @st.cache_resource-decorated function that parses extensive command-line arguments (database URL, Snowflake connection parameters, SiS compatibility flags, OTel tracing toggle) and returns a singleton TruSession. Supports both standard database and Snowflake connector backends.
is_sis_compatibility_enabled() -- Checks whether the Streamlit-in-Snowflake compatibility mode is active, which disables certain custom components like the trace viewer.
read_spcs_oauth_token() -- Reads the OAuth token from /snowflake/session/token for SPCS (Snowpark Container Services) deployments.

Data Retrieval (all Streamlit-cached with TTL):

get_records_and_feedback(app_ids, app_name, app_versions, run_name, offset, limit) -- Fetches records and feedback columns from the database, flattens record metadata, handles the HIDE_RECORD_COL_NAME boolean conversion, and replaces NaN values with None.
get_apps(app_name) -- Returns a list of all registered apps, optionally filtered by app name.
get_feedback_defs() -- Retrieves feedback definitions and computes a feedback_directions dictionary mapping feedback names to their higher_is_better boolean.
get_app_versions(app_name) -- Fetches app version data, flattens metadata, and handles boolean column conversions for PINNED and EXTERNAL_APP columns.

Page Configuration and Sidebar:

set_page_config(page_title) -- Configures the Streamlit page with the TruLens favicon, wide layout, and logo (unless SiS compatibility is enabled).
render_sidebar() -- Renders the sidebar with an app selector dropdown, a refresh button, version info, and a bug report link. Returns the selected app_name.
render_refresh_button() -- Adds a refresh button to the sidebar that clears all caches, query params, and session state.
render_app_version_filters(app_name, ...) -- Renders a search bar, advanced filters popover (tags and metadata multiselect), and a reset filters button. Returns a filtered DataFrame of app versions.

Query Parameter Management:

add_query_param(param_name, param_value) -- Adds a query parameter to the Streamlit URL.
read_query_params_into_session_state(page_name, transforms) -- One-time initialization that loads URL query parameters into Streamlit session state, handling prefixed page names and multiselect deserialization.

OTel Span Conversion:

_map_event_to_otel_span(row) -- Converts a single database Event row into an OtelSpan typed dictionary with SpanRecord and SpanTrace sub-structures.
_convert_events_to_otel_spans(events_df) -- Batch converts a DataFrame of Event rows into a list of OtelSpan objects.
_get_event_otel_spans(record_id, app_name) -- Cached function that fetches events for a record ID and returns the converted OTel spans.

Cross-Format Record Checking:

_check_cross_format_records(app_name, app_versions) -- Queries both OTEL (Event table) and non-OTEL (Record table) to get record counts, used to provide helpful error messages when records exist in a different format than the current mode.
_show_no_records_error(app_name, app_versions) -- Displays context-aware error messages suggesting the user switch between OTel and non-OTel modes.

Usage

This module is used internally by all TruLens dashboard pages. It should be imported by any custom Streamlit page that needs to access TruLens session data, render the standard sidebar, or retrieve records and feedback information.

Code Reference

Source Location

Repository: Truera_Trulens
File: src/dashboard/trulens/dashboard/utils/dashboard_utils.py
Lines: 1-803

Signature

def set_page_config(page_title: Optional[str] = None): ...


def add_query_param(param_name: str, param_value: str): ...


def read_query_params_into_session_state(
    page_name: str,
    transforms: Optional[Dict[str, Callable[[str], Any]]] = None,
): ...


def is_sis_compatibility_enabled() -> bool: ...


def read_spcs_oauth_token() -> Optional[str]: ...


@st.cache_resource(show_spinner="Setting up TruLens session")
def get_session() -> core_session.TruSession: ...


@st.cache_data(ttl=dashboard_constants.CACHE_TTL, show_spinner="Getting record data")
def get_records_and_feedback(
    app_ids: Optional[List[str]] = None,
    app_name: Optional[str] = None,
    app_versions: Optional[List[str]] = None,
    run_name: Optional[str] = None,
    offset: Optional[int] = None,
    limit: Optional[int] = None,
): ...


@st.cache_data(ttl=dashboard_constants.CACHE_TTL, show_spinner="Getting app data")
def get_apps(app_name: Optional[str] = None): ...


@st.cache_data(ttl=dashboard_constants.CACHE_TTL, show_spinner="Getting feedback definitions")
def get_feedback_defs(): ...


def update_app_metadata(app_id: str, metadata: dict): ...


def render_refresh_button(): ...


def render_sidebar() -> Optional[str]: ...


@st.cache_data(ttl=dashboard_constants.CACHE_TTL, show_spinner="Getting app versions")
def get_app_versions(app_name: str): ...


def render_app_version_filters(
    app_name: str,
    other_query_params_kv: Optional[Dict[str, str]] = None,
    page_name_keys: Optional[List[str]] = None,
): ...


@st.cache_data(ttl=dashboard_constants.CACHE_TTL, show_spinner="Getting events for record")
def _get_event_otel_spans(
    record_id: str, app_name: Optional[str] = None,
) -> List[OtelSpan]: ...


def _show_no_records_error(
    app_name: Optional[str] = None,
    app_versions: Optional[List[str]] = None,
) -> None: ...

Import

from trulens.dashboard.utils.dashboard_utils import set_page_config
from trulens.dashboard.utils.dashboard_utils import get_session
from trulens.dashboard.utils.dashboard_utils import get_records_and_feedback
from trulens.dashboard.utils.dashboard_utils import get_apps
from trulens.dashboard.utils.dashboard_utils import get_feedback_defs
from trulens.dashboard.utils.dashboard_utils import render_sidebar
from trulens.dashboard.utils.dashboard_utils import render_app_version_filters
from trulens.dashboard.utils.dashboard_utils import is_sis_compatibility_enabled
from trulens.dashboard.utils.dashboard_utils import _get_event_otel_spans

I/O Contract

Inputs

set_page_config:

Name	Type	Required	Description
page_title	Optional[str]	no	Page title suffix. Rendered as "TruLens: {page_title}" or just "TruLens" if `None`.

get_records_and_feedback:

Name	Type	Required	Description
app_ids	Optional[List[str]]	no	List of app IDs to filter by.
app_name	Optional[str]	no	App name to filter by.
app_versions	Optional[List[str]]	no	List of app versions to filter by.
run_name	Optional[str]	no	Run name to filter by.
offset	Optional[int]	no	Pagination offset for records.
limit	Optional[int]	no	Maximum number of records to return.

render_app_version_filters:

Name	Type	Required	Description
app_name	str	yes	The app name to load versions for.
other_query_params_kv	Optional[Dict[str, str]]	no	Additional query parameter key-value pairs for tracking active filters.
page_name_keys	Optional[List[str]]	no	Keys that are page-name-prefixed in session state.

read_query_params_into_session_state:

Name	Type	Required	Description
page_name	str	yes	Name of the page for prefixing session state keys.
transforms	Optional[Dict[str, Callable]]	no	Optional mapping of param names to deserialization functions.

_get_event_otel_spans:

Name	Type	Required	Description
record_id	str	yes	The record ID to fetch OTel event spans for.
app_name	Optional[str]	no	Optional app name filter.

Outputs

Name	Type	Description
get_session return	TruSession	The singleton TruLens session instance.
get_records_and_feedback return	Tuple[pd.DataFrame, List[str]]	A tuple of (records DataFrame, list of feedback column names).
get_apps return	List[dict]	List of app definition dictionaries.
get_feedback_defs return	Tuple[pd.DataFrame, Dict[str, bool]]	A tuple of (feedback definitions DataFrame, feedback directions dictionary).
get_app_versions return	Tuple[pd.DataFrame, List[str]]	A tuple of (app versions DataFrame, list of metadata column names).
render_sidebar return	Optional[str]	The selected app name, or `None` if no apps exist.
render_app_version_filters return	Tuple[pd.DataFrame, List[str]]	A tuple of (filtered app versions DataFrame, metadata column names).
_get_event_otel_spans return	List[OtelSpan]	List of OTel span dictionaries for the given record.
is_sis_compatibility_enabled return	bool	`True` if SiS compatibility is enabled.

Usage Examples

from trulens.dashboard.utils.dashboard_utils import set_page_config
from trulens.dashboard.utils.dashboard_utils import render_sidebar
from trulens.dashboard.utils.dashboard_utils import get_records_and_feedback

# Standard page setup pattern used by all built-in dashboard pages
set_page_config(page_title="Records")
app_name = render_sidebar()

if app_name:
    records_df, feedback_col_names = get_records_and_feedback(app_name=app_name)
    st.dataframe(records_df)

from trulens.dashboard.utils.dashboard_utils import render_app_version_filters

# Render version filters with search and advanced filtering
filtered_versions, metadata_cols = render_app_version_filters(
    app_name="my_rag_app",
    other_query_params_kv={"records.record_id": selected_record_id},
)
st.write(f"Found {len(filtered_versions)} matching versions")

from trulens.dashboard.utils.dashboard_utils import get_feedback_defs

# Get feedback definitions and directions
feedback_defs_df, feedback_directions = get_feedback_defs()
for name, higher_is_better in feedback_directions.items():
    direction = "higher is better" if higher_is_better else "lower is better"
    st.write(f"{name}: {direction}")

Related Pages

Page Connections

Double-click a node to navigate. Hold to expand connections.

Principle

Implementation

Heuristic

Environment