Skip to content

API and Prometheus Metrics ​

Podux can create API keys for scripts, Home Assistant, Grafana or Prometheus. Manage them under Settings → API.

Creating an API Key ​

Enter a name, pick the access level and click Create key. Keys start with pdx_ and are shown only once: Podux stores just their SHA-256 hash, so a lost key cannot be recovered; delete it and create a new one. The list shows the first characters of each key and when it was last used, so you can tell them apart.

Deleting a key rejects its requests immediately.

AccessWhat it allows
Read-onlyReading metrics, dashboard stats and proxy status
Read and writeAll of the above, plus starting, stopping and reloading frpc, and enabling, disabling, deleting or moving proxies in batches

Calling the API ​

Send the key in the request header:

bash
curl -H "Authorization: Bearer pdx_xxxxxxxx" http://<Podux address>:8090/api/metrics

API keys only work on these endpoints:

EndpointAccessDescription
GET /api/metricsRead-onlyMetrics in the Prometheus text format, see below
GET /api/dashboard/statsRead-onlyDashboard stats: server, proxy and visitor counts, highest latency, today's traffic
GET /api/proxies/statusRead-onlyTraffic and external reachability per proxy; add ?serverId= for a single server
POST /api/frpc/launchRead and writeStarts a server's frpc; body {"id": "<server ID>"}
POST /api/frpc/terminateRead and writeStops a server's frpc; same body
POST /api/frpc/reloadRead and writeReloads a server's configuration; same body
POST /api/proxies/batchRead and writeBatch actions on proxies; body {"ids": [...], "action": "enable"} with action one of enable, disable, delete, move (add "serverId" to move)

A read-only key gets 403 from the read-and-write endpoints.

Security boundary

An API key is not a user session. It cannot sign in to the UI, reach the PocketBase collection API, manage API keys, change settings, or create or restore backups, so it cannot read sensitive settings such as frps tokens or notification credentials. Even so, a read-and-write key can stop tunnels and delete proxies: keep it like a password, and create a read-only key for scraping metrics.

Podux itself serves plain HTTP, so keys travel in clear text. When calling it from other machines, put it behind an HTTPS reverse proxy or keep it on your local network.

Prometheus ​

Add a scrape job to the Prometheus configuration, with a read-only key as credentials:

yaml
scrape_configs:
  - job_name: podux
    metrics_path: /api/metrics
    scheme: http
    authorization:
      credentials: pdx_xxxxxxxx
    static_configs:
      - targets: ["192.168.1.10:8090"]

The bottom of Settings → API shows this configuration for the address you are using, ready to copy.

Metrics ​

All metrics are gauges. Server metrics have server_id and server labels; proxy metrics have proxy_id, proxy, type, server_id and server.

MetricDescription
podux_info{version}Podux version; always 1
podux_server_runningWhether frpc is running for the server (1/0)
podux_server_reachableWhether the last latency probe reached frps
podux_server_latency_millisecondsLatency of the last successful probe
podux_proxy_enabledWhether the proxy is enabled
podux_proxy_onlineWhether frpc reports the proxy as started
podux_proxy_reachableWhether the last external probe reached the proxy, see external reachability probes

Servers with an frps dashboard configured also have these. frps counts today's traffic and resets it daily:

MetricDescription
podux_server_frps_connectionsCurrent connections on frps
podux_server_frps_clientsClients connected to frps
podux_server_today_traffic_in_bytes / ..._out_bytesTraffic into / out of frps today
podux_proxy_connectionsCurrent connections to the proxy
podux_proxy_today_traffic_in_bytes / ..._out_bytesTraffic into / out of the proxy today

Metrics without data yet are left out; for example, there is no podux_proxy_reachable until the first probe.

frps dashboard data is cached for 15 seconds, so a scrape interval of 15 seconds or more is enough.

Alert Example ​

yaml
groups:
  - name: podux
    rules:
      - alert: PoduxProxyOffline
        expr: podux_proxy_enabled == 1 and podux_proxy_online == 0
        for: 2m
        annotations:
          summary: "Proxy {{ $labels.proxy }} on {{ $labels.server }} is offline"

Podux's own alerts already cover the common cases; with Prometheus, you can keep all alerting in Alertmanager instead.

Released under the Apache 2.0 License.