docs: Add Feature Health docs

- Add "Advanced Use > Feature Health"
- Add Grafana Feature Health Provider docs
- Improve Grafana Integration docs
- Rename "APM" to "Observability"

Author: khvn26

docs/docs/advanced-use/feature-health.md

@@ -0,0 +1,53 @@
+---
+title: Feature Health
+---
+
+:::info
+
+Feature Health is an upcoming feature that's not yet available.
+
+:::
+
+Feature Health enables users to monitor observability metrics within Flagsmith, specifically in relation to Flagsmith's Features and Environments. Flagsmith receives alert notifications from your observability provider and, based on this data, marks your Features and optionally Environments with an **Unhealthy** status, providing details about the alerts. This enhances your team's observability, allowing for quicker, more informed decisions.
+
+## Integrations
+
+The following is an overview of the Feature Health providers currently supported.
+
+### Grafana / Prometheus Alertmanager
+
+[Learn more](/integrations/apm/grafana/#feature-health-provider-setup) about configuring Grafana / Prometheus Alertmanager Feature Health provider.
+
+### Sample Provider
+
+We provide a Sample Provider for your custom integrations. To create a Sample Feature Health webhook:
+
+1. Go to Project Settings > Feature Health.
+2. Select "Sample" from the Provider Name drop-down menu.
+3. Click Create and copy the Webhook URL.
+
+You can use the webhook in your custom integration. Refer to the payload schema below:
+
+```json
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "SampleEvent",
+  "type": "object",
+  "properties": {
+    "environment": {
+      "type": "string"
+    },
+    "feature": {
+      "type": "string"
+    },
+    "status": {
+      "type": "string",
+      "enum": ["healthy", "unhealthy"]
+    },
+    "reason": {
+      "type": "string"
+    }
+  },
+  "required": ["feature", "status"]
+}
+```

docs/docs/integrations/apm/_category_.json

@@ -1,5 +1,5 @@
 {
-    "label": "APM",
+    "label": "Observability",
     "collapsed": false,
     "position": 20
-}
+}

docs/docs/integrations/apm/grafana.md

@@ -9,9 +9,9 @@ import ReactPlayer from 'react-player'
 
 ![Image](/img/integrations/grafana/grafana-logo.svg)
 
-You can integrate Flagsmith with Grafana. Send flag change events from Flagsmith into Grafana as annotations.
+Integrate Flagsmith with Grafana to send flag change events as annotations.
 
-The video below will walk you through the steps of adding the integration:
+The video below demonstrates the integration process:
 
 <ReactPlayer
     controls
@@ -21,25 +21,57 @@ The video below will walk you through the steps of adding the integration:
 
 ## Integration Setup
 
-Log into Grafana and generate a Service Account Key:
+To set up the integration, follow these steps:
 
-1. Navigate to Administration > Users and access > Service accounts
-2. Add Service Account
-3. Change the Role selection to "Annotation Writer" or "Editor".
-4. Click on Add service account token and make a note of the generated token.
+### In Grafana:
 
-In Flagsmith:
+1. Go to Administration > Users and access > Service accounts.
+2. Add a Service Account.
+3. Set the Role to "Annotation Writer" or "Editor".
+4. Click on "Add service account token" and save the generated token.
 
-1. Navigate to Integrations, then add the Grafana integration.
-2. Enter the URL for your web interface of your Grafana installation. For example, `https://grafana.flagsmith.com`.
-3. Paste the service account token you created in Grafana to `Service account token` field.
+### In Flagsmith:
+
+1. Go to Integrations and add the Grafana integration.
+2. Enter the URL of your Grafana installation (e.g., `https://grafana.flagsmith.com`).
+3. Paste the service account token from Grafana into the `Service account token` field.
 4. Click Save.
 
-Flag change events will now be sent to Grafana as _Organisation Level_
-[Annotations](https://grafana.com/docs/grafana/latest/dashboards/build-dashboards/annotate-visualizations/).
+Flag change events will now be sent to Grafana as _Organisation Level_ [Annotations](https://grafana.com/docs/grafana/latest/dashboards/build-dashboards/annotate-visualizations/).
+
+To view the annotations in Grafana, go to Dashboard Settings > Annotations, select the `Grafana` data source, and filter by the `flagsmith` tag.
+
+Annotations for feature-specific events include project tags, user-defined tags, and environment tags for flag change events.
+
+## Feature Health Provider Setup
+
+:::info
+
+Feature Health is an upcoming feature that is not yet available.
+
+:::
+
+### In Flagsmith:
+
+1. Go to Project Settings > Feature Health.
+2. Select "Grafana" from the Provider Name drop-down menu.
+3. Click Create and copy the Webhook URL.
+
+### In Grafana:
+
+1. Create a new Webhook contact point using the Webhook URL from Flagsmith. Refer to the [Grafana documentation on contact points](https://grafana.com/docs/grafana/latest/alerting/configure-notifications/manage-contact-points/#add-a-contact-point) for details.
+2. Leave Optional Webhook settings empty. Ensure the "Disable resolved message" checkbox is unchecked.
+3. Add the `flagsmith_feature` label to your alert rule, specifying the Flagsmith Feature name. Refer to the [Grafana documentation on alert rule labels](https://grafana.com/docs/grafana/latest/alerting/fundamentals/alert-rules/annotation-label/#labels) for more information.
+4. Optionally, include the `flagsmith_environment` label in your alert rule, using the Flagsmith Environment name as the value.
+5. Set the previously created contact point as the alert rule recipient.
+
+You can create multiple alert rules pointing to the Feature Health Provider webhook. Ensure they include the `flagsmith_feature` label with a Feature name from the Project you created the Feature Health Provider for, to see Feature Health status changes for your features.
 
-You can view the annotations in your Grafana dashboards but going to Dashboard Settings > Annotations, selecting the
-`Grafana` data source and then filtering on annotations that are tagged with the `flagsmith` tag.
+You can integrate Grafana Feature Health with Prometheus Alertmanager. For detailed instructions on adding Flagsmith labels to your alerts in Prometheus, refer to the [Prometheus Alertmanager webhook configuration](https://prometheus.io/docs/alerting/latest/configuration/#webhook_config) and [Alerting rules configuration](https://prometheus.io/docs/prometheus/latest/configuration/alerting_rules/#defining-alerting-rules) documentation.
 
-Annotations reporting feature-specific events include the project tag and Flagsmith user-defined tags, and flag change
-events include the environment tag as well.
+The Feature Health UI will display the following information:
+- Alert name
+- Link to the alert instance in your Alertmanager
+- Alert description (if provided in alert annotations)
+- Alert summary (if provided in alert annotations)
+- Runbook URL (if provided in alert annotations)

docs/docs/integrations/index.md

@@ -68,7 +68,7 @@ analysis. [Learn more](/integrations/analytics/rudderstack).
 You can integrate Flagsmith with your own Analytics Platform/Data Warehouse. Send your Identity flag states into
 Snowflake, RedShift or anywhere else for further downstream analysis! [Learn more](/integrations/webhook).
 
-## Application Monitoring and Performance
+## Observability
 
 ---
 
@@ -90,6 +90,7 @@ You can integrate Flagsmith with Dynatrace. Send flag change events from Flagsmi
 
 You can integrate Flagsmith with Grafana. Send flag change events from Flagsmith into Grafana as annotations.
 [Learn more](/integrations/apm/grafana).
+**Coming soon**: Integrate your Grafana and Prometheus alerts with Feature Health.
 
 ---