Audit Trail

Audit Trail

Value Proposition Enforce uncompromising data governance and zero-trust compliance with automated, high-fidelity audit tracking. Capture precise pre-mutation snapshots to maintain absolute visibility into agent operations, seamlessly balancing autonomous speed with strict organizational security. Read the full value proposition.

⚙️ Enforce Compliance & Governance

Enforce strict data governance and streamline enterprise compliance with comprehensive, automated audit tracking. Maintain complete operational visibility across all AI interactions by capturing granular pre-mutation snapshots, seamlessly bridging AI autonomy with rigorous organizational security.

Zero-Contention Observability Architecture: guarantees high-throughput agent operations are never bottlenecked by forensic logging I/O.

Configure by passing the following flags during server initialization:

• --audit-log <path>: Enables the audit log and specifies the file path (e.g., --audit-log logs/mcp-audit.jsonl). Set to stderr to stream directly to standard error.
• --audit-backup: Enables pre-mutation snapshots for destructive DDL changes.
• --audit-reads: Includes read-scope tool calls (like SELECTs) in the audit log.
• --audit-redact: Automatically redacts sensitive parameters from the JSONL output.
• --audit-log-max-size: Maximum size for the audit log file. Reaching this maximum triggers automatic log rotation (default: 10485760 bytes (10MB)).
• --audit-backup-data: Includes the original row data in pre-mutation snapshots (up to a configured byte limit via --audit-backup-max-size).
• --audit-backup-max-size: Maximum table size in bytes for data capture (default: 52428800 bytes (50MB)).

See the Configuration guide for all audit options, including size limits and the redaction toggle.

Architect Zero-Contention Forensic Observability: Exporter Split-Path Architecture (mysql-mcp-exporter / neverinfamous/mysql-mcp)

When running the Prometheus metrics exporter in Docker (using the local mysql-mcp-exporter build or the remote neverinfamous/mysql-mcp image), the system enforces strict read/write separation to avoid lock contention.

The primary IDE application writes continuously to mcp-audit.jsonl. The exporter container reads the IDE's audit log via a separate environment variable (AUDIT_LOG_PATH), while its internal logs are written to a distinct file (exporter-audit.jsonl):

Variable / Flag	Value	Purpose
AUDIT_LOG_PATH	/var/log/mysql-mcp/mcp-audit.jsonl	Read-only path to the IDE's live audit JSONL, mounted from your host's local log directory (e.g., ./logs or ../../logs depending on your deployment directory)
--audit-log	/var/log/mysql-mcp/exporter-audit.jsonl	Write path for the exporter's own audit events

This Exporter Split-Path Architecture separates the read path (AUDIT_LOG_PATH reading mcp-audit.jsonl) from the write path (--audit-log writing to exporter-audit.jsonl for the exporter's own AuditLogger), preventing log rotation race conditions.

Integrate Observability Pipelines (Datadog & OpenTelemetry)

To integrate the audit log into centralized observability platforms:

• Datadog Agent: Configure the agent to tail mcp-audit.jsonl using inotify. Ensure the configuration points correctly to the mounted log directory and avoids duplicate autodiscovery.
• OpenTelemetry: Use the OTel Collector filelog receiver to ingest, parse, and forward the JSONL structured logs securely.

Warning

When using Grafana Alloy to forward audit logs to Loki, ensure strict routing is configured to prevent large log line truncation or buffer fragmentation.

Note

V8 isolate internal data mutations (Code Mode) are not captured by the audit log; only database queries executed from the isolate are logged.

• Resources — mysql://audit resource details
• Code Mode — Native V8 isolate
• Tools — Full tool list with scope groups
• Configuration — Configuration options