Skip to content

Observability

Jump to bottom
Chris edited this page Jul 31, 2026 · 110 revisions

Enterprise Observability & Telemetry

Tools Resources Prompts
OAuth Code Mode Rate Limiting

Value Proposition Gain visibility into AI operations with continuous real-time telemetry. Integrate with observability platforms like Prometheus, Grafana, and Datadog for minimal-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 robust database-specific endpoints seamlessly exposed to your AI agent. Examples include mysql://schema, mysql://insights, mysql://performance, and mysql://metrics. They also include mysql://sysschema for comprehensive wait events and I/O summaries. They empower the AI to proactively evaluate database state, performance metrics, and schema definitions with comprehensive clarity. 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.

When running the exporter container to aggregate telemetry, you must isolate its audit log to prevent race conditions. The container reads the live mcp-audit.jsonl written by the IDE, and must be configured to output its own audit events to a separate file (e.g., --audit-log /var/log/mysql-mcp/exporter-audit.jsonl). You must also explicitly set the AUDIT_LOG_PATH environment variable in the container (/var/log/mysql-mcp/mcp-audit.jsonl) so it knows where to find the IDE's live JSONL file.

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 examples/dashboards/ 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

Grafana Core Dashboard

AI Efficiency

Grafana AI Efficiency Dashboard

MySQL-MCP Logs (Loki)

Grafana Logs Dashboard

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 examples/dashboards/ directory.

Note

Audit Log Configuration: The Audit Log widget dynamically queries source:mysql_mcp log_type:mcp_audit to capture detailed agent activity. By default, mysql-mcp intelligently omits read scope tool payloads (like mysql_read_query) to protect sensitive enterprise data and optimize bandwidth. To actively stream read queries into Datadog, simply append the --audit-reads argument to your server's args array in your MCP client configuration file.

Token & Tool Metrics

Datadog Core Dashboard

AI Efficiency

Datadog AI Efficiency Dashboard

MySQL Cluster Telemetry

Datadog MySQL Telemetry Dashboard

Redis Telemetry

Datadog Redis Telemetry Dashboard

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.
  • Full Observability Ecosystem: The complete open-source observability stack (Prometheus, Grafana, Loki, Alloy, Dozzle, Redis) along with Datadog integrations and the enterprise MySQL architecture.

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

MySQL MCP Documentation

Unlock autonomous database orchestration with an enterprise-grade MySQL MCP server. Featuring blazing-fast sandboxed Code Mode, uncompromising schema enforcement, and seamless ecosystem integrations to power secure, intelligent AI workflows.

🏠 Home

Launch Your Setup

Connect Ecosystem Tools

Enforce Security & Compliance

Scale Your Operations

Explore External Links

Clone this wiki locally