Observability
Reference tables for ENGRAM’s observability surface. For setup instructions (Prometheus scrape config, OTel collector wiring, local Jaeger), see Enable observability.
Application metrics
Section titled “Application metrics”Exposed at GET /health/metrics in Prometheus text format.
| Metric | Type | Labels | Description |
|---|---|---|---|
engram_memory_operations_total |
counter | op, tier, status |
Memory operations by type, tier (stm/ltm), and outcome (success/error) |
engram_memory_operation_duration_seconds |
histogram | op, tier |
Operation latency in seconds |
engram_memories_promoted_total |
counter | — | STM memories promoted to LTM by the consolidation scheduler |
engram_consolidation_runs_total |
counter | status |
Consolidation scheduler runs (success/partial) |
engram_reindex_operations_total |
counter | status |
Vector-store reindex operations |
engram_active_mcp_sessions |
gauge | — | Active Streamable HTTP MCP sessions |
engram_vector_backend_info |
gauge | backend |
Active vector backend (always pgvector) |
engram_deployment_profile_info |
gauge | profile |
Active deployment profile |
engram_pgvector_ready |
gauge | — | Whether pgvector extension is reachable |
engram_agent_memory_operations_total |
counter | agent, op, status |
Store/recall ops per agent (API key) — primary-memory adoption (WP5) |
Standard Node.js process metrics (process_cpu_seconds_total,
nodejs_heap_size_bytes, etc.) are also exposed automatically by
prom-client.
The agent label on engram_agent_memory_operations_total is the
authenticated API-key id (or local for unauthenticated/stdio calls); op is
store or recall.
OpenTelemetry environment variables
Section titled “OpenTelemetry environment variables”| Variable | Default | Purpose |
|---|---|---|
OTEL_EXPORTER_OTLP_ENDPOINT |
unset (disabled) | OTLP HTTP collector endpoint; unset = zero overhead |
OTEL_SERVICE_NAME |
engram-mcp-server |
Service name attached to exported spans |
OTEL_RESOURCE_ATTRIBUTES |
unset | Extra resource attributes (comma-separated k=v) |
Traces are exported over OTLP HTTP to <endpoint>/v1/traces. HTTP requests
and Express routes are auto-instrumented; memory operations (create,
recall, reindex) emit spans via @opentelemetry/api.
Health endpoints
Section titled “Health endpoints”| Endpoint | Purpose |
|---|---|
GET /health |
Liveness probe |
GET /health/ready |
Readiness probe (checks all dependencies) |
GET /health/metrics |
Prometheus metrics |
See Deploy to production for Kubernetes/Docker probe configuration.