Repository navigation
feat(tracing): boot journey + process device for out-of-request calls - #116
Merged
Merged
Conversation
added 2 commits
October 21, 2026 11:27
Every SDK call is a user request — human or agent (ruling, campus-api-python#114) — so calls outside any request context (startup, background threads) now carry: - X-Journey-ID: one uid-journey-… per process boot, lazily minted on first use, fixed for the process's lifetime (format matches campus.common.utils.uid.generate_category_uid without importing the server package). - X-Journey-Name: only when the app names the journey (set_process_journey(name=...)), riding the campus#952 adoption. - X-Campus-Device: the process device, defaulting to RAILWAY_DEPLOYMENT_ID, so boot spans attribute to the deploy that produced them. Strict MVP scope (ruled): in-request calls never inherit the boot journey — a journeyed request forwards its own, a journey-less request stays unjourneyed (the trace waterfall already correlates it) — and the process device only fills the gap when the request stashed none. Opt-out, both ruled in: CAMPUS_PROCESS_JOURNEY=off (also false/0/no; a non-off value pins an explicit id) for pytest/CI, and disable_process_journey() in code; set_process_journey() re-enables and set_process_device() overrides. Fixes #114.
The in_request flag broke type narrowing: pyright could not connect the bool to flask being non-None inside the request branch. Branch on flask None-ness directly and return from each path.
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
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.
Fixes #114 (all four decisions settled in the issue, user-ruled 2026-10-21, recommendations accepted).
What
Every SDK call is a user request — human or agent — so calls outside any request context (startup vault fetches, background threads) now correlate instead of landing as anonymous single-span traces:
uid-journey-…per process boot, lazily minted on first out-of-request use and fixed for the process's lifetime (format matchesgenerate_category_uid("journey")— replicated, not imported).X-Journey-Name(campus#952 adoption) when the app callsset_process_journey(name="campus.api.boot"); auto-minted journeys are unnamed until then.X-Campus-Devicedefaults toRAILWAY_DEPLOYMENT_ID, so boot spans attribute to the deploy that produced them.Strict MVP scope (ruled): in-request calls never inherit the boot journey — a journeyed request forwards its own (precedence pinned by test), a journey-less request stays unjourneyed since the trace waterfall already correlates the chain. The process device only gap-fills when a request stashed no device of its own.
Opt-out, both forms (ruled):
CAMPUS_PROCESS_JOURNEY=off(alsofalse/0/no) for pytest/CI with zero code;disable_process_journey()for embedded hosts. A non-off env value pins an explicit id.set_process_journey()re-enables after either;set_process_device()overrides the env default.Zero server-side changes: the campus journeys middleware already adopts header-minted journeys, and #952 (merged) adopts the name.
Testing
TestProcessJourney(15 tests): mint-once per boot, explicit id/name, env off + disable API + re-enable, env-pinned id, device from Railway env + override, strict-MVP in-request non-inheritance, journeyed-request precedence, device gap-fill vs stashed-device-wins, id-format lockstep._reset_process_journey()test hook keeps the module state isolated between tests.