What Should a Transit Search Log Record?
From the earlier reference collection. Read the current software blog.
Structured search logs should capture timing, schedule revision, and failure class while avoiding unnecessary details that could expose a rider’s query or travel pattern.
Log the operation, not a dossier
A failed search needs enough context to diagnose software behavior, not a complete account of a person’s movement. Record an operation identifier, start time, duration, outcome, and the schedule revision used. A request can often be debugged without retaining exact origin, destination, or travel time in a general-purpose log.
If query details are needed for a short investigation, establish a limited retention period and restrict access. Consider recording coarse categories or a nonreversible diagnostic identifier instead of raw stop names. Do not assume hashing makes a small set of possible locations private; likely values can be guessed.
Capture useful timing and source context
Include which schedule snapshot or source version was queried, whether it was current according to the system’s policy, and how long the search took. These fields help separate slow computation from an old or incomplete dataset. A retrieval timestamp and a schedule revision are complementary: one tells when you fetched; the other identifies the content used.
For a search with two legs, record counts at key stages, such as candidate trips found and candidates removed by transfer validation. Counts can reveal that a query returned nothing because of an empty index or a stricter connection rule, without storing every candidate route.
Make failures actionable
Use a controlled outcome vocabulary: no itinerary found, invalid input, schedule unavailable, timeout, or internal error. Distinguish a valid empty answer from a failed search. Attach a stable error code and a short sanitized message; avoid including credentials, full request headers, or raw exception dumps that may contain user input.
A useful log event might contain an operation ID, elapsed milliseconds, source revision, result class, and a count of candidate legs. An operator can correlate it with a trace or restricted diagnostic record if deeper inspection is needed. Keep metrics aggregated so a dashboard can show failure rates without exposing individual requests.
Review the user impact
Set alerts around patterns that matter: repeated timeouts, a missing active schedule revision, or a sudden increase in internal errors. A single “no itinerary found” may be normal; alerting on each empty result creates noise and risks encouraging collection of more query detail than necessary.
A schedule lookup is a concrete workflow for deciding what system health means: a search should use a known schedule snapshot and explain when no result is available. Use the public page as context for the user task, not as evidence about its logging or data pipeline.