A newer version of this documentation is available.

View Latest

Configure Prometheus Metrics Collection

      You can set up the Autonomous Operator to use the Couchbase Prometheus Exporter for metrics collection.


      Prometheus is the de facto metrics collection platform for use in Kubernetes environments. The Autonomous Operator provides Prometheus integration for collecting and exposing Couchbase Server metrics via the Couchbase Prometheus Exporter.

      Prometheus metrics collection is enabled in the CouchbaseCluster resource. The configuration allows you to specify a Couchbase-provided container image that contains the Prometheus Exporter. The Autonomous Operator injects the image as a "sidecar" container in each Couchbase Server pod.

      The Couchbase-supplied Prometheus Exporter container image is only supported on Kubernetes platforms in conjunction with the Couchbase Autonomous Operator.


      Prometheus metrics collection is enabled in the CouchbaseCluster resource.

      apiVersion: couchbase/v2
      kind: CouchbaseCluster
            enabled: true (1)
            image: couchbase/exporter:1.0.5 (2)
            authorizationSecret: cb-metrics-token (3)
      1 Setting couchbaseclusters.spec.monitoring.prometheus.enabled to true enables injection of the sidecar into Couchbase Server pods.
      2 If the couchbaseclusters.spec.monitoring.prometheus.image field is left unspecified, then the dynamic admission controller will automatically populate it with the most recent container image that was available when the installed version of the Autonomous Operator was released. The default image for open source Kubernetes comes from Docker Hub, and the default image for OpenShift comes from Red Hat Container Catalog.

      If pulling directly from the the Red Hat Container Catalog, then the path will be something similar to registry.connect.redhat.com/couchbase/exporter:1.0.5 (you can refer to the catalog for the most recent images). If image pull secrets are required to access the image, they are inherited from the Couchbase Server pod and can be set explicitly with the couchbaseclusters.spec.servers.pod.spec.imagePullSecrets field or implicitly with a service account specified with the couchbaseclusters.spec.servers.pod.spec.serviceAccountName field.

      3 You can optionally specify a Kubernetes Secret that contains a bearer token value that clients will need to use to gain access to the Prometheus metrics.

      If you wish to create a Kubernetes secret with a bearer token, simply edit and create the following definition:

      apiVersion: v1
      kind: Secret
        name: cb-metrics-token
      type: Opaque
        token: your-plain-text-bearer-token-here

      The stringData field allows you to put a non-base64 encoded string directly into the Secret, and Kubernetes will then encode the string for you when the Secret is created or updated.

      Important Considerations
      • You can enable/disable Prometheus metric collection at any time during the cluster’s lifecycle. However, since Pod resources are immutable, enabling or disabling metric collection will require a rolling upgrade of the cluster.

      • Only official Prometheus images provided by Couchbase are supported (with the exception of user-supplied images that specifically enable customized metrics).

        In addition, you should ensure that your image source is trusted. The sidecar container requires access to the Couchbase cluster administrative credentials in order to login and perform collection. Granting these credentials to arbitrary code is potentially harmful.

      Customizing Metrics

      By default, the exporter collects all metrics from Couchbase Server, with each metric having a default name and default metadata associated with it. The exporter supports certain user-configurable customizations to these defaults.

      The Couchbase Prometheus Exporter currently supports the following customizations:

      • Change the namespace, subsystem, name, and help text for each metric.

      • Enable and disable whether a metric is exported to Prometheus.

      These customizations are enabled by building your own custom version of the Couchbase Prometheus Exporter container image. For instructions on how to create a custom metrics configuration and build it into a container image, refer to the couchbase-exporter README.

      Using Exported Metrics

      Once configured, active metrics can be collected from each Couchbase Server pod on port 9091.

      The Autonomous Operator does not create or manage resources for third-party software. Prometheus scrape targets must be manually created by the user.

      Couchbase Cluster Auto-scaling

      The Autonomous Operator supports auto-scaling Couchbase clusters. In order to properly take advantage of this feature, users must expose Couchbase metrics through the Kubernetes custom metrics API.

      Discovery of available metrics can be performed through Prometheus queries. However, the Couchbase Exporter repository contains a convenient list of the Couchbase metrics being exported.

      Some metric names are further explained in the Couchbase Server documentation:

      You might find the following resources helpful when setting up your Prometheus environment: