Add support for Prometheus metrics

.github/workflows/test-all.yml

@@ -880,9 +880,22 @@ jobs:
       agent-image-windows-py2: "${{ inputs.agent-image-windows-py2 }}"
       test-py2: ${{ inputs.test-py2 }}
       test-py3: ${{ inputs.test-py3 }}
+      target-env: ${{ matrix.target-env }}
       minimum-base-package: ${{ inputs.minimum-base-package }}
       pytest-args: ${{ inputs.pytest-args }}
     secrets: inherit
+    strategy:
+      matrix:
+        target-env:
+        - py3.13-7.0-rest
+        - py3.13-7.0-prometheus
+        - py3.13-7.1-rest
+        - py3.13-7.1-prometheus
+        - py3.13-7.2-rest
+        - py3.13-7.2-prometheus
+        - py3.13-7.6-rest
+        - py3.13-7.6-prometheus
+      fail-fast: false
   ja3692a6:
     uses: ./.github/workflows/test-target.yml
     with:

couchbase/README.md

@@ -35,11 +35,31 @@ To configure this check for an Agent running on a host:
 
 1. Edit the `couchbase.d/conf.yaml` file in the `conf.d/` folder at the root of your [Agent's configuration directory][3] to start collecting your Couchbase data. See the [sample couchbase.d/conf.yaml][4] for all available configuration options.
 
+   The Couchbase integration supports two collection methods:
+
+   **Prometheus-based collection (Couchbase 7.0+)**
+
+   For Couchbase 7.0 and later, configure the `prometheus_url` to use the Prometheus exporter:
+
    ```yaml
    init_config:
 
    instances:
-     ## @param server - string - required
+     ## @param prometheus_url - string - optional
+     ## The Prometheus/OpenMetrics endpoint URL for the Prometheus-based check.
+     #
+     - prometheus_url: http://localhost:8091/metrics
+   ```
+
+   **Legacy REST API collection**
+
+   For older versions or to use the legacy REST API:
+
+   ```yaml
+   init_config:
+
+   instances:
+     ## @param server - string - optional
      ## The server's url.
      #
      - server: http://localhost:8091
@@ -79,6 +99,16 @@ For containerized environments, see the [Autodiscovery Integration Templates][6]
 
 ##### Metric collection
 
+For Prometheus-based collection (Couchbase 7.0+):
+
+| Parameter            | Value                                            |
+| -------------------- | ------------------------------------------------ |
+| `<INTEGRATION_NAME>` | `couchbase`                                      |
+| `<INIT_CONFIG>`      | blank or `{}`                                    |
+| `<INSTANCE_CONFIG>`  | `{"prometheus_url": "http://%%host%%:8091/metrics"}` |
+
+For legacy REST API collection:
+
 | Parameter            | Value                                |
 | -------------------- | ------------------------------------ |
 | `<INTEGRATION_NAME>` | `couchbase`                          |

couchbase/assets/configuration/spec.yaml

@@ -9,11 +9,31 @@ files:
   - template: instances
     options:
     - name: server
-      description: The server's url.
-      required: true
+      description: |
+        The server's url for the legacy REST API-based check.
+        Required if prometheus_url is not set.
+      required: false
       value:
         example: http://localhost:8091
         type: string
+    - name: prometheus_url
+      description: |
+        The Prometheus/OpenMetrics endpoint URL for the Prometheus-based check.
+        Required if server is not set. This enables collection of metrics from Couchbase's
+        Prometheus exporter (available in Couchbase 7.0+).
+      required: false
+      value:
+        example: http://localhost:8091/metrics
+        type: string
+    - name: labels_mapper
+      description: |
+        A mapping of Prometheus labels to rename to avoid conflicts with reserved tag names.
+        By default, the "service" label is renamed to "couchbase_service" to avoid conflict
+        with Datadog's reserved "service" tag while preserving the contextual information.
+      value:
+        example:
+          service: couchbase_service
+        type: object
     - name: query_monitoring_url
       description: |
         Url to get query monitoring stats, available since couchbase 4.5.

couchbase/changelog.d/21780.added

@@ -0,0 +1 @@
+Add support for Prometheus-based metrics collection

couchbase/datadog_checks/couchbase/check.py

@@ -0,0 +1,55 @@
+# (C) Datadog, Inc. 2025-present
+# All rights reserved
+# Licensed under a 3-clause BSD style license (see LICENSE)
+
+from datadog_checks.base import OpenMetricsBaseCheck
+
+from .metrics import (
+    get_metric_map_couchbase_to_datadog,
+    get_type_overrides,
+)
+
+
+class CouchbaseCheckV2(OpenMetricsBaseCheck):
+    """
+    Couchbase check using OpenMetrics/Prometheus metrics.
+    """
+
+    DEFAULT_METRIC_LIMIT = 0
+
+    def __init__(self, name, init_config, instances):
+        instance = instances[0]
+
+        # Configure metrics collection using our curated metric map
+        metrics = instance.get("metrics", [])
+        if not metrics:
+            metric_map = get_metric_map_couchbase_to_datadog()
+            metrics = [metric_map]
+
+        metric_type_overrides = get_type_overrides()
+
+        instance.update(
+            {
+                "prometheus_url": instance.get("prometheus_url"),
+                "namespace": "couchbase",
+                "metrics": metrics,
+                "type_overrides": metric_type_overrides,
+                # Use traditional histogram format with separate .sum and .count metrics
+                "send_histograms_buckets": True,
+                "send_distribution_buckets": False,
+                # Send histogram counts and sums as monotonic counters (Prometheus histograms are cumulative)
+                "send_distribution_counts_as_monotonic": True,
+                "send_distribution_sums_as_monotonic": True,
+                # Increase timeout in case Couchbase is slow to respond
+                "prometheus_timeout": instance.get("prometheus_timeout", 20),
+                # Ensure we collect all metrics (no limit)
+                "max_returned_metrics": instance.get("max_returned_metrics", 0),
+                # Rename the "service" label to avoid conflict with Datadog's reserved "service" tag
+                "labels_mapper": instance.get("labels_mapper", {"service": "couchbase_service"}),
+                # Authentication - map 'user' to 'username' for OpenMetrics compatibility
+                "username": instance.get("username") or instance.get("user"),
+                "password": instance.get("password"),
+            }
+        )
+
+        super().__init__(name, init_config, [instance])

couchbase/datadog_checks/couchbase/config_models/defaults.py

@@ -60,6 +60,10 @@ def instance_persist_connections():
     return False
 
 
+def instance_prometheus_url():
+    return 'http://localhost:8091/metrics'
+
+
 def instance_query_monitoring_url():
     return 'http://localhost:8093'
 
@@ -68,6 +72,10 @@ def instance_request_size():
     return 16
 
 
+def instance_server():
+    return 'http://localhost:8091'
+
+
 def instance_skip_proxy():
     return False
 

couchbase/datadog_checks/couchbase/config_models/instance.py

@@ -74,17 +74,19 @@ class InstanceConfig(BaseModel):
     kerberos_hostname: Optional[str] = None
     kerberos_keytab: Optional[str] = None
     kerberos_principal: Optional[str] = None
+    labels_mapper: Optional[MappingProxyType[str, Any]] = None
     log_requests: Optional[bool] = None
     metric_patterns: Optional[MetricPatterns] = None
     min_collection_interval: Optional[float] = None
     ntlm_domain: Optional[str] = None
     password: Optional[str] = None
     persist_connections: Optional[bool] = None
+    prometheus_url: Optional[str] = None
     proxy: Optional[Proxy] = None
     query_monitoring_url: Optional[str] = None
     read_timeout: Optional[float] = None
     request_size: Optional[float] = None
-    server: str
+    server: Optional[str] = None
     service: Optional[str] = None
     skip_proxy: Optional[bool] = None
     sync_gateway_url: Optional[str] = None

couchbase/datadog_checks/couchbase/couchbase.py

@@ -34,6 +34,8 @@
     TO_SECONDS,
 )
 
+from .check import CouchbaseCheckV2
+
 
 class Couchbase(AgentCheck):
     """
@@ -43,6 +45,14 @@ class Couchbase(AgentCheck):
 
     HTTP_CONFIG_REMAPPER = {'user': {'name': 'username'}, 'ssl_verify': {'name': 'tls_verify'}}
 
+    def __new__(cls, name, init_config, instances):
+        instance = instances[0]
+
+        if instance.get("prometheus_url"):
+            return CouchbaseCheckV2(name, init_config, instances)
+        else:
+            return super(Couchbase, cls).__new__(cls)
+
     def __init__(self, name, init_config, instances):
         super(Couchbase, self).__init__(name, init_config, instances)
 

couchbase/datadog_checks/couchbase/couchbase_consts.py

@@ -364,14 +364,14 @@
 INDEX_STATS_COUNT_METRICS = [
     "cache_hits",
     "cache_misses",
-    "items_count",
     "num_docs_indexed",
     "num_items_flushed",
     "num_requests",
     "num_rows_returned",
     "num_scan_errors",
     "num_scan_timeouts",
     "scan_bytes_read",
+    "total_scan_duration",
 ]
 
 INDEXER_STATE_MAP = {'Active': 0, 'Pause': 1, 'Warmup': 2}

couchbase/datadog_checks/couchbase/data/conf.yaml.example

@@ -45,10 +45,27 @@ init_config:
 #
 instances:
 
-    ## @param server - string - required
-    ## The server's url.
+  -
+    ## @param server - string - optional - default: http://localhost:8091
+    ## The server's url for the legacy REST API-based check.
+    ## Required if prometheus_url is not set.
     #
-  - server: http://localhost:8091
+    # server: http://localhost:8091
+
+    ## @param prometheus_url - string - optional - default: http://localhost:8091/metrics
+    ## The Prometheus/OpenMetrics endpoint URL for the Prometheus-based check.
+    ## Required if server is not set. This enables collection of metrics from Couchbase's
+    ## Prometheus exporter (available in Couchbase 7.0+).
+    #
+    # prometheus_url: http://localhost:8091/metrics
+
+    ## @param labels_mapper - mapping - optional
+    ## A mapping of Prometheus labels to rename to avoid conflicts with reserved tag names.
+    ## By default, the "service" label is renamed to "couchbase_service" to avoid conflict
+    ## with Datadog's reserved "service" tag while preserving the contextual information.
+    #
+    # labels_mapper:
+    #   service: couchbase_service
 
     ## @param query_monitoring_url - string - optional - default: http://localhost:8093
     ## Url to get query monitoring stats, available since couchbase 4.5.