Using Metrics

GeoHazardWatch can export application metrics in Prometheus format for monitoring with tools like Prometheus , Grafana, or any OpenTelemetry-compatible collector.

Enabling Metrics

Metrics are disabled by default. To enable, add the following to your custom configuration (data/config/app-custom-config.json) and restart the server:

Current Configuration Value

Key: ngdpbase.telemetry.enabled

Value: false

When enabled, a Metrics card appears on the Admin Dashboard and raw Prometheus data is available at /metrics.

Endpoints

Endpoint	Port	Access	Purpose
`http://<host>:9464/metrics`	9464	No authentication	Prometheus scrape target
`http://<host>:<appport>/metrics`	App port	Admin role required	Browser and admin access

Use port 9464 for Prometheus scrape targets. The main app /metrics endpoint is for admin inspection and is not intended for automated scraping.

Configuration

Configuration Values (11 matches) — ngdpbase.telemetry.*

Key	Value
`ngdpbase.telemetry.enabled`	`false`
`ngdpbase.telemetry.metrics.host`	`0.0.0.0`
`ngdpbase.telemetry.metrics.interval`	`15000`
`ngdpbase.telemetry.metrics.path`	`/metrics`
`ngdpbase.telemetry.metrics.port`	`9464`
`ngdpbase.telemetry.otlp.enabled`	`false`
`ngdpbase.telemetry.otlp.endpoint`
`ngdpbase.telemetry.otlp.headers`	`{}`
`ngdpbase.telemetry.otlp.interval`	`30000`
`ngdpbase.telemetry.otlp.timeout`	`30000`
`ngdpbase.telemetry.service-name`

Metrics Reference

All metric names are prefixed with the application name (sanitized for Prometheus). For example, if the application name is mysite, metrics are prefixed mysite_. The examples below use {app} as a placeholder.

Counters

Metric	Description	Labels
`{app}_page_views_total`	Total page views	—
`{app}_page_saves_total`	Total page saves	—
`{app}_page_deletes_total`	Total page deletions	—
`{app}_login_attempts_total`	Total login attempts	—
`{app}_search_rebuilds_total`	Total search index rebuilds	—
`{app}_http_requests_total`	Total HTTP requests	`method`, `route`, `status`

Histograms

Metric	Description
`{app}_page_view_duration_ms`	Time to render a page view
`{app}_page_save_duration_ms`	Time to save a page
`{app}_page_delete_duration_ms`	Time to delete a page
`{app}_engine_init_duration_ms`	Time for engine initialisation
`{app}_http_request_duration_ms`	Time to handle an HTTP request

Prometheus Integration

Add a scrape target to your prometheus.yml:

scrape_configs:
  - job_name: 'mysite'
    scrape_interval: 15s
    static_configs:
      - targets: ['localhost:9464']

For Docker deployments, replace localhost with the container hostname or service name.

OTLP Export

In addition to OpenTelemetry pull-based scraping, metrics can be pushed to a remote OpenTelemetry collector via OTLP HTTP. Enable alongside Prometheus:

"ngdpbase.telemetry.otlp.enabled": true,
"ngdpbase.telemetry.otlp.endpoint": "https://otel.example.com/v1/metrics"

If the collector requires authentication:

"ngdpbase.telemetry.otlp.headers": { "Authorization": "Bearer <token>" }

Example Queries

Replace {app} with your actual metric prefix.

# Average page view duration over the last 5 minutes
rate({app}_page_view_duration_ms_sum[5m]) / rate({app}_page_view_duration_ms_count[5m])

# Request rate by route
sum(rate({app}_http_requests_total[5m])) by (route)

# Error rate (5xx responses)
sum(rate({app}_http_requests_total{status=~"5.."}[5m]))

Notes

Counters reset to zero on every server restart — this is normal Prometheus behavior. Graphs showing rates will show a gap at restart boundaries.
If port 9464 is already in use, change it with ngdpbase.telemetry.metrics.port.
Disabling metrics (ngdpbase.telemetry.enabled: false) adds no performance overhead — all recording calls become no-ops.

Documentation for Developers

Refer to Documentation for Developers