Statistics API

The statistics API reports message traffic, connection activity, authentication outcomes, and errors for an individual node. It is available on both the main HTTPS listener and the console listener, and requires an administrator session. The console uses this API to render its charts.

History is a local append-only log on that node. It is not in the account database, and a cluster does not add the nodes together. The directory is {stats_history_dir, Dir} when that value is a non-empty string. Otherwise it is statistics/ inside the keystore, or keys/statistics when no keystore is set. Each node writes under a subdirectory named by the hex SHA-256 of its node name. Keep history for {stats_retention_seconds, N}, an integer from 60 to 604800. The default is 86400, one day. Any other value stops the statistics store at startup.

Chart catalog

GET /auth/admin/statistics/charts returns the charts you can request. schema_version is 1. scope is node. traffic_scopes are main and console. max_points is 2000. max_range_seconds is 86400. steps are 1, 5, 10, 30, 60, 300, 900, and 3600.

Filter method, on logins and account events, is password, oauth, enrollment, recovery, session, admin, legacy, or none. Filter kind is tls, protocol, decode, handler, delivery, authorization, login, logout, session_refresh, session_revoke, password_reset, otp_recovery, provider_link, provider_unlink, account_create, account_disable, account_enable, account_remove, or unlock. Use kind on errors and on account events.

Query a time range

GET /auth/admin/statistics/charts/CHART needs a range. With no range, mesgd returns 400 and {"error":"invalid_statistics_range"}.

from, to, and step are digits only, at most 12 digits. scope, traffic, method, and kind are strings. An unknown parameter, a duplicate parameter, or a query string over 2048 bytes is 400.

mesgd then requires all of the following. A failure is the same 400:

• chart is one of the six ids.
• from is at least 0, to is greater than from, and both are divisible by step.
• step is one of the catalog steps. The default step is 60.
• to - from is at most 86400 seconds and at most 2000 points.
• to is not more than one step ahead of the node clock.
• scope is omitted or node.
• traffic is omitted, main, or console. The default is main.
• method is present only on logins_per_second and auth_events_per_second, and only with a catalog method.
• kind is present only on errors_per_second and auth_events_per_second, and only with a catalog kind.

A successful body has schema_version 1, the chart, unit, node name, scope node, traffic, from, to, step, the filters you set, generated_at, series, buckets, and availability. availability is complete when every bucket is complete, and partial otherwise.

Read a bucket as a slice of the range. It has start, duration, covered_seconds, complete, final, counts, values, and observed_counts. final means the bucket ended at least 60 seconds ago. That alone does not make it complete. When the bucket is complete, values are the counts divided by duration. When it is incomplete, counts and values are null, and observed_counts still reports what mesgd saw. Treat an incomplete hour, or a second with more than one collector epoch, as a gap in coverage rather than as zero traffic.