Trace how AI agent activity travels from the aidb extension to the EDB Agent Governance screens. EDB Agent Governance reads that activity from a Postgres database that runs the aidb extension. The extension records what agents do, and which actions purpose enforcement allowed or denied, as OpenTelemetry telemetry inside the database itself. The viewer's backend reads that telemetry over a read-only connection, and the viewer renders it. No log pipeline sits in between.
Postgres clusters managed by EDB Hybrid Manager (HM) and standalone Loki endpoints are still supported as a legacy path, on which the viewer reconstructs sessions from Postgres query logs. See Tracing the legacy data path: Hybrid Manager and Loki.
Tracing the data path
Follow an agent call through four stages before it appears in the viewer.
┌─────────────────────────────┐
│ AI agent (aidb registry) │ runs inside Postgres as the
└──────────────┬──────────────┘ role of its declared purpose
│ 1. agent calls, tool calls, governed SQL
▼
┌─────────────────────────────┐
│ aidb extension │ one purpose_decision span per
│ aidb.otel_client=database │ governed SQL (allowed or denied)
└──────────────┬──────────────┘
│ 2. spans and log records
▼
┌─────────────────────────────┐
│ Source database │ plain tables; retention is
│ aidb_otel.traces, .logs │ configured by the operator
└──────────────┬──────────────┘
│ 3. read-only role over TLS, nothing copied
▼
┌─────────────────────────────┐
│ Viewer backend │ groups traces into sessions,
│ │ extracts decisions, holds credentials
└──────────────┬──────────────┘
│ 4. API, no credentials
▼
┌─────────────────────────────┐
│ Viewer (browser) │ Dashboard, Activity,
│ │ session, and Agents pages
└─────────────────────────────┘Recording telemetry with the aidb extension
Set the aidb.otel_client parameter to database to make aidb write telemetry; the default, noop, writes nothing. For each agent call it records spans in aidb_otel.traces and log records in aidb_otel.logs. Every tool SQL execution that runs under a purpose-resolved role also emits one purpose_decision span that says whether the action was allowed or denied, for which principal and Postgres role, and why it was denied. The attributes aidb records are listed in the AIDB observability reference. See Connecting an aidb database for enabling telemetry.
Decisions are recorded only for agents from the aidb agent registry whose reasoning loop runs inside Postgres, and only for SQL that runs under a purpose-resolved role. Agents whose loop runs outside Postgres — for example, through Airman MCP — aren't recorded in aidb_otel at all; they're visible only through the legacy path.
Storing telemetry in the source database
Plan retention and access control for the two ordinary tables that hold the telemetry in the database the agents use. Anyone with write access to the aidb_otel schema can change or delete rows, and the optional cleaner worker deletes rows older than a retention window. The viewer therefore shows the recorded activity that is still stored — not a complete or tamper-evident history. See Handling retention and missing data.
Reading telemetry in the viewer backend
Connect the viewer backend to each registered database with a dedicated read-only role over TLS (sslmode=verify-ca or verify-full). The backend reads only aidb_otel.traces and aidb_otel.logs. It never writes to the source database, and it doesn't copy the telemetry into its own database: each page reads the source directly, so activity appears within seconds of the first agent call, and rows removed by retention disappear from the viewer. The backend groups traces by the identifiers aidb recorded — an MCP session, a Postgres connection, a conversation, or the trace itself — extracts governance decisions from the spans, and loads long sessions page by page. The connection string and certificates are encrypted at rest and never reach the browser. See Connecting an aidb database and Securing access and handling credentials.
Rendering telemetry in the viewer
Use the viewer — a single-page application that manages client-side routing and calls the backend for all data — to open the cluster Dashboard, Activity, session, and Agents pages. Credentials never reach the browser — the backend holds them and reads the source on the browser's behalf.
Tracing the legacy data path: Hybrid Manager and Loki
Use the legacy path for Postgres clusters managed by HM, and for any cluster whose logs are shipped to a standalone Loki endpoint. The viewer doesn't read aidb_otel for these clusters. See Connecting Hybrid Manager or Loki.
On this path, AI agents reach Postgres through the Airman MCP server, which tags every query by setting the Postgres application_name session variable to airman:<purpose>/<session-short>. Postgres logs each statement with that tag, Loki stores the log lines, and the viewer's backend reconstructs sessions from them. This path shows the SQL an agent ran and whether the database refused it, but it records no agent identity and no purpose-enforcement decision.
┌─────────────────────────────┐
│ AI agent via Airman MCP │ application_name =
└──────────────┬──────────────┘ 'airman:<purpose>/<session-short>'
│ 1. tagged SQL
▼
┌─────────────────────────────┐
│ Postgres cluster │ logs each statement with the tag,
└──────────────┬──────────────┘ SQL, duration, severity, role, PID
│ 2. JSON log lines
▼
┌─────────────────────────────┐
│ Loki │ HM Loki pipeline or a
│ │ standalone instance; LogQL
└──────────────┬──────────────┘
│ 3. LogQL queries, incremental sync
▼
┌─────────────────────────────┐
│ Viewer backend │ parses log lines into sessions,
│ │ caches summaries, holds credentials
└──────────────┬──────────────┘
│ 4. API, no credentials
▼
┌─────────────────────────────┐
│ Viewer (browser) │ clusters, sessions,
│ │ session detail
└─────────────────────────────┘Tagging queries with Airman MCP
Route agent Postgres operations through Airman MCP, the MCP server AI agents call on this path. It enforces the access mode — rejecting disallowed statement types in restricted mode — and tags every query with the airman:<purpose>/<session-short> identifier. The tag persists for the duration of the connection, grouping all queries in one agent interaction under a single session. See Configuring Airman MCP.
Logging queries in Postgres and Loki
Enable JSON logging on the Postgres cluster so it records every statement Airman MCP sends, with its application_name, SQL text, duration, error severity, database, role, and process ID. Loki ingests those log lines, labels them by container and cluster, and makes them queryable via LogQL. EDB Agent Governance works with both the HM-managed Loki pipeline and standalone Loki instances.
Syncing and caching sessions
Use the viewer backend's sync and caching on this path: it queries Loki via LogQL, parses the results into structured session and step data, and caches session summaries for fast retrieval. It uses a watermark-based incremental sync to avoid full-range Loki queries on repeated visits, splits high-verbosity query windows to stay within Loki's per-query limits, and applies separate retry policies for background sync and proxied requests. Resyncing clears all cached sessions and watermarks and restarts the pipeline from scratch. See Resyncing an instance.