docs(OTel): Add backend event catalogue

CODEOWNERS

@@ -6,3 +6,6 @@
 /frontend/       @flagsmith/flagsmith-front-end
 /infrastructure/ @flagsmith/flagsmith-infrastructure
 /docs/           @flagsmith/flagsmith-docs
+
+# Specific rules based on file
+/docs/docs/deployment-self-hosting/observability/_events-catalogue.md @flagsmith/flagsmith-product

api/Makefile

@@ -164,7 +164,8 @@ integrate-private-tests:
 
 .PHONY: generate-docs
 generate-docs: generate-flagsmith-sdk-openapi
-	poetry run flagsmith docgen metrics > ../docs/docs/administration-and-security/platform-configuration/metrics.md
+	poetry run flagsmith docgen metrics > ../docs/docs/deployment-self-hosting/observability/_metrics-catalogue.md
+	poetry run flagsmith docgen events > ../docs/docs/deployment-self-hosting/observability/_events-catalogue.md
 
 .PHONY: add-known-sdk-version
 add-known-sdk-version:

api/README.md

@@ -35,7 +35,7 @@ We use the Given When Then structure in all our tests.
 
 ### Code guidelines: metrics
 
-Flagsmith's backend exports Prometheus metrics. When planning a feature, consider which metrics should cover it — counters for domain events, histograms for latency or sizes, gauges for cardinalities. See [documentation for existing metrics](../docs/docs/administration-and-security/platform-configuration/metrics.md). Metrics code is hosted in `metrics.py` modules.
+Flagsmith's backend exports Prometheus metrics. When planning a feature, consider which metrics should cover it — counters for domain events, histograms for latency or sizes, gauges for cardinalities. See [documentation for existing metrics](https://docs.flagsmith.com/deployment-self-hosting/observability/metrics). Metrics code is hosted in `metrics.py` modules.
 
 Name metrics `flagsmith_{domain}_{entity}_{unit}` and give them a comprehensive description.
 

api/pyproject.toml

@@ -178,7 +178,7 @@ pygithub = "~2.8"
 hubspot-api-client = "^12.0.0"
 djangorestframework-dataclasses = "^1.3.1"
 pyotp = "^2.9.0"
