// 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, configure the appropriate properties in the custom resources for the components you want to monitor.

Use `metricsConfig` to expose metrics for these components:

* Kafka 
* Kafka Connect
* MirrorMaker
* Cruise Control

This enables the {JMXExporter}, which exposes metrics on port 9404 through an HTTP endpoint. 
Prometheus scrapes this endpoint to collect Kafka metrics.

Set `enableMetrics` to `true` to expose metrics for the following: 

* Kafka Bridge
* OAuth 2.0
** Configure in the `Kafka` resource for `oauth` or `keycloak` cluster authorization, or `oauth` listener authentication.
** Configure in the `KafkaBridge`, `KafkaConnect`, or `KafkaMirrorMaker2` resources for `oauth` authentication.

To include xref:con-metrics-kafka-exporter-lag-str[Kafka Exporter] metrics, add `kafkaExporter` configuration to the `Kafka` resource.

IMPORTANT: Kafka Exporter provides additional metrics for consumer lag and offsets only.
You still need to configure Prometheus metrics in the `Kafka` resource to collect standard Kafka metrics.

You can create your own Prometheus configuration or use the xref:ref-metrics-prometheus-metrics-config-{context}[example custom resource 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 include relabeling rules and example metrics configuration, and are a good starting point for trying Prometheus with Strimzi. 

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

.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, 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` containing metrics configuration.
<2> Copy the whole `ConfigMap` specifying the metrics configuration.

. To deploy Kafka Exporter, add `kafkaExporter` configuration.
+
`kafkaExporter` configuration is specified only 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>
    showAllOffsets: false # <6>
    resources: # <7>
      requests:
        cpu: 200m
        memory: 64Mi
      limits:
        cpu: 500m
        memory: 128Mi
    logging: debug # <8>
    enableSaramaLogging: true # <9>
    template: # <10>
      pod:
        metadata:
          labels:
            label1: value1
        imagePullSecrets:
          - name: my-docker-credentials
        securityContext:
          runAsUser: 1000001
          fsGroup: 0
        terminationGracePeriodSeconds: 120
    readinessProbe: # <11>
      initialDelaySeconds: 15
      timeoutSeconds: 5
    livenessProbe: # <12>
      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> By default, metrics are collected for all consumers regardless of their connection status. Setting `showAllOffsets` to `false` stops collecting metrics on disconnected consumers.
<7> CPU and memory resources to reserve.
<8> Logging configuration, to log messages with a given severity (debug, info, warn, error, fatal) or above.
<9> Boolean to enable Sarama logging, a Go client library used by Kafka Exporter.
<10> Customization of deployment templates and pods.
<11> Healthcheck readiness probes.
<12> 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 

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

* In the Kafka resource for:
** Cluster authorization (`oauth` or `keycloak`)
** Listener authentication (`oauth` only)
* In the `KafkaBridge`, `KafkaConnect`, or `KafkaMirrorMaker2` resources for `oauth` authentication  

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

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

To use OAuth 2.0 metrics with Prometheus, copy the `ConfigMap` configuration from the `oauth-metrics.yaml` file to the same `Kafka` resource configuration file where you enabled metrics for OAuth 2.0 and then apply the configuration.

NOTE: You can also enable metrics for the `type: opa` authorization option in the same way as for OAuth 2.0 authorization.
However, `type: opa` is deprecated and will be removed in a future release.
To continue using the Open Policy Agent authorizer, use the `type: custom` authorization configuration.


