Skip to content
Menu

Log events#

This page documents the event log: one JSON line for each sign-in, failed sign-in, sign-out, refusal and revoked session, the fields on each line, and what is never written.

Where it goes#

The gateway writes two logs. The access log (%h %l %u %t "%m %U %H" %>s %b, no query strings) covers every request. The event log covers only the requests worth an alert or an audit, one JSON object per line:

  • DRAWBRIDGE_EVENT_LOG names the file. The default is /dev/stdout, next to the access log, and a line there is told apart by starting with {"v":1,. Point it at a file on a mounted volume to keep the events apart for a log shipper.
  • Apache writes the line itself, after the answer is sent, so a slow log never slows a request.
  • An ordinary request (a public page, a proxied page for a signed-in person, the redirect to sign in) writes nothing.

A line#

{"v":1,"event":"drawbridge.denied","time":"2026-11-07T15:04:05Z","host":"app1.apps.wayne.edu","path":"/admin/reports/q3","status":403,"user":"ab1234","rule":"login","reason":"group","client":"(client address)"}
Field What it holds
v The format version, 1. It changes only when a field changes meaning; new fields may be added at the end.
event One of the events below.
time When the gateway answered, UTC, to the second (YYYY-MM-DDTHH:MM:SSZ).
host The host the request named, lower case.
path The request path only, never the query string. - when it has characters outside the URL path set.
status The HTTP status the gateway answered with, a number.
user The signed-in subject (the value of oidc.user_claim, the same name the access log's %u shows), or -.
rule The protection of the rule that decided: public, login, api, deny, or - before any rule applied.
reason Why, for a refusal or a failed sign-in (below); - otherwise.
client The client address, after the trusted proxies (DRAWBRIDGE_TRUSTED_PROXIES) are taken off.

Every value is a plain string from a small safe set of characters (or -), so a line is always valid JSON and a value can never break out of its field.

Events and reasons#

event When reason
drawbridge.signin The provider sent the person back with a code and the gateway made a session. -
drawbridge.signin_failed The callback did not end in a session. provider_error (the provider answered with an error, for example the person cancelled), callback_refused (a bad, replayed or expired state or code)
drawbridge.signout The ?logout= link ended a gateway session. -
drawbridge.denied The gateway refused the request. group (signed in, holds none of the rule's groups), deny_rule (a deny path or a deny default), unauthenticated (an api path without a session, 401), unsafe_path (the guard's 400), unknown_host (no app has the host), forbidden (another 403), bad_signout (a ?logout= link that was refused)
drawbridge.revoked A session ended by drawbridge revoke was used. The browser is sent to sign out; an api caller gets 401. revoked

What is never written#

  • No query string: the provider's code, state and error text, and any app parameter, stay out.
  • No cookie, no session ID, no ID token, access token or refresh token, and no claim but the subject.
  • No header the client sent.

The rig checks the format, each event and these rules against the real gateway (tests/E2E/EventLogTest.php), and tests/Unit/EventLogFormatTest.php keeps this page and the rendered LogFormat in step.

Using it#

  • Alert on a burst of drawbridge.signin_failed or of drawbridge.denied with reason group for one user.
  • Audit with drawbridge.revoked: it shows that a revoked session was really refused, and when.
  • Count drawbridge.denied by reason to spot a misconfigured rule (a jump in deny_rule after a deploy).