Observability

AuthKit emits a canonical set of metrics from both the server (IdP) and the client kit, through a small MetricsRecorder seam that wires to OpenTelemetry when available — and always keeps an in-memory snapshot for the built-in JSON / dashboard routes.

Enabling metrics (server)

Metrics are off until you turn them on in observability:

config/authkit.ts

defineConfig({
  // ...
  observability: {
    metrics: true, // create the recorder and wire provider events
    jsonRoutes: true, // GET /authkit/metrics  → snapshot JSON
    dashboard: true, // GET /authkit/dashboard → tiny HTML table (auto-refresh)
  },
});

Field	Type	Default	Notes
`metrics`	`boolean?`	`false`	Builds the `OtelRecorder` and binds `authkit.metrics`; without it the recorder is a `NoopRecorder`.
`jsonRoutes`	`boolean?`	`false`	Mounts `GET /authkit/metrics` returning the in-memory snapshot.
`dashboard`	`boolean?`	`false`	Mounts `GET /authkit/dashboard`, a minimal auto-refreshing HTML table.

The metric names

The canonical names live in AUTHKIT_METRICS (from @adonis-agora/authkit-core).

Server (IdP)

Wired from real oidc-provider v9 events:

Constant	Name	Kind	Meaning
`loginSuccess`	`authkit.login.success`	counter	A grant succeeded (`grant.success`).
`loginFailure`	`authkit.login.failure`	counter	A provider error occurred (`server_error`).
`tokenIssued`	`authkit.token.issued`	counter	An access token was issued/saved (`access_token.issued` / `.saved`).
`refreshRotated`	`authkit.refresh.rotated`	counter	A refresh token was saved/rotated (`refresh_token.saved`).
`grantRevoked`	`authkit.grant.revoked`	counter	A grant was revoked (`grant.revoked`).

Client (RP)

Recorded by the Authenticator while resolving an identity:

Constant	Name	Kind	Meaning
`resolveDuration`	`authkit.resolve.duration`	histogram	Wall-clock (ms) to resolve an identity — includes opaque-resolver introspection latency.
`resolveErrors`	`authkit.resolve.errors`	counter	The resolver threw while resolving.

Reserved names

These names are part of the contract for future use (no emit site yet): sessionsActive (authkit.sessions.active), passwordHashDuration (authkit.password.hash.duration), jwksRefresh (authkit.jwks.refresh), tokenRefresh (authkit.token.refresh).

The MetricsRecorder seam

A recorder is just two methods plus a snapshot:

interface MetricsRecorder {
  increment(
    name: AuthkitMetricName,
    attributes?: Record<string, string | number>,
  ): void;
  record(
    name: AuthkitMetricName,
    value: number,
    attributes?: Record<string, string | number>,
  ): void;
  snapshot(): MetricsSnapshot;
}

OtelRecorder (server and client) best-effort imports @opentelemetry/api. If it's installed, counters/histograms are emitted to your configured OTel meter; if not, it silently stays in-memory-only. It always aggregates into an InMemorySnapshot.
NoopRecorder is used when metrics is off.

InMemorySnapshot and NoopRecorder are exported from @adonis-agora/authkit-core, so you can build a custom recorder over the same contract. The snapshot shape:

interface MetricsSnapshot {
  counters: Record<string, number>;
  histograms: Record<
    string,
    { count: number; sum: number; min: number; max: number }
  >;
  updatedAt: number;
}

To actually export to a backend (Prometheus/OTLP), install @opentelemetry/api plus an OTel SDK and meter provider in your app. AuthKit only calls the API surface; the SDK wiring (readers, exporters) is yours.

Sample Grafana dashboard

The board below wires the key metrics to a Prometheus datasource (metric names are shown in their Prometheus form — dots become underscores and counters gain _total). Import it from /grafana-dashboard.json or paste the JSON:

