Observability

import { Aside } from “@astrojs/starlight/components”;

Alquimia Platform produces three observability signals out of the box: metrics, traces, and logs. All three are correlated by a shared set of dimensions so you can follow a request from the HTTP boundary through every tool call and LLM invocation.

The two-layer model

Observability is split across the two layers of the platform:

Layer	Signal	What it covers
`alquimia-runtime`	Traces, logs	HTTP requests, CloudEvent lifecycle, structured logging
`alquimia-core`	Metrics	Token usage, tool calls, shield invocations, agent lifecycle

The runtime owns the HTTP boundary, so it is the natural place for request-scoped traces and logs. The core SDK owns the agent execution loop, so it emits business-level metrics.

Conversation evaluation with TrustLens

For automated quality evaluation, the optional TrustLens service consumes signed context.persistence.v1 webhooks from the runtime and runs Gaussia benchmarks against conversation sessions. Results are persisted in PostgreSQL and exposed as Prometheus metrics that Studio renders in the Agent Humanity view.

TrustLens supports benchmarks for humanity, context awareness, conversational quality, bias, and toxicity. It is configured through Studio and is typically deployed as a private service alongside the runtime.

Correlation dimensions

Every signal carries the same identifiers:

Dimension	Meaning
`assistant_id`	The agent being invoked
`agentspace_id`	The agentspace containing the agent
`user_id`	The end user
`session_id`	The conversation session
`task_id`	The inference run
`channel_id`	The originating channel, when applicable

These dimensions let you pivot from a slow metric to the matching trace and then to the exact log lines for the same inference run.

Request and task identifiers

X-Request-ID is generated per HTTP call and echoed in the response. Use it to correlate logs for a single API request.
task_id stays the same across the SSE stream, CloudEvent hops, and all worker processing for one inference run.

What is measured

The core SDK emits metrics across categories such as:

LLM token counts and latency
Tool invocations and errors
Shield invocations and errors
Agent execution starts and completions
Empathy rule triggers

The runtime emits traces for HTTP requests and internal CloudEvent handlers, and bridges structured logs to OpenTelemetry.

Enabling observability

OpenTelemetry is disabled by default. Export the standard OTLP endpoints to enable each signal:

OTEL_COLLECTOR_ENDPOINT — metrics
OTEL_COLLECTOR_ENDPOINT_TRACES — traces
OTEL_COLLECTOR_ENDPOINT_LOGS — logs

When running alquimia-runtime, telemetry is initialized automatically during startup. When using alquimia-core directly, call setup_observability() once at application startup.

Privacy and dimension stripping

If certain dimensions such as user_id or session_id must not appear in metrics for compliance reasons, use OTEL_EXCLUDED_ATTRIBUTES. Apply collector-level processors for traces and logs.