Observability

Observability & Telemetry

Value Proposition Gain unprecedented visibility into your automated database operations. By integrating natively with industry-leading telemetry platforms like Prometheus, Grafana, and Datadog, mysql-mcp ensures every AI-driven action is fully transparent, highly auditable, and easily measurable. Read the full value proposition

Achieve complete operational clarity. The mysql-mcp server integrates natively with industry-leading observability platforms—empowering you with comprehensive, real-time monitoring of both your database and the MCP server itself.

Distinguish Telemetry Domains

It's important to differentiate between the two types of observability available:

• 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 Server Logging

The server outputs internal logs based on the configured log level. You can set the log level using 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 SQLite SystemDb

mysql-mcp persists deep telemetry and agent activities directly to a local SQLite SystemDb. This provides comprehensive forensic audit trails, long-term token usage tracking, and AI efficiency metrics out-of-the-box. The local storage guarantees that critical operational data remains accessible to the agent even if external observability pipelines are temporarily unavailable.

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 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:3000 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:8081.

Review Dashboard Previews

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