Observability

Enterprise Observability & Telemetry

Value Proposition Gain comprehensive, real-time visibility into your automated database operations. Designed for enterprise scale, mysql-mcp integrates natively with industry-leading telemetry platforms—including Prometheus, Grafana, and Datadog. This ensures every AI-driven action remains transparent, auditable, and highly measurable. Read the full value proposition

Distinguish Telemetry Domains

Establish a clear operational baseline by differentiating between the two pillars of our observability architecture:

• MCP Resources: These are database-specific endpoints exposed to your AI agent (e.g., mysql://schema, mysql://insights, mysql://metrics/performance, and mysql://sys/* for wait events and I/O summaries). They allow the AI to proactively read database state, performance metrics, and schema definitions. See Resources for more details.
• System Telemetry: This refers to the passive metrics and logs exported by the server to external monitoring tools (Prometheus, Grafana, Datadog). This page focuses on setting up and using System Telemetry.

Calibrate Enterprise Server Logging

Maintain precise control over system verbosity. The server outputs structured internal logs based on your meticulously configured log level, which you can set seamlessly via the --log-level flag or the LOG_LEVEL environment variable.

Supported levels:

• debug: Verbose output, including payload serialization sizes and internal function traces.
• info: (Default) Standard operational logs, startup events, and significant connection lifecycle events.
• warn: Recoverable errors or deprecation warnings.
• error: Critical failures and unhandled exceptions.

Tip

Forensic Audit Logging: For complete forensic JSONL logging of all queries, mutations, and Code Mode executions, configure the Audit Subsystem. See Audit Trail for detailed setup instructions.

Persist Metrics with Autonomous SQLite Storage

mysql-mcp automatically persists crucial telemetry and agent activities directly to a resilient, local SQLite SystemDb. This architecture provides comprehensive audit trails, token usage tracking, and AI efficiency metrics out-of-the-box. Edge-local storage guarantees that critical operational intelligence remains highly accessible to your AI agents, even in the event of upstream observability pipeline disruptions.

Harness Prometheus Metrics

The server exports Prometheus metrics via the /metrics endpoint.

Important

Transport Requirement: The /metrics endpoint is only available when using the HTTP transport (--transport http). It is not available in stdio mode.

To enable the metrics endpoint, pass the --metrics-export prometheus flag or set MCP_METRICS_EXPORT=prometheus.

Metrics exposed include:

• mysql_mcp_tool_calls_total: Total number of MCP tool invocations.
• mysql_mcp_tool_latency_ms_p50: Median tool execution latency.
• mysql_mcp_pool_queries_total: Total number of connection pool queries.
• mysql_mcp_resource_reads_total: Total number of resource reads.
• mysql_mcp_uptime_seconds: Server uptime.

Visualize with Grafana

The project's source repository includes a pre-configured Grafana dashboard that visualizes the Prometheus metrics.

• Location: The JSON definitions for the dashboards are located in the test-server/infrastructure/config/grafana/dashboards directory.
• Access: When running the full ecosystem via docker-compose up -d, Grafana is available at http://localhost:3001 with the dashboard pre-loaded.

Enable Datadog Telemetry

For observability, the project's source repository integrates with Datadog. This includes:

• Autodiscovery: The Datadog Agent automatically discovers and monitors all containers.
• eBPF System Probe: Captures deep kernel-level network performance metrics.
• APM Tracing: Enabled for application containers to trace requests across boundaries.
• Live Processes: Tracks host and container processes.
• Custom Dashboards: Includes datadog-ai-dashboard.json for Token & Tool Metrics and AI Efficiency, plus datadog-dashboard.json for deep database insights.

Configuration: The datadog-unified agent is configured via docker-compose.yml and config/datadog-integration-configs/ in the test-server/infrastructure directory.

Monitor Logs with Dozzle

To easily view and search container logs in real-time without using the CLI, the ecosystem includes Dozzle.

• Access: When running the test infrastructure, Dozzle is available at http://localhost:8080.

Review Dashboard Previews

Below are previews of the Grafana and Datadog dashboards provided in the project's source repository: