Implementation:Truera Trulens Otel Span Constants

Knowledge Sources	Truera_Trulens
Domains	Dashboard, Observability, OpenTelemetry
Last Updated	2026-02-14 08:00 GMT

Overview

span.ts defines the core OTEL span type enumeration and span attribute key constants used throughout the TruLens OTEL record viewer to classify, filter, and extract data from OpenTelemetry spans.

Description

This constants module is the canonical TypeScript source of truth for all AI Observability span types and attribute keys used in the TruLens dashboard frontend. It is designed to stay in sync with the Python-side semantic conventions defined in trulens.otel.semconv.trace.

The module exports three primary constructs:

1. BASE_SCOPE -- The string 'ai.observability', which serves as the namespace prefix for all TruLens-specific OTEL attributes.
2. SpanType -- A frozen object literal (used as a const enum alternative) that enumerates all recognized span types: UNKNOWN, CUSTOM, RECORDING, SEMANTIC, RECORD_ROOT, EVAL_ROOT, EVAL, RECORD, RETRIEVAL, RERANKING, GENERATION, MEMORIZATION, EMBEDDING, TOOL_INVOCATION, and AGENT_INVOCATION.
3. SpanAttributes -- A frozen object literal containing the fully-qualified OTEL attribute key strings, organized into logical groups:
   • Common attributes -- SPAN_TYPE, RECORD_ID, APP_NAME, APP_VERSION, ROOT_SPAN_ID, INPUT_ID, DOMAIN, RUN_NAME.
   • Cost attributes -- Token counts, model name, currency, and cost values.
   • Function call attributes -- Call ID, stack, signature, function name, class, arguments, return value, and error.
   • Recording attributes -- App ID for the recording span type.
   • Record root attributes -- Ground truth output, input, output, and error.
   • Eval root attributes -- Target trace/span IDs, feedback definition ID, metric name, status, total cost, error, score, and metadata.
   • Eval attributes -- Target record ID, eval root ID, metric name, args, criteria, explanation, and score.
   • Retrieval attributes -- Query text, query embedding, distance type, number of contexts, retrieved contexts, scores, and embeddings.
   • Reranking attributes -- Query text, model name, top N, input/output context texts, scores, and output ranks.
   • Generation attributes -- Model name, model type, input/output token counts, input/output messages, temperature, and cost.
   • Memorization attributes -- Memory type and remembered content.
   • Embedding attributes -- Input text, model name, and embedding vector.
   • Tool invocation attributes -- Description.
   • Agent invocation attributes -- Description.

All attribute keys are dynamically constructed by concatenating the BASE_SCOPE prefix with the relevant span type and field name, ensuring consistency with the backend conventions.

Usage

Import and use these constants whenever you need to read, filter, or classify OTEL span data in the frontend. For example, use SpanAttributes.SPAN_TYPE to look up the span type from an attribute dictionary, or compare against SpanType.RECORD_ROOT to identify the root span. Code consuming these constants should handle unknown attributes gracefully to maintain backwards and forwards compatibility.

Code Reference

Source Location

• Repository: Truera_Trulens
• File: src/dashboard/react_components/record_viewer_otel/src/constants/span.ts
• Lines: 1-142

Signature

export const BASE_SCOPE = 'ai.observability';

export const SpanType = {
  UNKNOWN: 'unknown',
  CUSTOM: 'custom',
  RECORDING: 'recording',
  SEMANTIC: 'semantic',
  RECORD_ROOT: 'record_root',
  EVAL_ROOT: 'eval_root',
  EVAL: 'eval',
  RECORD: 'record',
  RETRIEVAL: 'retrieval',
  RERANKING: 'reranking',
  GENERATION: 'generation',
  MEMORIZATION: 'memorization',
  EMBEDDING: 'embedding',
  TOOL_INVOCATION: 'tool_invocation',
  AGENT_INVOCATION: 'agent_invocation',
} as const;

export type TruLensSpanType = (typeof SpanType)[keyof typeof SpanType];

export const SpanAttributes = {
  SPAN_TYPE: `${BASE_SCOPE}.span_type`,
  RECORD_ID: `${BASE_SCOPE}.record_id`,
  APP_NAME: `${BASE_SCOPE}.app_name`,
  // ... (142 lines of fully-qualified attribute keys)
} as const;

Import

import { BASE_SCOPE, SpanType, TruLensSpanType, SpanAttributes } from '@/constants/span';

I/O Contract

Inputs

Name	Type	Required	Description
N/A	N/A	N/A	This module exports only constants and a type alias. It takes no runtime inputs.

Outputs

Name	Type	Description
BASE_SCOPE	string	The base attribute namespace: 'ai.observability'.
SpanType	Readonly object literal	Maps human-readable span type names (e.g., RECORD_ROOT) to their string values (e.g., 'record_root').
TruLensSpanType	type alias	A union type of all valid span type string literal values, derived from SpanType.
SpanAttributes	Readonly object literal	Maps human-readable attribute names (e.g., SPAN_TYPE) to their fully-qualified OTEL attribute key strings (e.g., 'ai.observability.span_type').

Span Type Reference

Constant	Value	Description
UNKNOWN	'unknown'	Span type could not be determined.
CUSTOM	'custom'	User-defined custom span.
RECORDING	'recording'	Represents an active recording session.
SEMANTIC	'semantic'	A semantic-level operation span.
RECORD_ROOT	'record_root'	The root span of a record trace; exactly one per record.
EVAL_ROOT	'eval_root'	The root span of an evaluation trace.
EVAL	'eval'	An individual evaluation span.
RECORD	'record'	A record-level span.
RETRIEVAL	'retrieval'	A retrieval operation (e.g., vector DB query).
RERANKING	'reranking'	A reranking operation on retrieved contexts.
GENERATION	'generation'	An LLM generation/inference call.
MEMORIZATION	'memorization'	A memory read/write operation.
EMBEDDING	'embedding'	An embedding computation.
TOOL_INVOCATION	'tool_invocation'	An external tool call.
AGENT_INVOCATION	'agent_invocation'	An agent invocation step.

Usage Examples

import { SpanType, SpanAttributes } from '@/constants/span';

// Determine the type of a span from its attributes
const spanType = span.record_attributes?.[SpanAttributes.SPAN_TYPE];

// Check if the span is the root of a record
if (spanType === SpanType.RECORD_ROOT) {
  console.log('Found the root span');
}

// Filter out evaluation spans from a list
const nonEvalSpans = spans.filter((span) => {
  const type = span.record_attributes?.[SpanAttributes.SPAN_TYPE];
  return type !== SpanType.EVAL && type !== SpanType.EVAL_ROOT;
});

// Access a generation-specific attribute
const modelName = span.record_attributes?.[SpanAttributes.GENERATION_MODEL_NAME];

Related Pages

• Environment:Truera_Trulens_Streamlit_Dashboard_Environment
• Truera_Trulens_Otel_StackTreeNode -- Span tree nodes whose attributes are keyed by these constants.
• Truera_Trulens_Otel_CreateTreeFromCalls -- Tree-building algorithm that uses SpanType and SpanAttributes to filter and classify spans.
• Truera_Trulens_Otel_RecordInfo_Component -- The top-level component that renders views based on span type classifications.