-flagsmith-common = { version = ">=3.5.0,<4", extras = [
+flagsmith-common = { version = ">=3.8.2,<4", extras = [
   "common-core",
   "flagsmith-schemas",
   "task-processor",

docs/docs/administration-and-security/index.mdx

@@ -149,7 +149,7 @@ Configure environment-specific settings and platform-wide options for your Flags
     <div className="icon-container">
       <IonIcon icon={analytics} className="card-icon" />
     </div>
-    <h3><Link to="/administration-and-security/platform-configuration/metrics">Platform Metrics</Link></h3>
+    <h3><Link to="/deployment-self-hosting/observability/metrics">Platform Metrics</Link></h3>
   </div>
   <p>System monitoring and performance metrics</p>
 </Card>

docs/docs/deployment-self-hosting/core-configuration/environment-variables.md

@@ -53,7 +53,7 @@ relevant section below for more details.
 - `PREVENT_SIGNUP`: Determines whether to prevent new signups.
 - `ENABLE_EMAIL_ACTIVATION`: New user registration will go via email activation flow, default False.
 - `OTEL_EXPORTER_OTLP_ENDPOINT`: Base OTLP/HTTP endpoint (e.g. `http://collector:4318`). If unset, OTel is disabled. See
-  [OpenTelemetry](/deployment-self-hosting/scaling-and-performance/opentelemetry).
+  [OpenTelemetry](/deployment-self-hosting/observability/opentelemetry).
 - `OTEL_SERVICE_NAME`: The `service.name` resource attribute attached to all OTel telemetry. Defaults to
   `flagsmith-api`.
 - `OTEL_TRACING_EXCLUDED_URL_PATHS`: Comma-separated URL paths to exclude from OTel tracing (e.g.

docs/docs/deployment-self-hosting/index.md

@@ -50,11 +50,19 @@ Once deployed, you'll need to configure your Flagsmith instance:
 As your usage grows, you'll need to consider scaling and performance:
 
 - **[Sizing and Scaling](/deployment-self-hosting/scaling-and-performance/sizing-and-scaling)**: Understand resource requirements and scaling strategies
-- **[Monitoring](/deployment-self-hosting/scaling-and-performance/monitoring)**: Set up monitoring and alerting for your deployment
 - **[Asynchronous Task Processor](/deployment-self-hosting/scaling-and-performance/asynchronous-task-processor)**: Configure background task processing
 - **[Using InfluxDB for Analytics](/deployment-self-hosting/scaling-and-performance/using-influxdb-for-analytics)**: Set up analytics storage
 - **[Load Testing](/deployment-self-hosting/scaling-and-performance/load-testing)**: Test your deployment under load
 
+## Observability
+
+Monitor the health and behaviour of your deployment:
+
+- **[Monitoring](/deployment-self-hosting/observability/monitoring)**: Set up monitoring and alerting
+- **[Metrics](/deployment-self-hosting/observability/metrics)**: Prometheus metrics exported by the backend
+- **[Events](/deployment-self-hosting/observability/events)**: Structured events emitted by the backend
+- **[OpenTelemetry](/deployment-self-hosting/observability/opentelemetry)**: Export traces and logs via OTLP
+
 ## Administration and Maintenance
 
 Ongoing administration tasks to keep your deployment running smoothly:

docs/docs/deployment-self-hosting/observability/_category_.json

@@ -0,0 +1,5 @@
+{
+  "label": "Observability",
+  "position": 6,
+  "collapsed": true
+}

docs/docs/deployment-self-hosting/observability/_events-catalogue.md

@@ -0,0 +1,232 @@
+
+### `app_analytics.no_analytics_database_configured`
+
+Logged at `warning` from:
+ - `api/app_analytics/analytics_db_service.py:74`
+ - `api/app_analytics/analytics_db_service.py:210`
+
+Attributes:
+ - `details`
+
+### `code_references.cleanup_issues.created`
+
+Logged at `info` from:
+ - `api/integrations/github/views.py:388`
+
+Attributes:
+ - `issues_created.count`
+ - `organisation.id`
+
+### `code_references.scan.created`
+
+Logged at `info` from:
+ - `api/projects/code_references/views.py:41`
+
+Attributes:
+ - `code_references.count`
+ - `feature.count`
+ - `organisation.id`
+
+### `dynamodb.environment_document_compressed`
+
+Logged at `info` from:
+ - `api/environments/dynamodb/wrappers/environment_wrapper.py:92`
+
+Attributes:
+ - `environment_api_key`
+ - `environment_id`
+
+### `feature_health.feature_health_event_dismissal_not_supported`
+
+Logged at `warning` from:
+ - `api/features/feature_health/services.py:127`
+
+Attributes:
+ - `feature_health_event_external_id`
+ - `feature_health_event_id`
+ - `feature_health_event_type`
+ - `provider_name`
+
+### `feature_health.feature_health_provider_error`
+
+Logged at `error` from:
+ - `api/features/feature_health/services.py:50`
+
+Attributes:
+ - `exc_info`
+ - `provider_id`
+ - `provider_name`
+
+### `feature_health.invalid_feature_health_webhook_path_requested`
+
+Logged at `warning` from:
+ - `api/features/feature_health/providers/services.py:30`
+
+Attributes:
+ - `path`
+
+### `gitlab.api_call_failed`
+
+Logged at `error` from:
+ - `api/integrations/gitlab/views/browse_gitlab.py:58`
+
+Attributes:
+ - `exc_info`
+
+### `gitlab.configuration_created`
+
+Logged at `info` from:
+ - `api/integrations/gitlab/views/configuration.py:26`
+
+Attributes:
+ - `gitlab_instance_url`
+ - `organisation.id`
+ - `project.id`
+
+### `gitlab.configuration_updated`
+
+Logged at `info` from:
+ - `api/integrations/gitlab/views/configuration.py:34`
+
+Attributes:
+ - `gitlab_instance_url`
+ - `organisation.id`
+ - `project.id`
+
+### `gitlab.issues_fetched`
+
+Logged at `info` from:
+ - `api/integrations/gitlab/views/browse_gitlab.py:133`
+
+Attributes:
+ - `gitlab_project_id`
+ - `project.id`
+
+### `gitlab.merge_requests_fetched`
+
+Logged at `info` from:
+ - `api/integrations/gitlab/views/browse_gitlab.py:159`
+
+Attributes:
+ - `gitlab_project_id`
+ - `project.id`
+
+### `gitlab.projects_fetched`
+
+Logged at `info` from:
+ - `api/integrations/gitlab/views/browse_gitlab.py:108`
+
+Attributes:
+ - `project.id`
+
+### `launch_darkly.import_failed`
+
+Logged at `exception` from:
+ - `api/integrations/launch_darkly/tasks.py:36`
+
+Attributes:
+ - `import_request_id`
+ - `ld_project_key`
+ - `organisation_id`
+ - `project_id`
+
+### `launch_darkly.import_rate_limit_reached`
+
+Logged at `warning` from:
+ - `api/integrations/launch_darkly/tasks.py:26`
+
+Attributes:
+ - `error_message`
+ - `import_request_id`
+ - `ld_project_key`
+ - `organisation_id`
+ - `project_id`
+ - `retry_at`
+
+### `platform_hub.no_analytics_database_configured`
+
+Logged at `warning` from:
+ - `api/platform_hub/services.py:116`
+ - `api/platform_hub/services.py:206`
+ - `api/platform_hub/services.py:428`
+
+Attributes:
+
+### `segments.serializers.segment_revision_created`
+
+Logged at `info` from:
+ - `api/segments/serializers.py:141`
+
+Attributes:
+ - `revision_id`
+ - `segment_id`
+
+### `sentry_change_tracking.integration_error`
+
+Logged at `warning` from:
+ - `api/integrations/sentry/change_tracking.py:112`
+
+Attributes:
+ - `feature_name`
+ - `sentry_action`
+ - `sentry_response_body`
+ - `sentry_response_status`
+
+### `sentry_change_tracking.request_failure`
+
+Logged at `warning` from:
+ - `api/integrations/sentry/change_tracking.py:102`
+
+Attributes:
+ - `error`
+ - `feature_name`
+ - `sentry_action`
+
+### `sentry_change_tracking.sending`
+
+Logged at `debug` from:
+ - `api/integrations/sentry/change_tracking.py:87`
+
+Attributes:
+ - `feature_name`
+ - `headers`
+ - `payload`
+ - `sentry_action`
+ - `url`
+
+### `sentry_change_tracking.success`
+
+Logged at `info` from:
+ - `api/integrations/sentry/change_tracking.py:109`
+
+Attributes:
+ - `feature_name`
+ - `sentry_action`
+
+### `workflows.change_request.committed`
+
+Logged at `info` from:
+ - `api/core/workflows_services.py:39`
+
+Attributes:
+ - `environment.id`
+ - `feature_states.count`
+ - `organisation.id`
+
+### `workflows.missing_live_segment`
+
+Logged at `warning` from:
+ - `api/core/workflows_services.py:114`
+
+Attributes:
+ - `draft_segment`
+
+### `workflows.segment_revision_created`
+
+Logged at `info` from:
+ - `api/core/workflows_services.py:119`
+
+Attributes:
+ - `revision_id`
+ - `segment_id`
+

docs/docs/administration-and-security/platform-configuration/metrics.md → docs/docs/deployment-self-hosting/observability/_metrics-catalogue.md

@@ -1,17 +1,3 @@
----
-title: Metrics
-sidebar_label: Metrics
-sidebar_position: 20
----
-
-## Prometheus
-
-To enable the Prometheus `/metrics` endpoint, set the `PROMETHEUS_ENABLED` environment variable to `true`.
-
-When enabled, Flagsmith serves the `/metrics` endpoint on port 9100.
-
-The metrics provided by Flagsmith are described below.
-
 
 ### `flagsmith_build_info`
 

docs/docs/deployment-self-hosting/observability/events.mdx

@@ -0,0 +1,15 @@
+---
+title: Events
+sidebar_label: Events
+sidebar_position: 40
+---
+
+import EventCatalogue from './_events-catalogue.md';
+
+Flagsmith backend emits [OpenTelemetry events](https://opentelemetry.io/docs/specs/otel/logs/data-model/#events)
+that can be ingested to downstream observability systems and/or a data warehouse of your choice via OTLP.
+To learn how to configure this, see [OpenTelemetry](/deployment-self-hosting/observability/opentelemetry).
+
+## Event catalogue
+
+<EventCatalogue />

docs/docs/deployment-self-hosting/observability/metrics.mdx

@@ -0,0 +1,22 @@
+---
+title: Metrics
+sidebar_label: Metrics
+sidebar_position: 30
+---
+
+import MetricsCatalogue from './_metrics-catalogue.md';
+
+## Prometheus
+
+To enable the Prometheus `/metrics` endpoint, set the `PROMETHEUS_ENABLED` environment variable to `true`.
+
+When enabled, Flagsmith serves the `/metrics` endpoint on port 9100.
+
+The metrics provided by Flagsmith are described below.
+
+<MetricsCatalogue />
+
+## StatsD
+
+Flagsmith's Gunicorn worker emits per-request access log metrics (request counts, durations, HTTP statuses) to StatsD
+when configured. See [StatsD](/deployment-self-hosting/observability/monitoring#statsd) for setup.