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_LOGnames 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,stateand 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_failedor ofdrawbridge.deniedwithreasongroupfor oneuser. - Audit with
drawbridge.revoked: it shows that a revoked session was really refused, and when. - Count
drawbridge.deniedbyreasonto spot a misconfigured rule (a jump indeny_ruleafter a deploy).