From 5a6a6b9cc49533b80aaba8be8f8c37e60e2a36fe Mon Sep 17 00:00:00 2001 From: Dustin Byrne Date: Wed, 27 May 2026 12:59:40 -0400 Subject: [PATCH 1/3] docs: add Java request context docs --- contents/docs/libraries/java/index.mdx | 55 ++++++++++++++++++++++++++ 1 file changed, 55 insertions(+) diff --git a/contents/docs/libraries/java/index.mdx b/contents/docs/libraries/java/index.mdx index 80d80da56bb3..0d0194da504b 100644 --- a/contents/docs/libraries/java/index.mdx +++ b/contents/docs/libraries/java/index.mdx @@ -117,6 +117,61 @@ posthog.capture( ); ``` +## Request context + +Use request context to apply a distinct ID, session ID, and common properties to all captures inside a request scope. This is useful when connecting frontend activity to backend events, session replay, error tracking, and feature flag evaluation. + +```java +Map headers = new HashMap<>(); +headers.put( + PostHogRequestContext.DISTINCT_ID_HEADER, + request.getHeader(PostHogRequestContext.DISTINCT_ID_HEADER) +); +headers.put( + PostHogRequestContext.SESSION_ID_HEADER, + request.getHeader(PostHogRequestContext.SESSION_ID_HEADER) +); + +Map properties = new HashMap<>(); +properties.put("$current_url", request.getRequestURL().toString()); +properties.put("$request_method", request.getMethod()); +properties.put("$request_path", request.getRequestURI()); +properties.put("$user_agent", request.getHeader("User-Agent")); +properties.put("$ip", request.getRemoteAddr()); + +PostHogRequestContextData context = PostHogRequestContext.fromHeaders( + headers, + true, + properties +); + +try (PostHogRequestContext.Scope ignored = PostHogRequestContext.beginScope(context, true)) { + posthog.capture("backend_event"); + posthog.captureException(error); + + PostHogFeatureFlagEvaluations flags = posthog.evaluateFlags(); + if (flags.isEnabled("new-checkout")) { + // Do something differently for this request + } +} +``` + +`fromHeaders()` reads `X-PostHog-Distinct-Id` and `X-PostHog-Session-Id`. Captures inside the scope use the context distinct ID when you don't pass one explicitly. If no distinct ID is available, captures are sent as [personless events](/docs/data/anonymous-vs-identified-events) with an auto-generated UUID. `evaluateFlags()` returns an empty snapshot when no distinct ID is available. + +Pass `false` as the second argument to `fromHeaders()` to ignore client-supplied tracing headers while still attaching request metadata: + +```java +PostHogRequestContextData context = PostHogRequestContext.fromHeaders( + headers, + false, + properties +); +``` + +Tracing headers are client-controlled analytics context, not authentication or authorization context. For security-sensitive server branching, pass an authenticated distinct ID explicitly. + +Request context is stored in a `ThreadLocal`. It applies to work on the same thread while the scope is active. If your framework moves work across threads, propagate the context explicitly in your framework integration. + ## Feature flags import FeatureFlagsLibsIntro from "../_snippets/feature-flags-libs-intro.mdx" From 6775ecd0bd900fae50d9bb5407c9751ef1fa7a14 Mon Sep 17 00:00:00 2001 From: Dustin Byrne Date: Thu, 28 May 2026 09:57:09 -0400 Subject: [PATCH 2/3] Update request context explanations in Java docs Clarified request context usage and security considerations. --- contents/docs/libraries/java/index.mdx | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/contents/docs/libraries/java/index.mdx b/contents/docs/libraries/java/index.mdx index 0d0194da504b..c9454a91867e 100644 --- a/contents/docs/libraries/java/index.mdx +++ b/contents/docs/libraries/java/index.mdx @@ -119,7 +119,7 @@ posthog.capture( ## Request context -Use request context to apply a distinct ID, session ID, and common properties to all captures inside a request scope. This is useful when connecting frontend activity to backend events, session replay, error tracking, and feature flag evaluation. +Use request context to apply a distinct ID, session ID, and common properties to all captures inside a request scope. This allows you to associate frontend user activity to backend events, session replay, error tracking, and feature flag evaluation. ```java Map headers = new HashMap<>(); @@ -168,7 +168,7 @@ PostHogRequestContextData context = PostHogRequestContext.fromHeaders( ); ``` -Tracing headers are client-controlled analytics context, not authentication or authorization context. For security-sensitive server branching, pass an authenticated distinct ID explicitly. +Tracing headers are client-controlled analytics context, not authentication or authorization context. If an event should be server-authoritative, pass an authenticated distinct ID explicitly. Request context is stored in a `ThreadLocal`. It applies to work on the same thread while the scope is active. If your framework moves work across threads, propagate the context explicitly in your framework integration. From c9de1f81568c3e15aaa20c8198a692d434c94052 Mon Sep 17 00:00:00 2001 From: Dustin Byrne Date: Thu, 28 May 2026 09:57:49 -0400 Subject: [PATCH 3/3] Update wording in request context section Corrected the wording from 'to' to 'with' for clarity. --- contents/docs/libraries/java/index.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/contents/docs/libraries/java/index.mdx b/contents/docs/libraries/java/index.mdx index c9454a91867e..8a0ca0c767f4 100644 --- a/contents/docs/libraries/java/index.mdx +++ b/contents/docs/libraries/java/index.mdx @@ -119,7 +119,7 @@ posthog.capture( ## Request context -Use request context to apply a distinct ID, session ID, and common properties to all captures inside a request scope. This allows you to associate frontend user activity to backend events, session replay, error tracking, and feature flag evaluation. +Use request context to apply a distinct ID, session ID, and common properties to all captures inside a request scope. This allows you to associate frontend user activity with backend events, session replay, error tracking, and feature flag evaluation. ```java Map headers = new HashMap<>();