Observability¶
who counts what happens as Micrometer meters and times its own work as Micrometer observations,
so sign-ins, failures and sign-in emails show up on the dashboards and alerts you already have.
There is nothing to configure in who: add Spring Boot Actuator (or any MeterRegistry and
ObservationRegistry beans) and it starts.
To see it all working, run the observability example: who's meters, traces and logs in Grafana, with a dashboard, a traffic generator, and a page whose every request links to its trace.
What Spring Security already measures¶
Spring Security times every authentication: with an ObservationRegistry it records
spring.security.authentications for email-link, email-code, passkey and API-key sign-ins, and
its filter-chain observations cover JWT requests. who does not time sign-ins a second time.
What Spring cannot see is why a sign-in failed: by design every failure answers with the same
401. who's meters add that reason.
Meters¶
Counters, registered when the application has a MeterRegistry. Tag values are who's enum
constants in lower case with _ replaced by -. No address, identity id, credential id, label
or role is ever a tag. A series appears the first time it counts.
| Meter | Counts | Tags |
|---|---|---|
who.sign-ins |
Sign-in attempts | method, outcome, reason |
who.sign-in.emails |
Sign-in email requests | outcome |
who.sign-outs |
Sign-outs of who sessions | none |
who.human-checks |
Requests to who's human-checked endpoints | check, action, outcome (passed, refused, error); a vendor outage counts as refused, or passed with fail-open, since Turnstile handles it itself |
who.sessions.ended |
Sessions who ended | reason |
who.sessions.purged |
Ended or abandoned session records deleted | none |
who.credentials.added |
Credentials added | kind |
who.credentials.revoked |
Credentials revoked | kind |
Tag values:
method:email-link,email-code,passkey,api-key,jwt,oidc.outcomeonwho.sign-ins:successorfailure.reasononwho.sign-ins:nonefor a success; for a failure,malformed,invalid-link,no-live-code,wrong-code,code-already-used,invalid-assertion,unknown-key,missing-claims,unknown-credential,inactive-identity,sign-up-refusedorprovider-error.outcomeonwho.sign-in.emails:sent,unknown-address,inactive-identity,resend-suppressed,send-failed.reasononwho.sessions.ended:identity-inactive,credential-revoked,revoked.kind:email,passkey,api-key,federated,other.
Successes count only real sign-ins (email link, email code, passkey, identity provider). API keys and JWTs
authenticate every request, so they count only failures here; Spring Security's
spring.security.authentications counts every authenticated API-key request. who.sign-ins
has at most 76 series.
The meters are built from who's events, so they count exactly what the events report.
Observations¶
| Observation | Spans | Key |
|---|---|---|
who.principal.resolve (who resolve principal) |
Loading a credential's identity and its permissions | outcome: resolved, inactive, not-linked, no-identity, or error when the lookup throws (a database fault) |
who.sign-in.email.issue (who issue sign-in email) |
Looking up the address, storing the code and sending the mail | outcome: as who.sign-in.emails, or error if issuing throws |
With Actuator each observation is a timer of the same name, and a span when tracing is on. The resolution runs on every authenticated request (sessions, API keys and JWTs re-resolve the identity each time), so its timer shows the per-request cost of who's database lookups. When a sign-in email is issued, the resolution span nests inside the issue span.
A failing observation handler never changes who's answer: who logs it at WARN, with the exception class only, and carries on.
Startup log¶
When who builds a security chain, it logs at INFO the sign-in methods that chain accepts, so a
missing jar or a stray who.<module>.enabled=false shows up as soon as the application starts:
who: this chain signs browsers in with email-link, passkey, oidc (github, google) under /who
who: this chain accepts api-key, jwt
Each chain logs its own lines: the browser line comes from PasswordlessConfigurer and names the
endpoint root, and the stateless line from WhoStatelessConfigurer or WhoSecurityConfigurer.
Provider sign-in lists its registration ids. The line names methods only, never a key, secret,
client id or issuer. A method of your own is named by its class unless it overrides name().
who has no Actuator info contributor for this on purpose: it would tell anyone who can read
/actuator/info how the application can be attacked.
Building services yourself¶
The autoconfiguration passes your ObservationRegistry to WhoService and EmailLinkIssuer. If
you construct them yourself, use the constructors that take an ObservationRegistry; the
existing constructors observe nothing.
Meter names, tag keys and values, and observation names are public API, with the same
compatibility rules as events. WhoObservations in who-core is
internal to who and has no compatibility promise.
Example alerts¶
PromQL, with the Prometheus registry's naming:
# Someone is guessing sign-in codes
sum(rate(who_sign_ins_total{outcome="failure", reason="wrong-code"}[5m])) > 1
# Sign-in emails are not going out
sum(rate(who_sign_in_emails_total{outcome="send-failed"}[15m])) > 0
# Someone is trying API keys
sum(rate(who_sign_ins_total{method="api-key", reason="unknown-key"}[5m])) > 1
# A bot is at the email endpoints
sum(rate(who_human_checks_total{outcome="refused"}[5m])) > 1
# The human check passes nobody: a broken site key, or the vendor is down
# (or vector(0): with nothing ever passed, the passed series does not exist)
(sum(rate(who_human_checks_total{outcome="passed"}[15m])) or vector(0)) == 0
and sum(rate(who_human_checks_total[15m])) > 0
Protect the metrics endpoint¶
The meters reveal sign-in volume and failure patterns. Do not expose /actuator/prometheus or
/actuator/metrics without authentication.