Repository navigation
docs: document observability, frontend errors and the mail API - #12
Merged
Merged
Conversation
Refreshing the snapshot surfaced eleven undocumented paths: the frontend error endpoints, and the whole admin mail API, which had never been written up. Documents all of them, plus the OpenTelemetry settings, and carries across the parts a reader cannot recover from a schema: Why the OTLP endpoint is the seam — no application code imports a vendor SDK, so pointing it elsewhere is the entire change needed to use a different backend. That the user agent is reduced to a family and major version rather than stored, and that the reduction is also a filter. That frontend errors are grouped by message rather than by stack, because the same fault reached from two routes produces two stacks and is one bug. That the list shows only what browsers managed to send, so an error that breaks a page badly enough to stop the reporter never arrives — a quiet list is no news, not proof of no errors. For mail: that a uid is only meaningful alongside its folder, that /status is the endpoint to check first when the others return nothing, and that transactional order mail does not pass through this API at all. Closes #11 Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01YY1ekLLeFLkAU2kvdQ8Ey4
PhilippTheServer
force-pushed
the
docs/observability
branch
from
August 26, 2026 16:36
545d5a4 to
95aed61
Compare
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Closes #11 · documents OpenTaberna/fastapi#48, #50, and the mail feature
Refreshing the snapshot surfaced eleven undocumented paths — my two frontend-error
endpoints and, it turned out, the entire admin mail API, which had never been written up:
That the check caught somebody else's undocumented feature is the point of it existing.
What's documented
Frontend errors, including the parts a schema cannot convey: the user agent is reduced
to a family and major version rather than stored, and the reduction doubles as a filter;
grouping is by message rather than stack, because one fault from two routes is one bug; and
the list shows only what browsers managed to send, so a quiet list is no news, not proof
of no errors.
OpenTelemetry settings, and why the endpoint is the seam — no application code imports a
vendor SDK, so pointing it at Datadog is the entire change required.
The admin mail API, all twelve endpoints, read from the running instance rather than
guessed: that a
uidis only meaningful alongside its folder, that/statusis what tocheck first when the others return nothing, and that transactional order mail does not pass
through this API at all.
Verification
Snapshot regenerated from a live instance (43 paths, up from 32).
Merge after OpenTaberna/fastapi#51, since the snapshot includes its endpoints.