{
  "title": "AuthKit — Auth Overview",
  "uid": "authkit-overview",
  "tags": ["authkit", "oidc", "auth"],
  "templating": {
    "list": [
      {
        "name": "DS_PROMETHEUS",
        "label": "Prometheus",
        "query": "prometheus",
        "type": "datasource"
      }
    ]
  },
  "panels": [
    {
      "title": "Login success vs failure rate",
      "type": "timeseries",
      "gridPos": { "h": 8, "w": 12, "x": 0, "y": 0 },
      "targets": [
        {
          "expr": "sum(rate(authkit_login_success_total[5m]))",
          "legendFormat": "login success/s"
        },
        {
          "expr": "sum(rate(authkit_login_failure_total[5m]))",
          "legendFormat": "login failure/s"
        }
      ]
    },
    {
      "title": "Login failure ratio",
      "type": "stat",
      "gridPos": { "h": 8, "w": 12, "x": 12, "y": 0 },
      "targets": [
        {
          "expr": "sum(rate(authkit_login_failure_total[5m])) / clamp_min(sum(rate(authkit_login_success_total[5m])) + sum(rate(authkit_login_failure_total[5m])), 1)"
        }
      ]
    },
    {
      "title": "Identity resolve duration (incl. introspection latency)",
      "type": "timeseries",
      "gridPos": { "h": 8, "w": 12, "x": 0, "y": 8 },
      "targets": [
        {
          "expr": "histogram_quantile(0.95, sum(rate(authkit_resolve_duration_bucket[5m])) by (le))",
          "legendFormat": "resolve p95"
        },
        {
          "expr": "histogram_quantile(0.50, sum(rate(authkit_resolve_duration_bucket[5m])) by (le))",
          "legendFormat": "resolve p50"
        }
      ]
    },
    {
      "title": "Tokens, rotation, revocation & resolve errors",
      "type": "timeseries",
      "gridPos": { "h": 8, "w": 12, "x": 12, "y": 8 },
      "targets": [
        {
          "expr": "sum(rate(authkit_token_issued_total[5m]))",
          "legendFormat": "tokens issued/s"
        },
        {
          "expr": "sum(rate(authkit_refresh_rotated_total[5m]))",
          "legendFormat": "refresh rotated/s"
        },
        {
          "expr": "sum(rate(authkit_grant_revoked_total[5m]))",
          "legendFormat": "grants revoked/s"
        },
        {
          "expr": "sum(rate(authkit_resolve_errors_total[5m]))",
          "legendFormat": "resolve errors/s"
        }
      ]
    }
  ]
}

The exact Prometheus metric names depend on your OTel → Prometheus exporter's naming conventions (unit suffixes, _total). Adjust the PromQL expr to match what your exporter actually publishes for the authkit.* instruments.

Telescope & the Agora diagnostics bus

Independently of OTel metrics, AuthKit republishes every audit event onto the Agora diagnostics bus as agora:authkit:<AuditEventType> (e.g. agora:authkit:login.success, agora:authkit:mfa.enabled, agora:authkit:account.locked, agora:authkit:pat.issued). This is wired automatically by the audit sink — it is a best-effort, fire-and-forget republish that never touches the request path and is a no-op when nothing is subscribed.

The baseline works without any extra setup

If you have @adonis-agora/telescope installed, its generic diagnostics watcher already records each of these events as a diagnostic entry tagged lib:authkit — no AuthKit-specific configuration required. You can browse them in Telescope under the diagnostics entry type out of the box.

Adding the dedicated "Security" dashboard

For a purpose-built auth view, register AuthKit's Telescope extension. It contributes a navigable Auth entry type and a Security dashboard that aggregates the recorded agora:authkit:* entries: login success rate, successful/failed logins over time, MFA & passkey enrollments, account lockouts, and PAT / impersonation activity.

config/telescope.ts

import { defineConfig } from "@adonis-agora/telescope";
import { defineAuthkitTelescopeExtension } from "@adonis-agora/authkit-server/telescope";

export default defineConfig({
  extensions: [defineAuthkitTelescopeExtension()],
});

You can widen or narrow the rolling window the stat / gauge / breakdown panels aggregate over (default 24h):

defineAuthkitTelescopeExtension({ windowMs: 7 * 24 * 60 * 60 * 1000 });

@adonis-agora/telescope is an optional peer dependency of @adonis-agora/authkit-server. The extension lives on the isolated @adonis-agora/authkit-server/telescope subpath, so the main entrypoint never imports Telescope — and the baseline (events on the bus) keeps working whether or not you register the extension.

Enabling metrics (server)Copy Anchor Link

The metric namesCopy Anchor Link

Server (IdP)Copy Anchor Link

Client (RP)Copy Anchor Link

Reserved namesCopy Anchor Link

The MetricsRecorder seamCopy Anchor Link

Sample Grafana dashboardCopy Anchor Link

Telescope & the Agora diagnostics busCopy Anchor Link

The baseline works without any extra setupCopy Anchor Link

Adding the dedicated "Security" dashboardCopy Anchor Link

On this page