Monitoring & Observability
Relevant source files
The following files were used as context for generating this wiki page:
Monitoring and Observability in the Memory Context Browser (MCB) project is a multi-layered system designed to provide real-time visibility into the health, performance, and structural integrity of the MCP server. The system encompasses infrastructure-level metrics (CPU, Memory), application-level telemetry (HTTP request rates, cache hit ratios), and developer-centric quality reports (architecture validation, complexity metrics).
The observability stack integrates Prometheus for metric collection, Grafana for visualization, and a built-in Admin UI for direct inspection of system state. This ensures that AI coding agents and human developers can maintain a high-performance, persistent memory environment with validated architectural boundaries.
Infrastructure & System Monitoring
MCB utilizes a Kubernetes-native monitoring approach, exposing telemetry through standard endpoints for scrape-based collection.
Metric Collection Architecture
The application exposes performance data via a dedicated metrics endpoint, typically consumed by a Prometheus ServiceMonitor. The data flows from the application pods through internal services to the monitoring stack.
Diagram showing the flow of metric data from Kubernetes pods to Grafana visualization.
Sources: k8s/README.md:92-102, k8s/README.md:18-24
Resource and Performance Metrics
The system tracks several critical resource and performance indicators to ensure stability and high-performance semantic search operations.
| Metric Name | Type | Description |
|---|---|---|
mcp_cpu_usage_percent | Gauge | Percentage of CPU utilization (Warning at 70%, Error at 90%) |
mcp_memory_usage_percent | Gauge | Percentage of Memory utilization (Warning at 70%, Error at 85%) |
mcp_http_requests_total | Counter | Total number of HTTP requests processed |
mcp_http_request_duration_seconds | Histogram | Latency distribution of HTTP requests |
mcp_active_connections | Gauge | Number of concurrent active connections to the server |
mcp_cache_hit_ratio | Gauge | Efficiency of the internal caching layer |
Sources: monitoring/grafana/dashboards/mcp-overview.json:28-115, k8s/README.md:92-100
Admin UI & Health Checks
MCB provides an integrated Admin Web UI for direct inspection of the running instance, which is critical for verifying session status and indexing progress.
Health Endpoints
The server implements multiple endpoints for automated and manual health verification:
- Liveness Probe (
/api/alive): Checks if the container is running. - Readiness Probe (
/api/alive): Checks if the application is ready to serve traffic. - Health API (
/health): Returns a JSON object containing the system status and basic metrics.
Sources: k8s/README.md:135-138, tests/e2e/admin-functional.spec.ts:50-58
UI Components
The Admin UI is organized into functional modules that allow for granular observability:
- Config Page: Displays the active provider (e.g., OpenAI, Ollama) and vector store configurations.
- Jobs Page: Monitors background indexing tasks, showing status labels such as
idle,running, orcomplete. - Browse Page: Provides a visual grid of indexed code collections and chunks.
Sources: tests/e2e/admin-functional.spec.ts:25-48, README.md:37-41
Quality & Architecture Observability
Beyond runtime performance, the project treats architectural integrity as a measurable metric through the mcb-validate crate.
Validation Reporting
The GenericReporter facilitates the generation of validation reports in multiple formats (JSON, Human-Readable, and CI-specific). It groups violations by category (e.g., architecture, quality, naming) to provide a clear view of the codebase's structural health.
Class diagram representing the structure of the internal validation reporting system.
Sources: crates/mcb-validate/src/generic_reporter.rs:21-55
Software Metrics Analysis
The system performs statistical analysis on SARIF issues and code metrics, such as the Maintainability Index (MI).
| Metric | Target | Significance |
|---|---|---|
| Maintainability Index | > 65 | Combines Halstead Volume, CC, and LOC into a single score. |
| Cognitive Complexity | Lower is better | Measures how difficult code is to understand mentally. |
| Cyclomatic Complexity | Lower is better | Measures the number of linearly independent paths. |
Sources: scripts/qlty/report.py:12-45, crates/mcb-validate/rules/metrics/METRIC006_maintainability-index.yml:12-20
Service Level Objectives (SLO)
The project defines SLOs that are monitored via the Grafana dashboard to ensure professional-grade reliability.
- Uptime Compliance: Targeted at 99.95% over a 30-day window.
- Latency Compliance: P95 Latency for critical endpoints (like
/api/search) is expected to be under 200ms. - Error Rate: Maximum acceptable error rate is 0.1% for normal operations.
Sources: monitoring/grafana/dashboards/mcp-overview.json:151-205
Monitoring and observability in MCB ensure that the persistent memory and semantic search capabilities remain reliable and performant. By combining infrastructure gauges with architectural validation, the system provides a holistic view of both the application's runtime behavior and its internal quality.