Overview
Streamlit dashboard tab for browsing, searching, and inspecting individual execution records, including their inputs, outputs, cost metrics, feedback results, and trace details.
Description
The Records Tab module (Records.py) provides a detailed record-level view of LLM application executions in the TruLens dashboard. It combines a searchable, filterable record grid with a comprehensive single-record detail panel.
Key capabilities:
- Text Search -- A search bar at the top allows filtering records by matching against app version, input text, or output text (case-insensitive substring matching).
- App ID Filtering -- When navigated to from the Leaderboard or Compare tabs, the page can accept pre-filtered app IDs via session state, displaying only records for those specific versions with a "Show All" button to remove the filter.
- Interactive Grid -- Records are displayed in an AgGrid table (with st.dataframe fallback) showing app version, input, output, record metadata, total tokens, total cost, eval costs (USD and/or Snowflake Credits), latency, tags, timestamps, and color-coded feedback scores. The grid supports single-row selection, pagination, and sidebar column filters.
- Record Detail Panel -- Upon selecting a record, the detail view renders:
- Input/Output Expanders -- With mojibake correction, unicode escape decoding, and Markdown-safe escaping.
- Record Metrics -- Total tokens, cost (with delta relative to app average), and latency (with delta relative to app average).
- Feedback Results -- Feedback pills for selecting a metric, plus detailed call-level information via
_render_feedback_call.
- Trace Viewer -- Conditionally renders the appropriate trace visualization: SIS-compatible JSON, OTEL span viewer, or standard record/app JSON viewer.
The module includes several text-processing utilities:
_clean_text_value -- fixes mojibake (UTF-8 displayed as latin-1) and decodes backslash-escaped unicode sequences._escape_problematic_markdown -- escapes dollar signs and intra-word underscores to prevent Streamlit's Markdown renderer from misinterpreting them as LaTeX or emphasis.
Usage
Use the Records Tab to inspect individual LLM application executions in detail. Navigate to it from the Leaderboard by clicking "Examine Records" on selected app versions, or access it directly via URL with query parameters. It is the primary tool for debugging specific records, understanding why a particular feedback score was assigned, and viewing the full execution trace.
Code Reference
Source Location
Signature
def init_page_state() -> None: ...
def _format_cost(cost: float, currency: str) -> str: ...
def _clean_text_value(value: Any) -> Any: ...
def _escape_currency_dollars(text: str) -> str: ...
def _escape_problematic_markdown(text: str) -> str: ...
def _render_record_metrics(
records_df: pd.DataFrame,
selected_row: pd.Series,
) -> None: ...
@streamlit_compat.st_fragment
def _render_trace(
selected_row: pd.Series,
records_df: pd.DataFrame,
feedback_col_names: Sequence[str],
feedback_directions: Dict[str, bool],
) -> None: ...
def _preprocess_df(
records_df: pd.DataFrame,
record_query: Optional[str] = None,
) -> pd.DataFrame: ...
def _build_grid_options(
df: pd.DataFrame,
feedback_col_names: Sequence[str],
feedback_directions: Dict[str, bool],
version_metadata_col_names: Sequence[str],
) -> dict: ...
def _render_grid(
df: pd.DataFrame,
feedback_col_names: Sequence[str],
feedback_directions: Dict[str, bool],
version_metadata_col_names: Sequence[str],
) -> pd.DataFrame: ...
def _render_grid_tab(
df: pd.DataFrame,
feedback_col_names: List[str],
feedback_directions: Dict[str, bool],
version_metadata_col_names: List[str],
) -> None: ...
def _reset_app_ids() -> None: ...
def _render_app_id_args_filter(
versions_df: pd.DataFrame,
) -> pd.DataFrame: ...
def _handle_record_query_change() -> None: ...
def render_records(app_name: str) -> None: ...
def records_main() -> None: ...
Import
from trulens.dashboard.tabs.Records import render_records
from trulens.dashboard.tabs.Records import records_main
from trulens.dashboard.tabs.Records import init_page_state
I/O Contract
Inputs
init_page_state
| Name |
Type |
Required |
Description
|
| (none) |
-- |
-- |
Reads page_name.app_ids from query parameters and session state. Synchronizes app IDs to query params if present in session state but not in URL.
|
_format_cost
| Name |
Type |
Required |
Description
|
| cost |
float |
yes |
The numeric cost value to format.
|
| currency |
str |
yes |
The currency label (e.g. "USD" or "Snowflake credits"). USD values are prefixed with "$".
|
_clean_text_value
| Name |
Type |
Required |
Description
|
| value |
Any |
yes |
A value to clean. Non-string values are returned unchanged. Strings are checked for mojibake markers and escaped unicode sequences.
|
_escape_problematic_markdown
| Name |
Type |
Required |
Description
|
| text |
str |
yes |
Text to escape. Dollar signs are backslash-escaped and underscores between word characters are escaped to prevent Markdown interpretation.
|
_render_record_metrics
| Name |
Type |
Required |
Description
|
| records_df |
pd.DataFrame |
yes |
Full records DataFrame, used to compute per-app averages for delta calculations.
|
| selected_row |
pd.Series |
yes |
The specific record row whose metrics should be displayed.
|
_render_trace
| Name |
Type |
Required |
Description
|
| selected_row |
pd.Series |
yes |
The record row to render trace details for.
|
| records_df |
pd.DataFrame |
yes |
Full records DataFrame (passed to _render_record_metrics).
|
| feedback_col_names |
Sequence[str] |
yes |
Feedback column names to show in the feedback results section.
|
| feedback_directions |
Dict[str, bool] |
yes |
Mapping of feedback names to their direction (True = higher is better).
|
_preprocess_df
| Name |
Type |
Required |
Description
|
| records_df |
pd.DataFrame |
yes |
Raw records DataFrame with columns including ts, input, output, app_id, app_name, record_id, app_version.
|
| record_query |
Optional[str] |
no |
Optional search string to filter records by app_version, input, or output content.
|
render_records
| Name |
Type |
Required |
Description
|
| app_name |
str |
yes |
The name of the application whose records should be displayed.
|
Outputs
_format_cost
| Name |
Type |
Description
|
| formatted |
str |
Formatted cost string (e.g. "$0.05" for USD or "0.00123 Snowflake credits").
|
_clean_text_value
| Name |
Type |
Description
|
| cleaned |
Any |
The cleaned text value with mojibake fixed and escape sequences decoded, or the original non-string value unchanged.
|
_preprocess_df
| Name |
Type |
Description
|
| records_df |
pd.DataFrame |
Preprocessed DataFrame with hidden records removed, sorted by timestamp descending, columns reordered (app_version, record_id, app_name, app_id first), text values cleaned, and optionally filtered by search query.
|
_render_grid
| Name |
Type |
Description
|
| selected_rows |
pd.DataFrame |
DataFrame of user-selected rows from the grid (may be empty).
|
render_records
| Name |
Type |
Description
|
| (none -- renders to Streamlit) |
None |
Renders the full records page including search, grid, and detail panel.
|
Usage Examples
# Example 1: Running the records tab as a standalone Streamlit page
# (typically invoked as: streamlit run tabs/Records.py)
from trulens.dashboard.tabs.Records import records_main
if __name__ == "__main__":
records_main()
# Example 2: Navigating to the Records tab from the Leaderboard with pre-filtered app IDs
import streamlit as st
from trulens.dashboard.constants import RECORDS_PAGE_NAME
selected_app_ids = ["app_id_abc123"]
st.session_state[f"{RECORDS_PAGE_NAME}.app_ids"] = selected_app_ids
st.switch_page("tabs/Records.py")
# Example 3: Using the text cleaning utilities programmatically
from trulens.dashboard.tabs.Records import _clean_text_value, _escape_problematic_markdown
# Fix mojibake in a string
raw = "The userâ\x80\x99s query"
cleaned = _clean_text_value(raw) # Returns: "The user's query"
# Escape Markdown-problematic characters
text = "variable_name costs $5.00"
safe = _escape_problematic_markdown(text)
# Returns: "variable\_name costs \$5.00"
# Example 4: Using _format_cost for display
from trulens.dashboard.tabs.Records import _format_cost
print(_format_cost(0.0523, "USD")) # "$0.05"
print(_format_cost(0.00123, "Snowflake credits")) # "0.00123 Snowflake credits"
Related Pages
