docs(SaaS): Add Cluster Metrics endpoint documentation for Camunda 8 SaaS monitoring

docs/components/saas/monitoring/cluster-metrics-endpoint/configure-monitoring-systems-to-scrape-metrics.md

@@ -0,0 +1,135 @@
+---
+id: configure-monitoring-systems-to-scrape-metrics
+title: Configure monitoring systems to scrape metrics
+description: Learn how to configure monitoring systems to scrape metrics from the Cluster Metrics endpoint in Camunda 8 SaaS.
+---
+
+Configure your monitoring systems to scrape metrics from a Camunda 8 SaaS cluster using the Cluster Metrics endpoint.
+
+## Before you begin
+
+Before configuring metric scraping, ensure that:
+
+- The Cluster Metrics endpoint is enabled for your Camunda 8 SaaS cluster.
+- You have the metrics endpoint URL and authentication credentials.
+- Your monitoring system can reach the endpoint from an allowlisted IP address.
+
+For information about the Cluster Metrics endpoint monitoring model and limitations, see [Cluster Metrics endpoint](/components/saas/monitoring/cluster-metrics-endpoint/index.md).
+
+## Metrics endpoint details
+
+The metrics endpoint:
+
+- Uses HTTPS
+- Requires Basic Authentication
+- Returns metrics in Prometheus format
+
+### Endpoint format
+
+The full metrics endpoint follows this format: `https://<metrics-target>/<cluster-id>`
+
+- `<metrics-target>`: The domain hosting the metrics endpoint.
+- `<cluster-id>`: The identifier of the Camunda 8 SaaS cluster.
+
+### Verify endpoint access
+
+Before configuring your monitoring system, use the following command to verify that the Cluster Metrics endpoint is reachable:
+
+```bash
+curl -v -u "<username>:<password>" https://<metrics-target>/<cluster-id>
+```
+
+## Configure Prometheus scraping
+
+Prometheus can scrape the Cluster Metrics endpoint directly.
+
+### Example scrape configuration
+
+```yaml
+scrape_configs:
+  - job_name: "c8-<cluster-id>"
+    scheme: https
+    metrics_path: /<cluster-id>
+    static_configs:
+      - targets:
+          - <metrics-target>
+    basic_auth:
+      username: <username>
+      password: <password>
+    scrape_timeout: 5s
+    scrape_interval: 30s
+```
+
+Configuration notes:
+
+- Use HTTPS.
+- Configure Basic Authentication using the credentials provided when the Cluster Metrics endpoint was enabled.
+- A scrape timeout of less than 10 seconds is recommended.
+- A scrape interval of at least 15 seconds is recommended. Metrics are collected every 15–30 seconds, so shorter intervals do not produce new data.
+
+## Scrape interval and retention
+
+The Cluster Metrics endpoint exposes metrics from the most recent scrape only and does not retain historical data.
+
+Configure your monitoring system to store and retain metrics as needed.
+
+## Verify metric collection
+
+After configuring scraping:
+
+- Confirm that the scrape target reports a healthy state.
+- Check that metrics correspond to the expected Camunda 8 cluster.
+
+If metrics do not appear, review authentication, network access, and scrape configuration.
+
+## Integrate non-Prometheus monitoring systems
+
+The Cluster Metrics endpoint exposes metrics in Prometheus-compatible formats. Some monitoring systems require additional components to ingest these metrics.
+
+In these cases, you can deploy a self-managed OpenTelemetry Collector to adapt the metrics to your monitoring system. For more information, see the [OpenTelemetry Collector documentation](https://opentelemetry.io/docs/collector/).
+
+![Integrate non-Prometheus monitoring systems](./img/cluster-metrics-endpoint-non-prometheus-architecture.png)
+
+Using an OpenTelemetry Collector allows you to normalize, enrich, and control the flow of metrics scraped from the Cluster Metrics endpoint. For example, you can:
+
+- Transform metrics to match internal naming conventions
+- Filter metrics to reduce noise or control ingestion costs.
+- Enrich metrics with standard labels such as environment or region.
+- Forward metrics to one or more monitoring backends.
+- Manage scrape behavior, buffering, retries, and backpressure without changing how Camunda exposes metrics.
+
+### Push-only monitoring systems
+
+If your monitoring system only supports push-based ingestion, use the following approach:
+
+1. Deploy a self-managed OpenTelemetry Collector.
+1. Configure the collector to scrape the Cluster Metrics endpoint.
+1. Configure the collector to push metrics to your monitoring system.
+
+Camunda provides the metrics endpoint only. You are responsible for deploying, configuring, and operating the collector.
+
+### Non-Prometheus metric formats
+
+If your monitoring system requires a format other than Prometheus, use an OpenTelemetry Collector with the appropriate exporter.
+
+The OpenTelemetry Collector supports a wide range of exporters, allowing you to forward metrics to different monitoring backends.
+
+For more information, see [OpenTelemetry Collector exporters](https://opentelemetry.io/docs/collector/components/exporter/).
+
+## Troubleshoot common issues
+
+### Authentication errors
+
+- Verify the configured username and password.
+- Check that the monitoring system’s IP address is allowlisted.
+
+### Scrape timeouts
+
+- Increase the configured scrape timeout.
+- Verify network connectivity to the metrics endpoint.
+
+### Missing or incomplete metrics
+
+- Confirm that the Cluster Metrics endpoint for the cluster is enabled and healthy.
+- Verify that the cluster is running a supported Camunda version.
+- Review scrape interval and retention behavior.

docs/components/saas/monitoring/cluster-metrics-endpoint/index.md

@@ -0,0 +1,57 @@
+---
+id: overview
+title: Cluster Metrics endpoint
+description: Learn how to expose and consume Camunda 8 SaaS cluster metrics using the Cluster Metrics endpoint.
+---
+
+The Cluster Metrics endpoint lets you expose metrics from a Camunda 8 SaaS Orchestration cluster and consume them in your own monitoring system.
+
+## About
+
+Use this endpoint to monitor cluster performance, set alerts, and correlate Camunda metrics with the rest of your infrastructure using your existing observability tools.
+
+This endpoint is a dedicated, customer-facing metrics service that exposes aggregated component-level metrics. The endpoint is separate from Camunda’s internal monitoring and operational systems and provides access only to metrics intended for customer consumption.
+
+## Before you begin
+
+Before using the Cluster Metrics endpoint, ensure that:
+
+- You have an external monitoring system capable of collecting prometheus metrics.
+- You understand your organization’s network access and IP allowlisting requirements.
+
+## Supported environments
+
+- The Cluster Metrics endpoint is available for all Camunda 8 SaaS Orchestration clusters.
+- The endpoint is configured per Orchestration cluster and can be enabled without requiring an upgrade or downtime.
+
+## Metrics exposure model
+
+The Cluster Metrics endpoint exposes metrics using a pull-based model and Prometheus-compatible format ([Prometheus](https://github.com/prometheus/docs/blob/main/docs/instrumenting/exposition_formats.md#text-based-format) and [OpenMetrics](https://github.com/prometheus/docs/blob/main/docs/instrumenting/exposition_formats.md#openmetrics-text-format) text exposition formats).
+
+![Cluster Metrics endpoint architecture](./img/cluster-metrics-endpoint-prometheus-architecture.png)
+
+When the Cluster Metrics endpoint is enabled for a cluster:
+
+- Camunda exposes a cluster-scoped metrics endpoint that aggregates metrics from all Orchestration cluster components.
+- Metrics are exposed in Prometheus-compatible format.
+- Your monitoring system initiates metric collection by scraping the endpoint.
+
+The Cluster Metrics endpoint does not push metrics to customer systems.
+
+## Monitoring endpoint constraints
+
+The Cluster Metrics endpoint exposes the application-level metrics produced by the Camunda version running in your cluster.
+
+The following constraints apply:
+
+- The Cluster Metrics endpoint uses Basic Authentication only.
+- Metric names and labels depend on the Camunda version running in your cluster.
+- Metric and dashboard compatibility between Camunda versions is not guaranteed.
+
+If your monitoring system does not support Prometheus scraping, you can adapt the metrics using a self-managed OpenTelemetry Collector. For more information, see [Integrate non-Prometheus monitoring systems](/components/saas/monitoring/cluster-metrics-endpoint/configure-monitoring-systems-to-scrape-metrics.md#integrate-non-prometheus-monitoring-systems).
+
+## Next steps
+
+- To enable the Cluster Metrics endpoint and obtain connection details, see [Set up the Cluster Metrics endpoint](/components/saas/monitoring/cluster-metrics-endpoint/set-up-cluster-metrics-endpoint.md).
+- To configure Prometheus to scrape metrics, see [Configure monitoring systems to scrape metrics](/components/saas/monitoring/cluster-metrics-endpoint/configure-monitoring-systems-to-scrape-metrics.md).
+- If your monitoring system does not support Prometheus scraping, see [Integrate non-Prometheus monitoring systems](/components/saas/monitoring/cluster-metrics-endpoint/configure-monitoring-systems-to-scrape-metrics.md#integrate-non-prometheus-monitoring-systems).

docs/components/saas/monitoring/cluster-metrics-endpoint/set-up-cluster-metrics-endpoint.md

@@ -0,0 +1,115 @@
+---
+id: set-up-cluster-metrics-endpoint
+title: Set up the Cluster Metrics endpoint
+description: Learn how to set up the Cluster Metrics endpoint in Camunda 8 SaaS, manage credentials, and obtain the connection details required to integrate with your monitoring system.
+---
+
+Set up and manage the Cluster Metrics endpoint for a Camunda 8 SaaS Orchestration cluster, including how to activate and deactivate the endpoint and obtain the connection details required to integrate it with an external monitoring system.
+
+## Before you begin
+
+Before enabling the Cluster Metrics endpoint, ensure that:
+
+- You are using Camunda 8 SaaS.
+- You have access to Console and have permission to manage cluster-level settings.
+- If allowlisting is configured for your cluster, the monitoring system’s source IP addresses are added to the cluster IP allowlist.
+
+## Enable Cluster Metrics endpoint
+
+Enable the Cluster Metrics endpoint per Orchestration cluster via either the Camunda Console or API. When the endpoint is enabled, Camunda provisions a secure, cluster-scoped metrics endpoint for external scraping.
+
+To activate the endpoint:
+
+1. Sign in to Camunda Console.
+1. Navigate to **Clusters**.
+1. Select an existing cluster, or create a new one.
+1. Open the **Monitoring** tab for the cluster.
+1. Click **Activate monitoring endpoint**.
+1. Enter a **username** for the monitoring credentials.
+1. Click **Activate**.
+
+### Capture connection details
+
+When the Cluster Metrics endpoint is activated, the Console displays a dialog containing the authentication credentials.
+
+1. Copy and store the password securely.
+1. Click **Got it** to close the dialog.
+
+After closing the dialog, you can find the metrics endpoint URL in the **Monitoring** tab for the cluster.
+
+:::warning
+Copy and safely store the password when it is displayed. The password is not shown again after you close the dialog. If you lose it, generate a new password.
+:::
+
+The following information is required to connect your monitoring system:
+
+- **Metrics endpoint URL**: HTTPS endpoint used by your monitoring system to scrape metrics.
+- **Username**: Used for Basic Authentication.
+- **Password**: Used for Basic Authentication.
+
+## Manage authentication credentials
+
+Authentication credentials are created and managed in Camunda Console.
+
+### Create additional credentials
+
+You can create up to 20 credentials per cluster.
+
+To create additional credentials:
+
+1. On the **Monitoring** tab, click **Create new credentials**.
+1. Enter a username.
+1. Generate and copy the password when it is displayed.
+
+### Rotate credentials
+
+Ƭo rotate a password:
+
+1. On the **Monitoring** tab, locate the credential.
+1. Click the **Generate password** icon next to the username.
+1. Generate and copy the new password when prompted.
+
+When credentials are removed or rotated, previously issued credentials may continue to work briefly. Access may persist for up to five minutes before the credentials are fully invalidated.
+
+To avoid interruptions during credential rotation, you can create multiple credentials for the same cluster and update your monitoring system to switch between credentials, rather than rotating a single credential in place.
+
+## Authentication and IP allowlisting
+
+The Cluster Metrics endpoint enforces both authentication and network restrictions.
+
+| Restriction     | Description                                                                                                                                                                                                                                                                                                      |
+| :-------------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Authentication  | The endpoint uses Basic Authentication.                                                                                                                                                                                                                                                                          |
+| IP allowlisting | The endpoint enforces the cluster-level IP allowlist. <ul><li><p>Requests from non-allowlisted IP addresses are rejected.</p></li><li><p>If an IP allowlist is configured for the cluster, you must add the source IP addresses of your monitoring system to the allowlist to access the endpoint.</p></li></ul> |
+
+### Error responses
+
+The Cluster Metrics endpoint returns standard HTTP status codes to indicate access and availability issues:
+
+| Scenario                                       | HTTP status code          |
+| :--------------------------------------------- | :------------------------ |
+| Request from a non-allowlisted IP address.     | `403 Forbidden`           |
+| Invalid or missing authentication credentials. | `401 Unauthorized`        |
+| Request rate exceeds allowed limits.           | `429 Too Many Requests`   |
+| Metrics endpoint is temporarily unavailable.   | `503 Service Unavailable` |
+| Request times out due to high load.            | `504 Gateway Timeout`     |
+
+## Disable the Cluster Metrics endpoint
+
+If you no longer want to expose cluster metrics externally, you can disable the Cluster Metrics endpoint:
+
+- Click **Deactivate** in the **Monitoring** tab, or
+- Delete all credentials associated with the endpoint
+
+When the Cluster Metrics endpoint is disabled:
+
+- The monitoring endpoint is shut down almost immediately (typically within a few seconds).
+- All existing credentials are deleted and are not retained if the endpoint is reactivated.
+- Monitoring systems can no longer scrape metrics from the cluster.
+
+To use the endpoint again, you must reactivate it and create new credentials. Disabling the Cluster Metrics endpoint does not affect cluster operation or workload execution.
+
+## Next steps
+
+- To configure Prometheus to scrape metrics from the Cluster Metrics endpoint, see [Configure monitoring systems to scrape metrics](/components/saas/monitoring/cluster-metrics-endpoint/configure-monitoring-systems-to-scrape-metrics.md).
+- If your monitoring system does not support Prometheus scraping, see [Integrate non-Prometheus monitoring systems](/components/saas/monitoring/cluster-metrics-endpoint/configure-monitoring-systems-to-scrape-metrics.md#integrate-non-prometheus-monitoring-systems).

docs/components/saas/monitoring/index.md

@@ -0,0 +1,13 @@
+---
+id: overview
+title: Monitoring
+description: Learn how to monitor Camunda 8 SaaS Orchestration Clusters using a secure metrics endpoint and your existing monitoring and observability tools.
+---
+
+Use your own monitoring and observability tools to observe the health and performance of your Camunda 8 SaaS Orchestration Clusters.
+
+## Cluster Metrics endpoint
+
+Camunda provides a secure, customer-facing metrics endpoint that exposes aggregated cluster metrics for external consumption.
+
+<p class="link-arrow">[Cluster Metrics endpoint](cluster-metrics-endpoint/index.md)</p>

docs/reference/announcements-release-notes/890/890-release-notes.md

@@ -92,6 +92,18 @@ New documentation shows you how to:
 - Install Camunda 8 Run with H2 as the default secondary storage.
 - Seamlessly switch from H2 to Elasticsearch or OpenSearch when required.
 
+### Cluster Metrics endpoint
+
+<div class="release"><span class="badge badge--long" title="This feature affects SaaS">SaaS</span><span class="badge badge--medium" title="This feature affects Console">Console</span></div>
+<!-- https://github.com/camunda/product-hub/issues/2229 -->
+
+Camunda 8.9 provides a Cluster Metrics endpoint for SaaS clusters.
+
+- Activate a secure metrics endpoint for your cluster and integrate it with Prometheus, Datadog, or any monitoring system that supports Prometheus scraping.
+- Get real-time visibility into cluster performance, troubleshoot faster, and integrate with your existing observability stack.
+
+<p class="link-arrow">[Cluster Metrics endpoint](/components/saas/monitoring/cluster-metrics-endpoint/index.md)</p>
+
 ### Global user task listeners
 
 <div class="release"><span class="badge badge--long" title="This feature affects Self-Managed">Self-Managed</span></div>

sidebars.js

@@ -1067,6 +1067,28 @@ module.exports = {
         "components/concepts/clusters",
         "components/saas/regions",
         "components/saas/data-locations",
+        {
+          type: "category",
+          label: "Monitoring",
+          link: {
+            type: "doc",
+            id: "components/saas/monitoring/overview",
+          },
+          items: [
+            {
+              type: "category",
+              label: "Cluster Metrics endpoint",
+              link: {
+                type: "doc",
+                id: "components/saas/monitoring/cluster-metrics-endpoint/overview",
+              },
+              items: [
+                "components/saas/monitoring/cluster-metrics-endpoint/set-up-cluster-metrics-endpoint",
+                "components/saas/monitoring/cluster-metrics-endpoint/configure-monitoring-systems-to-scrape-metrics",
+              ],
+            },
+          ],
+        },
         {
           type: "category",
           label: "Encryption",