Observability

Enterprise Observability & Telemetry

Value Proposition Gain visibility into AI operations with continuous real-time telemetry. Integrate with observability platforms like Prometheus, Grafana, and Datadog for zero-overhead metrics export and forensic diagnostic auditing to monitor, measure, and optimize agent actions. Read the full value proposition.

---

Establish Visibility

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, and mysql://metrics/performance. They also include 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 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.

---

Configure Server Logging

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.

---

Telemetry Persistence with Local Storage

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.

---

Export Prometheus Metrics

The server exports Prometheus metrics via the /metrics endpoint.

Important

Transport Requirement: The /metrics endpoint is exposed via the MCP v2 streamable HTTP transport (--transport http / NodeStreamableHTTPServerTransport) and remains disabled 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 pre-configured Grafana dashboards for both metrics and logs.

• Metrics: Visualizes Prometheus metrics exposing mysql-mcp tool usage, latencies, and resource reads.
• Logs: The MySQL-MCP Logs (Loki) dashboard visualizes structured mcp-audit.jsonl and agent-issues.jsonl streams, aggregated natively by Grafana Alloy (replaces EOL Promtail).
• Location: The JSON definitions for the dashboards are located in the test-server/infrastructure/config directory.
• Access: Run the full ecosystem via docker compose up -d from the test-server/infrastructure directory. Grafana is then available at http://localhost:3001 (login: admin / admin). The dashboards are pre-loaded.

Token & Tool Metrics

AI Efficiency

MySQL-MCP Logs (Loki)

---

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: We include pre-configured datadog-dashboard.json for Token and Tool Metrics (including the live MySQL-MCP Audit Log stream), datadog-ai-dashboard.json for AI Efficiency, datadog-mysql.json for MySQL Cluster Telemetry, and datadog-redis.json for Redis Telemetry. These dashboard JSON files reside in the test-server/infrastructure/config/ directory.

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.

Token & Tool Metrics

AI Efficiency

MySQL Cluster Telemetry

Redis Telemetry

Infrastructure Templates

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.

Monitor Logs with Dozzle

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.

---

Explore Related Topics

• Tools
• Resources
• Audit Trail