Observability

Enterprise Observability & Telemetry

Value Proposition Transforming black-box LLM operations into transparent, trackable enterprise assets with comprehensive, real-time actionable insights. Designed for enterprise scale, mysql-mcp integrates natively with industry-leading telemetry platforms such as Prometheus, Grafana, and Datadog. This ensures every AI-driven action remains transparent, auditable, and highly measurable. Read the full value proposition

Distinguish Telemetry Domains

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.

Calibrate Enterprise Server Logging

The server outputs structured internal logs based on your configured log level. Set this seamlessly via the --log-level flag or by using 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: 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.

Persist Metrics with Local SQLite Storage

mysql-mcp automatically persists crucial telemetry and agent activities, writing directly to a local SQLite SystemDb. This architecture provides comprehensive audit trails, token usage tracking, and AI efficiency metrics out-of-the-box. Local storage guarantees high accessibility for critical operational intelligence, ensuring your AI agents retain access during upstream observability pipeline disruptions.

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 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 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: Run the full ecosystem via docker compose up -d. Grafana is then available at http://localhost:3001. The dashboard is 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.
• Custom Dashboards: It includes datadog-ai-dashboard.json for Token and Tool Metrics. This also covers AI Efficiency. It includes datadog-dashboard.json for deep database insights.

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

Monitor Logs with Dozzle

To easily view and search container logs in real-time, the ecosystem includes Dozzle. You can do this without the CLI.

• Access: When running the test infrastructure, Dozzle is available at http://localhost:8080.