Overview
This page summarizes how to observe MAPS Messaging in production: metrics, $SYS topics, REST health, JMX/Jolokia, and logs—with links to focused guides.
Options at a glance
| Channel | What you get | Best for | Guide |
|---|---|---|---|
| Prometheus (JMX Exporter) | JVM + server metrics as time series | Dashboards, alerting, SLOs | Prometheus (JMX Exporter) |
| Jolokia (JMX over HTTP) | Inspect JMX MBeans via REST | Ad‑hoc diagnostics, tools | Jolokia Monitoring |
| $SYS topics | Live server stats as topics | Protocol‑native checks | System Topics ($SYS) |
| REST health | Liveness/readiness/health | Probes, load‑balancers | Rest API |
| Logs | Operational/audit detail | Forensics, support | Logging details |
For long‑term trends and alerting, use Prometheus + Grafana. For quick inspection, $SYS and Jolokia are handy.
Metrics & Telemetry
Prometheus (recommended)
Expose metrics via the JMX Prometheus Java agent (sidecarless):
- Attach the agent with
-javaagentto expose a/metricsendpoint (default example::9404). - Map server JMX to
maps_*metrics with the provided config. - Scrape with Prometheus, visualize in Grafana.
See Prometheus (JMX Exporter).
Jolokia (optional)
HTTP access to JMX for scripting and tools. Enable in config to read bean attributes or trigger operations.
See Jolokia Monitoring.
$SYS Topics (protocol‑native status)
MAPS publishes operational data under $SYS/ and extended JSON under $SYS/server/* (when enabled). Any supported protocol can subscribe. Examples:
- Broker: uptime, version, health
- Clients: connected, peak
- Throughput/bytes: in/out totals
- Endpoints & destinations: per‑listener/per‑queue stats
- Moving‑average variants (if enabled)
See System Topics ($SYS) for details and examples.
REST Health Endpoints
GET /health→OK | Warning | Error(used by load‑balancers/Consul)GET /api/v1/ping→{"status":"Success"}when responsive
Kubernetes probes typically check HTTP status code only. If you must treat
Warningas ready, implement body checks in your probe logic/sidecar.
For full API endpoints, see OpenAPI spec.
Logging (summary)
Runtime logs are written under ${MAPS_DATA}/log/:
messaging.log— operational messages (daily rotation, gzip, 7‑day history)audit.log— audit‑only entries (same rotation)
Default logging uses Logback with async appenders and marker‑based routing.
See Logging details for the default logback.xml, retention, and tuning.
What to monitor
- Availability:
/health - Client load: connected/peak clients, session churn
- Throughput & latency: msgs/bytes in/out, moving averages
- Backlog/pressure: destination pending counts, endpoint errors
- JVM health: heap, GC pauses, threads
- System: CPU, I/O saturation (via host/node metrics)