Concepts

Architecture

How data flows from your application into Introspection.

SDK

The SDK lives inside your application. It emits three types of signal:

Traces — execution data from model calls, tool calls, agent steps, retrieval, and orchestration. Traces show what the system did and where it spent time.
Events — product activity that does not fit naturally into a span: page views, workflow state changes, retries, escalations.
Feedback — outcome signals from users or reviewers: thumbs up/down, ratings, comments, review labels. Feedback links execution to human judgment.

The SDK propagates user, conversation, and agent context via OpenTelemetry baggage so all three signal types are automatically attributed.

Transport

All telemetry is sent as OTLP over HTTPS. This means:

Any OpenTelemetry-compatible instrumentation works out of the box
You can dual export the same spans to Introspection and another backend simultaneously
No proprietary wire format

Processing

Once data reaches Introspection, the platform:

Authenticates the request against your project’s API key
Extracts Gen AI semantic convention attributes (model, messages, token usage, tool/agent activity)
Links identity and conversation context to each span
Groups related spans into traces, events, and feedback records
Converts OpenInference attributes to Gen AI semconv where needed

Attribute Mapping

Introspection natively understands both Gen AI semantic conventions and OpenInference. If you use OpenInference instrumentation, these fields are converted automatically:

OpenInference	Gen AI semconv
`llm.model_name`	`gen_ai.request.model`
`llm.token_count.prompt`	`gen_ai.usage.input_tokens`
`llm.token_count.completion`	`gen_ai.usage.output_tokens`
`llm.input_messages.*`	`gen_ai.input.messages`
`llm.output_messages.*`	`gen_ai.output.messages`

Storage

Introspection separates:

Telemetry storage (ClickHouse) for traces, spans, and logs — optimized for high-volume append and fast analytical queries
Relational storage (PostgreSQL) for configuration, accounts, issues, and tasks
Cache and real-time infrastructure (Redis) for responsive product features

Deployment

Model	Data Plane	Control Plane
Managed Cloud	Introspection	Introspection
Hybrid	Customer VPC	Introspection
Self-Hosted	Customer VPC	Customer VPC

See Security for encryption, networking, and access control details.