Skip to content

audit-log.mdx

Latest commit

 

History

History
74 lines (59 loc) · 3.11 KB

audit-log.mdx

File metadata and controls

74 lines (59 loc) · 3.11 KB
Raw
title Audit Log
icon ScrollText
description Every statement an agent runs, allowed or blocked, recorded with its decision, reason, rows, bytes, latency, and credential.

The audit log records every statement a credential runs through PgBeam, whether it was allowed, masked, blocked, or throttled. Each entry captures the SQL, the decision and the reason for it, the rows and bytes returned, the latency, and the credential that ran it. Recent entries are queryable in the control plane; older entries are archived for retention.

It covers agent and human credentials, and records each credential's principal_type so you can tell agent traffic from people. To stream events to your own systems in real time, see audit export; to flag unusual behavior automatically, see anomaly detection.

What is recorded

Field Description
Time When the statement ran.
Credential The agent credential that ran it.
SQL The statement, as parsed.
Decision allowed, masked, blocked, or throttled.
Reason Why it was blocked, masked, or throttled.
Rows Rows returned to the agent (after masking and row caps).
Bytes Bytes returned.
Latency Time to serve the statement.
Source Connection string or hosted MCP.

Read the log

Open the Audit tab in the dashboard to filter by agent, decision, or time range and export the result. From the terminal or API:

# CLI
pgbeam audit list --decision blocked --since 24h

# API
curl "https://api.pgbeam.com/v1/projects/{projectId}/audit?decision=blocked" \
  -H "Authorization: Bearer pbo_..."

How the pipeline works

Each data plane captures the decision for every agent statement and ships it to the control plane. Recent entries are stored in control-plane Postgres for fast querying, and batched archives are written to object storage for long-term retention.

Audit retention depends on your plan: 7 days on Starter, 30 days on Pro, and 90 days on Scale. See [Plans](/docs/plans). Archived entries remain available for export within your retention window.

What it is good for

  • Answer "what did this agent do" with the exact statements and decisions.
  • Show a reviewer or security owner that an agent was held to its policy.
  • Spot an agent that is hitting blocks or budgets and needs its policy adjusted.

Related