Observability
Value Proposition Gain visibility into AI operations with real-time telemetry. Integrate with observability platforms like Prometheus, Grafana, and Datadog to continuously monitor, measure, and optimize agent actions. Read the full value proposition
Establish a clear operational baseline. Differentiate between the two pillars of our observability architecture:
-
MCP Resources: These are database-specific endpoints. They are exposed to your AI agent. Examples include
mysql://schema,mysql://insights, andmysql://metrics/performance. They also includemysql://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 passive metrics and logs. The server exports these to external monitoring tools. Examples include Prometheus, Grafana, and Datadog. This page focuses on setting up and using System Telemetry.
The server outputs structured internal logs based on your configured log level. Set this via the --log-level flag or by using the LOG_LEVEL environment variable.
Note
The LOG_LEVEL environment variable does not use the MCP_ prefix. This is also true for other database configuration variables like MYSQL_POOL_SIZE and PROXYSQL_HOST.
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: You may want complete forensic JSONL logging. This includes all queries, mutations, and Code Mode executions. If so, configure the Audit Subsystem. See Audit Trail for detailed setup instructions.
mysql-mcp persists telemetry and agent activities to a local SQLite SystemDb. This provides audit trails, token usage tracking, and AI efficiency metrics out-of-the-box.
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.
The project's source repository includes pre-configured Grafana dashboards for both metrics and logs.
-
Metrics: Visualizes Prometheus metrics exposing
mysql-mcptool usage, latencies, and resource reads. -
Logs: The MySQL-MCP Logs (Loki) dashboard visualizes structured
mcp-audit.jsonlandagent-issues.jsonlstreams, aggregated natively by Promtail. -
Location: The JSON definitions for the dashboards are located in the
test-server/infrastructure/configdirectory. -
Access: Run the full ecosystem via
docker compose up -dfrom thetest-server/infrastructuredirectory. Grafana is then available athttp://localhost:3001(login:admin/admin). The dashboards are pre-loaded.
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: It includes
datadog-dashboard.jsonfor Token and Tool Metrics. This includes the live MySQL-MCP Audit Log stream. It also includesdatadog-ai-dashboard.jsonfor AI Efficiency (cost, caches, and pooling) and deep database insights,datadog-redis-laptop.jsonfor monitoring Redis rate-limiting, cache hits, memory usage, and command rates, as well asdatadog-mysql-laptop.jsonfor MySQL Cluster Telemetry. These dashboard JSON files reside intest-server/infrastructure/config/.
Note
Audit Log Configuration: The Audit Log widget queries source:mysql_mcp log_type:mcp_audit to capture agent activity. By default, mysql-mcp omits read scope tool payloads (like mysql_read_query) to protect sensitive enterprise data and optimize bandwidth. To stream read queries into Datadog, add the --audit-reads argument to your server's args array in your MCP client configuration file.
We provide production-ready Docker Compose templates in the examples/ directory of the repository. These templates include full Datadog observability out-of-the-box:
- Basic Template: A lightweight, single-node MySQL setup with Datadog Agent.
- Enterprise HA Template: A highly-available InnoDB Cluster with MySQL Router, ProxySQL, and Datadog Agent.
See the README files in those directories for quick start instructions.
Configuration: End-users should start with the templates in the examples/ directory. The internal development test server configures the datadog-unified agent via docker-compose.yml in the test-server/infrastructure directory.
Streamline container log analysis and easily view and search container logs in real-time using Dozzle, included in the ecosystem. You can do this without the CLI.
-
Access: When running the test infrastructure, Dozzle is available at
http://localhost:8080.