Health checks, Prometheus metrics, OpenTelemetry tracing, profiling, and CLI diagnostics.

Moca now exposes an observability surface across the server and CLI:

• health endpoints for liveness and readiness
• Prometheus metrics from a dedicated registry
• OpenTelemetry tracing over OTLP/gRPC
• moca doctor for project, infrastructure, and per-site diagnostics
• moca dev bench for live microbenchmarks
• moca dev profile for pprof capture and SVG flamegraphs

• GET /health
• GET /health/ready
• GET /health/live

Prometheus metrics are enabled by default and served from observability.metrics.path, which defaults to /metrics.

The server registers 13 framework metrics covering:

• HTTP request count and latency
• document operation count and latency
• cache hits and misses
• queue throughput and duration
• Kafka publish counts and consumer lag
• active WebSocket connections
• database query duration and active pool usage

Only Moca's custom registry is exposed on the metrics endpoint; default Go process metrics are not added automatically.

When development.enable_pprof: true is set, the server exposes:

• GET /debug/pprof/
• GET /debug/pprof/cmdline
• GET /debug/pprof/profile
• GET /debug/pprof/symbol
• GET /debug/pprof/trace

development:
  enable_pprof: true

observability:
  metrics:
    enabled: true
    path: /metrics
  tracing:
    enabled: true
    exporter: otlp
    endpoint: localhost:4317
    insecure: true
    sample_rate: 1.0

Notes:

• observability.metrics.enabled defaults to enabled when omitted
• observability.metrics.path defaults to /metrics
• tracing is disabled unless observability.tracing.enabled: true
• tracing defaults to exporter: otlp, endpoint: localhost:4317, insecure: true, and sample_rate: 1.0

moca doctor runs project, infrastructure, and optional per-site checks. Depending on flags and configuration it can validate:

• config parsing
• installed Moca version
• local disk space
• PostgreSQL
• Redis
• Kafka
• Meilisearch
• object storage
• site schema existence
• site search indexes
• queue backlog / DLQ status

Useful flags:

• --site <site> adds site-specific checks
• --verbose shows details such as latency and version info
• --json returns machine-readable output
• --fix exists for future auto-remediation hooks but does not yet repair the current check set

Fetches the raw Prometheus text output from http://localhost:<port>/metrics. This is the quickest way to verify that the default metrics endpoint is reachable locally.

Runs synthetic latency benchmarks against a live site's PostgreSQL and Redis connections:

• read
• write
• query
• cache
• all (default)

Results include min/max/mean plus p50, p95, p99, ops/sec, and error count.

Downloads a pprof profile from the running server and either:

• saves the raw .pb.gz, or
• generates an SVG flamegraph with go tool pprof

cpu and block profiles honor --duration; mem, goroutine, and mutex are snapshots.

The repository's docker-compose.yml now includes Jaeger for local trace inspection:

• OTLP gRPC ingest: localhost:4317
• Jaeger UI: http://localhost:16686

This is intended for development and test environments; production deployment guidance still lives under the deployment docs.

• moca monitor live is still a placeholder command and does not launch a TUI dashboard
• moca monitor metrics assumes the default /metrics path and does not follow a custom observability.metrics.path
• the wiki does not yet ship Grafana dashboard templates or alert rules
• tracing is available, but exporters other than OTLP are not documented because the current server wiring targets OTLP only

• Configuration Reference
• CLI Commands Reference
• System Overview