Telemetry Export: customer documentation and experimental launch post - #404
Merged
Merged
Conversation
Adds docs/self-service/telemetry-export.md under the Observability category, and a blog post announcing it. The documentation leads with what a customer has to decide before they can use it: that the endpoint must be public HTTPS with a publicly signed certificate, that logs and events are all or nothing, and that exported events carry end-user IP addresses and user IDs in the clear. That last one is the fact most likely to matter to someone's legal review and least likely to be discovered by trying it. It also states the delivery semantics honestly rather than optimistically: a brief outage loses nothing, a long outage eventually drops the oldest records, disabling export discards what is queued, and we cannot see whether a backend accepted a record after we delivered it. The Delivery status panel is marked unimplemented, because it renders an em dash regardless and would otherwise generate support tickets. The blog post explains the two decisions a reader cannot infer from "we support OTLP" -- that events are rebuilt into flat attributes rather than forwarded as log text, and that event severity is derived because Keycloak logs a failed login at INFO, which makes the most useful filter anyone writes match nothing. Both carry the experimental caveat with specifics: which parts may change incompatibly, and what is not supported yet. Note: `pnpm run build` fails in this checkout before reading any content -- "Cannot mix different versions of joi schemas" during plugin option validation. It fails identically on a pristine main, so it is a node_modules problem here rather than anything in this change. Links and sidebar ids were checked by script instead.
Deploying phasetwo-docs with
|
| Latest commit: |
cd5dddf
|
| Status: | ✅ Deploy successful! |
| Preview URL: | https://595f0e8a.phasetwo-docs.pages.dev |
| Branch Preview URL: | https://xgp-telemetry-export-experim.phasetwo-docs.pages.dev |
pnzrr
approved these changes
Sep 18, 2026
…experimental-launch
The docs and the announcement were written before the tier decision and read as though any dedicated cluster could use it. On Starter and Premium the page now shows an upgrade note and the API returns 403, so a customer following these instructions would have hit a wall with no warning. Changed in the four places a reader could form the wrong expectation: the availability line and requirements list on the docs page, the two cross-links from Observability and Logs, and the announcement -- its description, its opening sentence, an Enterprise admonition next to the setup screenshot, and the limitations list. The upgrade sentence matches the one custom-domains.md already uses for app association files: what keeps working, what upgrading adds, and where to change plan. No reason to invent a second phrasing for the same situation. Kept the "not enabled on every account" caveat and made it "even on Enterprise", because both gates are real -- the entitlement and the feature flag are separate and a customer can be entitled and still not see the page. Also added an invitation for Starter and Premium customers to ask anyway. The tier boundary is a product decision we may revisit, and the use cases we hear are the input to that. Not changed: the generated API reference under api/management/. Its vendored status codes for cluster.telemetryExport.update are 200/400/401/503 with no 403. That comes from openapi-management.yaml, which is vendored from the control plane, so it corrects itself on the next re-vendor after phasetwo-keycloak#744 ships. Hand-editing generated files would be undone by that run.
Member
Author
|
Updated for the Enterprise tier decision — PR description rewritten to match. One item that needs a follow-up rather than a fix here: the generated API reference from #405 lists |
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
2 participants
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.
Both documents now say Telemetry Export is Enterprise, matching the enforcement in p2-inc/phasetwo-keycloak#744.
They were written before the tier decision and read as though any dedicated cluster could use it. On Starter and Premium the page now shows an upgrade note and the API returns
403— a customer following the old instructions would have hit a wall with no warning.Changed in the four places a reader could form the wrong expectation
403). Added to the limitations list too.:::info Available on Enterpriseadmonition beside the setup screenshot, and the limitations list.The upgrade sentence reuses the phrasing
custom-domains.mdalready uses for app association files — what keeps working, what upgrading adds, where to change plan. No reason to invent a second wording for the same situation.Two judgement calls
Kept "not enabled on every account", now "even on Enterprise." Both gates are real and independent: a customer can be entitled and still not see the page while the
telemetryExportfeature flag is internal-only. Saying only "Enterprise" would set up a support ticket from an Enterprise customer who can't find it.Added an invitation for Starter and Premium customers to ask anyway. The tier boundary is a product decision that may get revisited, and the use cases we hear are the input to that. Say the word if you'd rather not invite it.
One thing this PR deliberately does not fix
The generated API reference merged in #405 lists 200/400/401/503 for
cluster.telemetryExport.update— no 403. That comes fromopenapi-management.yaml, vendored from the control plane, so it corrects itself on the next re-vendor after #744 ships. Hand-editing generated files would just be undone by that run.Worth tracking so the reference doesn't sit wrong indefinitely.
Also in this branch
Merged current
main, which brought in #393 and #405. Someone added a setup screenshot to the branch (5b14d35) — kept, and the new Enterprise admonition sits directly above it.Links, doc ids, blog slugs and sidebar entries validated by script. The site build still cannot run in my checkout (
Cannot mix different versions of joi schemas, fails identically on a pristinemain), so CI remains the gate.