// This assembly is included in the following assemblies:
//
// metrics/assembly_metrics-kafka.adoc

[id='proc-metrics-kafka-deploy-options-{context}']
= Enabling Prometheus metrics through configuration

[role="_abstract"]
To enable and expose metrics in Strimzi for Prometheus, use metrics configuration properties. 

The following components require `metricsConfig` configuration to expose metrics:

* Kafka 
* KafkaConnect
* MirrorMaker
* Cruise Control
* ZooKeeper

This configuration enables the {JMXExporter} to expose metrics through an HTTP endpoint, which is scraped by the Prometheus server.

You set the `enableMetrics` property to `true` in order to expose metrics for these components:

* Kafka Bridge 
* OAuth 2.0 authentication and authorization framework
* Open Policy Agent (OPA) for authorization

To deploy Prometheus metrics configuration in Strimzi, you can use your own configuration or the xref:ref-metrics-prometheus-metrics-config-{context}[example custom resource configuration files] provided with Strimzi:

* `kafka-metrics.yaml`
* `kafka-connect-metrics.yaml`
* `kafka-mirror-maker-2-metrics.yaml`
* `kafka-bridge-metrics.yaml`
* `kafka-cruise-control-metrics.yaml`
* `oauth-metrics.yaml`

These files contain the necessary relabeling rules and configuration to enable Prometheus metrics.
They are a good starting point for trying Prometheus with Strimzi. 

This procedure shows how to deploy example Prometheus metrics configuration in the `Kafka` resource.
The process is the same when deploying the example files for other resources.

If you wish to include xref:con-metrics-kafka-exporter-lag-str[Kafka Exporter] metrics, add `kafkaExporter` configuration to your `Kafka` resource.

IMPORTANT: Kafka Exporter only provides additional metrics related to consumer lag and consumer offsets.
For regular Kafka metrics, you must configure the Prometheus metrics in xref:proc-metrics-kafka-deploy-options-{context}[Kafka brokers].

.Procedure

. Deploy the example custom resource with the Prometheus configuration.
+
For example, for each `Kafka` resource you can apply the `kafka-metrics.yaml` file.
+
.Deploying the example configuration
[source,shell,subs="+attributes"]
----
kubectl apply -f kafka-metrics.yaml
----
+
Alternatively, you can copy the example configuration in `kafka-metrics.yaml` to your own `Kafka` resource.
+
.Copying the example configuration
[source,shell]
----
kubectl edit kafka <kafka_configuration_file>
----
+
Copy the `metricsConfig` property and the `ConfigMap` it references to your `Kafka` resource.
+
.Example metrics configuration for Kafka
[source,yaml,subs="+quotes,attributes"]
----
apiVersion: {KafkaApiVersion}
kind: Kafka
metadata:
  name: my-cluster
spec:
  kafka:
    # ...
    metricsConfig: <1>
      type: jmxPrometheusExporter
      valueFrom:
        configMapKeyRef:
          name: kafka-metrics
          key: kafka-metrics-config.yml
---
kind: ConfigMap <2>
apiVersion: v1
metadata:
  name: kafka-metrics
  labels:
    app: strimzi
data:
  kafka-metrics-config.yml: |
  # _metrics configuration..._
----
<1> Copy the `metricsConfig` property that references the ConfigMap that contains metrics configuration.
<2> Copy the whole `ConfigMap` that specifies the metrics configuration.

. To deploy Kafka Exporter, add `kafkaExporter` configuration.
+
`kafkaExporter` configuration is only specified in the `Kafka` resource.
+
.Example configuration for deploying Kafka Exporter
[source,yaml,subs="attributes+"]
----
apiVersion: {KafkaApiVersion}
kind: Kafka
metadata:
  name: my-cluster
spec:
  # ...
  kafkaExporter:
    image: my-registry.io/my-org/my-exporter-cluster:latest <1>
    groupRegex: ".*" <2>
    topicRegex: ".*" <3>
    groupExcludeRegex: "^excluded-.*" <4>
    topicExcludeRegex: "^excluded-.*" <5>
    resources: <6>
      requests:
        cpu: 200m
        memory: 64Mi
      limits:
        cpu: 500m
        memory: 128Mi
    logging: debug <7>
    enableSaramaLogging: true <8>
    template: <9>
      pod:
        metadata:
          labels:
            label1: value1
        imagePullSecrets:
          - name: my-docker-credentials
        securityContext:
          runAsUser: 1000001
          fsGroup: 0
        terminationGracePeriodSeconds: 120
    readinessProbe: <10>
      initialDelaySeconds: 15
      timeoutSeconds: 5
    livenessProbe: <11>
      initialDelaySeconds: 15
      timeoutSeconds: 5
# ...
----
<1> ADVANCED OPTION: Container image configuration, which is recommended only in special situations.
<2> A regular expression to specify the consumer groups to include in the metrics.
<3> A regular expression to specify the topics to include in the metrics.
<4> A regular expression to specify the consumer groups to exclude in the metrics.
<5> A regular expression to specify the topics to exclude in the metrics.
<6> CPU and memory resources to reserve.
<7> Logging configuration, to log messages with a given severity (debug, info, warn, error, fatal) or above.
<8> Boolean to enable Sarama logging, a Go client library used by Kafka Exporter.
<9> Customization of deployment templates and pods.
<10> Healthcheck readiness probes.
<11> Healthcheck liveness probes.

NOTE: For Kafka Exporter to be able to work properly, consumer groups need to be in use. 

.Enabling metrics for Kafka Bridge 

To expose metrics for Kafka Bridge, set the `enableMetrics` property to `true` in the `KafkaBridge` resource.

.Example metrics configuration for Kafka Bridge
[source,yaml,subs="+quotes,attributes"]
----
apiVersion: {KafkaApiVersion}
kind: KafkaBridge
metadata:
  name: my-bridge
spec:
  # ...
  bootstrapServers: my-cluster-kafka:9092
  http:
    # ...
  enableMetrics: true
  # ...
----

.Enabling metrics for OAUth 2.0 and OPA 

To expose metrics for OAuth 2.0 or OPA, set the `enableMetrics` property to `true` in the appropriate custom resource.

OAuth 2.0 metrics:: Enable metrics for Kafka cluster authorization and Kafka listener authentication in the `Kafka` resource.
+
You can also enable metrics for OAuth 2.0 authentication in the custom resource of other xref:proc-oauth-kafka-config-{context}[supported components].   
OPA metrics:: Enable metrics for Kafka cluster authorization the `Kafka` resource in the same way as for OAuth 2.0. 

In the following example, metrics are enabled for OAuth 2.0 listener authentication and OAuth 2.0 (`keycloak`) cluster authorization.

.Example cluster configuration with metrics enabled for OAuth 2.0
[source,yaml,subs="+quotes,attributes"]
----
apiVersion: {KafkaApiVersion}
kind: Kafka
metadata:
  name: my-cluster
  namespace: myproject
spec:
  kafka:
    # ...
    listeners:
    - name: external
      port: 9094
      type: loadbalancer
      tls: true
      authentication:
        type: oauth
        enableMetrics: true
      configuration:
        #...
    authorization:
      type: keycloak
      enableMetrics: true
  # ...
----

To use the OAuth 2.0 metrics with Prometheus, you can use the `oauth-metrics.yaml` file to deploy example Prometheus metrics configuration.
Copy the `ConfigMap` configuration the `oauth-metrics.yaml` file contains to the same `Kafka` resource configuration file where you enabled metrics for OAUth 2.0.


