Monitoring & Health Checks

Three layers of monitoring are available: the in-app portal reports, machine health endpoints, and Prometheus metrics.

Health endpoints

Endpoint	What it tells you
`GET /pckzra/api/taxint/health`	Basic liveness: status, version, timestamp
`GET /pckzra/actuator/health`	Detailed Spring Boot health, including database connectivity (details always shown)
`GET /pckzra/actuator/info`	Application info
`GET /pckzra/actuator/metrics`	Full metrics catalog
`GET /pckzra/actuator/loggers`	Inspect/adjust log levels at runtime

Component health checks (configurable):

Check	Property	Default
Chrilan API reachability	`health.chrilan.api.check.enabled` / `timeout`	true / 5000ms
Database reachability	`health.database.check.enabled` / `timeout`	true / 3000ms

Prometheus

Metrics are exported in Prometheus format at /pckzra/actuator/prometheus (JVM and system metrics included). Point your Prometheus scrape config at the production host:

scrape_configs:
  - job_name: pck-middleware
    metrics_path: /pckzra/actuator/prometheus
    static_configs:
      - targets: ['server.zra.co.zm:443']
    scheme: https

What to watch

Signal	Where	Alert when
Transaction success rate	Portal dashboard / Reports API	Drops below ~98% over an hour
Failed transactions	Reports → failed (7-day default)	Any sustained cluster of 500s (Chrilan outage) or 403s (store config)
Response time (ms)	Transaction history column / metrics	Sustained rise toward the 30s Chrilan timeout
Per-store volume	Reports → volume by store	A trading store shows zero during business hours
Menu sync	Outbound `/product/createBulk` transactions	Repeated failures for a store (check Oracle LocRef, STS credentials)
DB pool	HikariCP metrics (leak detection at 60s)	Pool exhaustion or leak warnings in logs
Actuator health	`/actuator/health`	Any component DOWN

Logs

Application logs: console + logs/taxint-chrilan-middleware.log
Database audit: api_transactions and conversion_logs (query via Reports or SQL)
Default levels: application INFO; Spring/HTTP/SQL at WARN in production
Enable debug temporarily via /actuator/loggers or by restarting with logging.level.com.micros.taxintchrilan=DEBUG

Useful queries

-- Transactions in the last hour
SELECT COUNT(*) FROM api_transactions
WHERE created_at > NOW() - INTERVAL 1 HOUR;

-- Recent failures with their error
SELECT transaction_id, store_id, status_code, error_message, created_at
FROM api_transactions
WHERE success = FALSE
ORDER BY created_at DESC LIMIT 20;

-- Failed conversions today
SELECT * FROM conversion_logs
WHERE conversion_success = FALSE AND created_at > CURDATE()
ORDER BY created_at DESC;

Alerting notes

A monitoring alerts section exists in configuration (monitoring.alerts); email alerts are currently disabled.
Per-store WhatsApp notification targets (notification_phone, notification_group_id) are stored on each store; store-level alert wiring beyond OTP is on the roadmap.
Until alerting is wired, the daily operating routine in the dashboard guide is the recommended practice.