docs(OTel): Add backend event catalogue#7286
Merged
Conversation
|
The latest updates on your projects. Learn more about Vercel for GitHub.
2 Skipped Deployments
|
github-actions
Bot
added
api
Codecov Report✅ All modified and coverable lines are covered by tests. Additional details and impacted files@@ Coverage Diff @@
## main #7286 +/- ##
=======================================
Coverage 98.37% 98.37%
=======================================
Files 1366 1366
Lines 51215 51215
=======================================
Hits 50384 50384
Misses 831 831 ☔ View full report in Codecov by Sentry. 🚀 New features to boost your workflow:
|
github-actions
Bot
added
docs
github-actions
Bot
added
feature
![claude[bot]](https://avatars.githubusercontent.com/in/1236702?s=60&v=4){kind=small}
There was a problem hiding this comment.
Code review is billed via overage credits. To resume reviews, an organization admin can raise the monthly limit at claude.ai/admin-settings/claude-code.
Once credits are available, reopen this pull request to trigger a review.
github-actions
Bot
added
docs
emyller
reviewed
Apr 21, 2026
Contributor
emyller
left a comment
emyller
left a comment
There was a problem hiding this comment.
The outcome of this is great.
- Minor non-blocking comments on making wording more consistent.
- I see several attributes in the event catalogue that could be improved, e.g.
environment_idtoenvironment.id,segments.serializers.segment_revision_createdtosegments.segment_revision_created, etc, but I'm not sure this is the right pull request to address these?
Otherwise LGTM!
Member
Author
Yup we'll fix them as needed. |
github-actions
Bot
added
docs
Generates `docs/.../events.md` via `flagsmith docgen events` — the new subcommand shipped in Flagsmith/flagsmith-common#202. The catalogue lists every structured event the backend emits, the log level each is emitted at, its source locations, and the attributes it carries, so product and ops can curate the OTel allowlist without grepping the codebase. Wired into `make generate-docs` so the catalogue stays in sync with the source on the existing pre-commit hook — any PR that adds or changes an emit surfaces the diff in review. Points `flagsmith-common` at the PR branch for smoke testing; switch to a released version before merging. beep boop
Switch back from the branch pin now that the docgen events subcommand is released. beep boop
3.8.1 normalises legacy kebab-case event names to snake_case in the catalogue. beep boop
…Observability category
These four files are operator observability artefacts, not
Flagsmith-tenant settings — they shared a category (Platform
Configuration) with environment-settings.md that was aimed at a
different audience, and monitoring.md already linked cross-tree to
the metrics reference.
Lifts all four under a new `deployment-self-hosting/observability/`
category, updates inbound references in the docs tree and in
`api/{Makefile,README.md}`, updates the parent
`deployment-self-hosting/index.md` to surface the new section, and
adds redirects in `vercel.json` so the old URLs continue to work.
beep boop
…artial The flagsmith-common docgen templates used to emit a full Docusaurus page — frontmatter, intro prose, a section heading, and the catalogue entries. The intro links and framing were necessarily site-specific, which meant upstream owned URLs that only made sense for one consumer and silently broke on docs-tree moves (see Flagsmith/flagsmith-common#210). Switch to an MDX + partial pattern. The `docgen events` and `docgen metrics` commands now write only the catalogue entries to underscore-prefixed partial files (`_events-catalogue.md`, `_metrics-catalogue.md`) — Docusaurus ignores these from routing. The page shell moves to hand-authored `events.mdx` and `metrics.mdx` that import the partials, owning the frontmatter, intro prose, and internal links. Pins flagsmith-common to the PR branch temporarily; swap for a version pin once that lands and releases. beep boop
The generated events catalogue partial is the authoritative list of structured events the backend emits. Routing it through the product team means new events automatically summon product review at PR time. beep boop
The README is imported as a component into the docs site via docs/docs/project-and-community/development.md. Relative paths written from api/README.md's perspective on disk don't resolve when the README is rendered at /project-and-community/development — Docusaurus treats them as literal URL paths, which fail the broken-link check. Use an absolute docs.flagsmith.com URL so the link works both when reading the README on GitHub and when the README is composed into the docs site. beep boop
Move Monitoring and OpenTelemetry above Metrics and Events in the Observability category — the walkthrough pages should come before the references. Flesh out the StatsD section in Monitoring with the env vars that enable Gunicorn's built-in access log metrics, and cross-link it from the Metrics page so readers looking for StatsD metrics find their way there. Add a pointer from the OpenTelemetry logs section to the Events reference. beep boop
Switch back from the PR branch pin now that Flagsmith/flagsmith-common#210 (pure-data docgen templates) has been released. beep boop
Co-authored-by: Evandro Myller <22429+emyller@users.noreply.github.com>
khvn26
force-pushed
the
feat/otel-events-catalogue
branch
from
fbcd069 to
69ebd2a
Compare
github-actions
Bot
added
docs
emyller
approved these changes
Apr 21, 2026
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.
Thanks for submitting a PR! Please check the boxes below:
docs/if required so people know about the feature.Changes
Closes Flagsmith/flagsmith-common#201
Adds a checked-in catalogue of every structured event the backend emits, generated from the source on each pre-commit run. Product and ops can use it to curate the OTel allowlist without grepping the codebase, and any PR that adds, renames, or changes an emit surfaces the diff in review.
flagsmith docgen events, shipped in flagsmith-common 3.8.1, scans structlog call sites and emits per-event markdown entries. The existing pre-commit hook that runsmake -C api generate-docskeeps the catalogue in sync alongside the metrics doc.The metrics and events references live under a new
Observabilitycategory — a sibling toScaling & PerformanceunderDeployment and Self-hosting, alongside the existingMonitoringandOpenTelemetrypages they were already cross-linked to. Old URLs continue to work via redirects indocs/vercel.json.The flagsmith-common docgen templates used to emit a full page — frontmatter, intro prose, section heading, and catalogue entries — with intro links that were necessarily site-specific. flagsmith-common 3.8.2 strips them to pure data. Here, the page shell becomes hand-authored MDX (
events.mdx,metrics.mdx) that imports the generated partial (_events-catalogue.md,_metrics-catalogue.md). Docusaurus ignores underscore-prefixed files from routing, so the partials don't serve on their own._events-catalogue.mdis owned by@flagsmith/flagsmith-productinCODEOWNERSso every catalogue diff auto-requests product review. Validated via GitHub'scodeowners/errorsAPI.Also flesh out the
StatsDsection on the Monitoring page with theSTATSD_HOST/STATSD_PORT/STATSD_PREFIXenv vars and cross-link it from the Metrics page.Follow-ups, not in this PR: GitHub-linked source locations in the catalogue; implicit
bind_contextvarscontext support once the backend uses it.Preview
Docs preview (rebuilds per push):
scaling-and-performance, StatsD env var guide added)scaling-and-performance)Review
Complexity: 2/5. Mostly docs and config changes; no runtime code. Risk is bounded to docs rendering and the generated catalogue. Novelty sits in the MDX-plus-partial pattern and the
entity.actionevent convention — aim is editorial review: does the catalogue read right, do the pages flow, are the env vars accurate.Suggested flow, ~15 min:
Monitoring → OpenTelemetry → Metrics → Events.CODEOWNERSdiff — the_events-catalogue.mdrule puts future catalogue changes in front of product.How did you test this code?
Ran
make -C api generate-docslocally against flagsmith-common 3.8.2. The resulting catalogue captures every domain called out in the issue — code_references, workflows, launch_darkly, feature_health, sentry_change_tracking — plus emits from app_analytics, dynamodb, gitlab, platform_hub, and segments.Verified the Docusaurus build passes locally (
npm run build). Spot-checked that old URLs redirect correctly:/administration-and-security/platform-configuration/{metrics,events}and/deployment-self-hosting/scaling-and-performance/{monitoring,opentelemetry}all point to the new observability paths.CODEOWNERS validated via
gh api repos/Flagsmith/flagsmith/codeowners/errors— no errors.