Data model

​

Overview

Respan’s observability is built around one core concept: different views of the same underlying data. Every LLM interaction is stored as a log — a single record containing the input, output, model, metrics, and metadata. All views present the same log data, just organized differently for different use cases:

​

How Respan stores your data

When you send an LLM request through Respan — whether via the LLM Gateway, the logging API, or a tracing SDK — Respan creates a log record. Every log uses a universal input / output design. The system automatically:

• Serializes your data regardless of format (messages array, text string, embeddings vector, audio metadata)
• Extracts type-specific fields (tool calls, thinking blocks, etc.)
• Calculates metrics when possible (cost, token counts, latency)
• Associates the log with traces, threads, and customers based on the identifiers you provide

​

What’s in a log

A log captures everything about a single LLM interaction: For the complete field reference, see Log fields & parameters. For per-type input/output formats, see Log types.

​

Logs

Every log has a log_type that determines its input/output format. The most common is chat (messages in, assistant message out), but Respan also supports embedding, speech, transcription, workflow, agent, and more. See Log types for the full list.

​

Traces

Traces group related logs using spans to show the execution flow of multi-step processes. Each span corresponds to a log entry but adds hierarchical context.

​

Trace structure

​

Key trace fields

• trace_unique_id: Groups all spans in the same workflow
• span_unique_id: Individual span identifier (maps to log ID)
• span_parent_id: Creates the hierarchical structure
• span_name: Descriptive name for the operation
• span_workflow_name: The nearest workflow this span belongs to

​

Multi-trace grouping

Complex workflows can span multiple traces using trace_group_identifier:

​

Threads

​

Thread structure

• Thread ID: Unique identifier for the conversation
• Messages: Ordered sequence of user and assistant messages (each message maps to log entries)

​

Scores

Scores are evaluation results that are attached to specific logs. Each score represents a quality assessment or performance metric for a particular LLM request.

​

Score structure

Scores are linked to logs through the log_id field and can be created by two types of evaluators:

• Platform evaluators: Use evaluator_id (UUID from Respan platform)
• Custom evaluators: Use evaluator_slug (your custom string identifier)

​

Key score fields

• id: Unique score identifier
• log_id: Links the score to its corresponding log entry
• evaluator_id: UUID of Respan platform evaluator (optional)
• evaluator_slug: Custom evaluator identifier (optional)
• is_passed: Whether the evaluation passed defined criteria
• cost: Cost of running the evaluation
• created_at: When the score was created

​

Score value types

Scores support four different value types based on the evaluator’s score_value_type:

​

Detailed descriptions

Numerical Scores

• Use case: Ratings, confidence scores, quality metrics
• Range: Defined by evaluator’s min_score and max_score
• Example: Rating response quality from 1-5

Boolean Scores

• Use case: Pass/fail evaluations, binary classifications
• Values: true or false
• Example: Content safety check

Categorical Scores

• Use case: Multi-choice classifications
• Values: Array of predefined choices from evaluator’s categorical_choices
• Example: ["relevant", "accurate", "helpful"]

Comment Scores

• Use case: Qualitative feedback, explanations
• Values: Free-form text
• Example: Detailed evaluation reasoning

​

Evaluator types

Scores are created by evaluators, which come in three types: LLM Evaluators (type: "llm")

• AI-powered evaluation using language models
• Requires evaluator_definition prompt
• Supports all score value types

Human Evaluators (type: "human")

• Manual evaluation by human reviewers
• Often used with categorical or comment scores
• Requires predefined choices for categorical

Code Evaluators (type: "code")

• Programmatic evaluation using custom code
• Requires eval_code_snippet
• Most flexible for complex logic