Observability

Observability & Telemetry

Value Proposition Gain absolute visibility into your automated operations. mysql-mcp integrates deeply with industry-leading telemetry platforms—Prometheus, Grafana, and Datadog—to guarantee transparent and auditable AI-driven database management. Read the full value proposition.

Achieve total 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). 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.

📈 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=true.

Metrics exposed include:

• mcp_queries_total: Total number of queries executed.
• mcp_query_duration_seconds: Histogram of query execution times.
• mcp_tool_calls_total: Total number of MCP tool invocations.
• mcp_active_sessions: Number of current HTTP/SSE sessions.
• V8 Isolate metrics (heap size, execution count).

📊 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.

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

📜 Dozzle for Logs

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.

🖼️ Dashboard Previews

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