Zwall
Talk to an Engineer
Talk to an Engineer
Documentation
Docs Home › Observability › Prometheus and Grafana

Prometheus and Grafana

Purpose

Scrape Manager Prometheus text and import shipped Grafana dashboards into your Prometheus/Grafana. Zwall does not operate a Grafana cloud and this is not a Splunk/SIEM product.

Audience

Operators who already run Prometheus and Grafana.

Edition

SHARED Manager /metrics. Enterprise tree also contains grafana/dashboards/cluster-ha.json. Manager cluster is not a public HA product; do not enable that dashboard as certified HA.

Status

SUPPORTED as operator-hosted scrape plus example dashboards. The in-tree prometheus/prometheus.yml example targets localhost:8080 with scheme: http and a bearer token file. That matches unconfigured zwallctl, not the Manager example TLS listen 8443. Point scrape at the real Manager URL.

Prerequisites

  • metrics.enabled: true (example true)
  • Admin JWT (or session) for scrape — /metrics uses AdminAuth + RoleAuth("admin")
  • Optional metrics.allowed_cidrs if you restrict scraper IPs
  • You operate Prometheus and Grafana

Required permissions

Administrator role for scrape. Treat the scrape token as admin-equivalent.

Dependencies

Manager process ready. TLS files if the Manager listens with server.tls.enabled: true.

Configuration

Scroll sideways to see the full table. Use the arrow keys when focused.

KeyExample
metrics.enabledtrue
metrics.path/metrics
metrics.allowed_cidrsempty = no IP restriction (still requires auth)
metrics.trusted_proxy_cidrsempty = never trust forwarded headers

If metrics.enabled is false, the route is not registered.

Agent optional metrics: disabled by default; if enabled, bind 127.0.0.1:9090 with paths /metrics and /health. Empty Agent allowed_cidrs means localhost only. Hosting observation profile rejects metrics.enabled on the Agent (no listener).

Shipped Grafana JSON under grafana/dashboards/:

  • agent-status.json
  • attack-patterns.json
  • authentication.json
  • security-overview.json
  • system-performance.json
  • cluster-ha.json (Enterprise tree; not a certified HA product)

Provisioning examples: grafana/provisioning/. Alert rule template: prometheus/rules.yml.

In-tree Prometheus job uses bearer_token_file: /etc/prometheus/zwall_admin_token.txt. Do not put live JWTs in documentation or world-readable files.

Procedure

  1. Enable metrics.enabled if it was turned off; restart the Manager.
  2. Obtain an admin JWT (zwallctl login interactive). Store it only in a 0600 file Prometheus can read.
  3. Scrape https://manager.example.com:8443/metrics (replace with your origin). Use HTTPS and a CA your Prometheus trusts. Do not copy the example scheme: http / :8080 blindly.
  4. Confirm HTTP 200 and Prometheus exposition format. Unauthenticated scrape must not return metrics.
  5. Import the JSON dashboards you need into your Grafana. Skip cluster-ha.json as a customer HA dashboard.
  6. Optional CIDR allowlist for scraper IPs.

Verification 

curl -sS https://manager.example.com:8443/metrics \
  -H "Authorization: Bearer TOKEN" | head

Prefer a token from interactive login, not from argv in shared shell history. Dashboard panels populate after scrape. Template intervals (10s job / 15s global) are examples, not availability targets.

Expected result

Operator-hosted Prometheus has Manager samples. Grafana shows the imported dashboards. No Zwall-operated Grafana.

Failure modes

Scroll sideways to see the full table. Use the arrow keys when focused.

SymptomCauseAction
404metrics.enabled falseenable and restart Manager
401/403not admin JWTlogin as admin
connection refused :8080Manager URLs and ports mismatchscrape TLS 8443 (or your real api_port)
empty Grafanascrape failing TLS/authfix Prometheus job
cluster-ha panels emptycluster not a customer productignore that dashboard
Hosting Agent /metrics missingprofile forbids Agent metricsscrape the Manager only

Troubleshooting

journalctl -u zwall-manager. Confirm /health/ready before debugging Grafana. Token expiry follows auth.token_expiry (example 8h) — a static bearer file will go stale unless you refresh it.

Security considerations

  • /metrics is admin-gated. A scraper credential is an administrator credential.
  • Do not expose unauthenticated /metrics on the public internet (the product does not offer that mode when metrics are enabled).
  • Rotate the scrape JWT when administrators rotate credentials.
  • Do not scrape Hosting Agents for Prometheus; they expose no metrics listener.

Limitations

Not Splunk. Not a Zwall-operated cloud. Metric names in dashboards are templates; there is no generated OpenAPI/metric catalog published as a customer contract.