Observability

Observability & Telemetry

The mysql-mcp server integrates with multiple observability platforms to provide comprehensive monitoring of your database and the MCP server itself.

MCP Resources vs. System Telemetry

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.

Server Logging Levels

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.

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

Grafana Dashboards

The test infrastructure 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.

Datadog Integration

For enterprise-grade observability, the test ecosystem 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:8080.

Dashboard Previews

Below are previews of the Grafana and Datadog dashboards provided in the test infrastructure: