How to Enable Insights and Metrics

This guide shows you how to turn Metrics Exposer on, expose Kafka metrics to Prometheus, route API Gateway traffic to the exposer, switch the Insight screens on in Self-Service, and confirm they show data.

Type

How-to guide

Goal

Get Kafka metrics visible to users in the Self-Service Insight screens.

Audience

Platform Operator who can edit the Axual Governance and Streaming values and apply them.

When to use

Use this guide after the governance layer is installed and a Prometheus stack is available.

Metrics Exposer is disabled by default, because it reads from a Prometheus stack the platform does not install. Nothing here works until that stack exists and scrapes the Kafka metrics.

Contents

The sections below cover each task in this guide:

Prerequisites

Confirm the following before you begin.

Access and permissions required

You need the following access and permissions:

  • Permission to edit the Axual Governance and Axual Streaming values files, and to upgrade both Helm releases.

  • An account in Self-Service that can open a topic, so you can confirm the Insight screens at the end.

Tools and versions required

You need the following tools:

  • helm >= 3.12, with OCI registry support.

  • kubectl >= 1.28, configured for the target cluster.

Resources that must exist before starting

The following must already exist:

  • The governance layer, installed per Install Axual Governance.

  • A Prometheus stack, with a Prometheus Operator to act on the PodMonitor the Kafka chart creates. See Installing the Monitoring Stack.

  • At least one topic in Self-Service with data flowing through it, because an idle topic draws an empty graph whether the setup works or not.

Enable Metrics Exposer

Turn the exposer on in the Axual Governance values.

values.yaml
global:
  # Metrics Exposer is disabled by default
  metrics-exposer:
    enabled: true

Every value the chart accepts is described in Metrics Exposer Chart Values Reference.

The exposer on its own shows nothing. Three more things have to be in place, each covered by a section below:

  • Kafka exposes its metrics for Prometheus to scrape.

  • The API Gateway redirects calls to Metrics Exposer.

  • The Platform UI allows the Insight features.

Enable Kafka Metrics

Prometheus needs two things from the Kafka cluster. The PodMonitor tells it what to scrape, and the Kafka exporter produces the consumer group and topic metrics the Insight screens read. Both are off by default, and both live in the Axual Streaming values.

values.yaml
kafka:
  kafka:
    # Creates the PodMonitor Prometheus scrapes
    metrics: true
    # Exports consumer group lag, topic and partition metrics
    kafkaExporter:
      enabled: true

Kafka PodMonitoring describes the scrape interval, the scrape timeout and the monitor labels. Set podMonitor.labels as well when your Prometheus Operator discovers only labelled monitors, which Make the Axual monitors discoverable covers.

Enable API Gateway redirect to Metrics Exposer

Turn the metricsExposer and metricsExposerApiDocs endpoints on in the API Gateway values, and point the gateway at the Platform Manager endpoint that serves the monitoring configuration.

Replace every <VALUE> placeholder with your own value before applying the file.
values.yaml
api-gateway:

  config:
    # Metrics Exposer Config Endpoint
    metrics-exposer-config-api:
      url: "http://<PLATFORM_MANAGER_SERVICE_NAME>/api/monitoring_information"
    gateway:
      endpoints:

        # Optional Backend service
        metricsExposer:
          enabled: true
          url: "http://<METRICS_EXPOSER_SERVICE_NAME>"
        # Optional Backend service
        metricsExposerApiDocs:
          enabled: true
          url: "http://<METRICS_EXPOSER_SERVICE_NAME>"

Every endpoint the gateway accepts is described in Gateway Endpoints.

Enable Self-Service Insight

Turn insightsEnabled on in the Platform UI values, and give it the exposer URL the gateway serves.

values.yaml
platform-ui:

  config:
      # To enable Insights with Metrics Exposer
      insightsEnabled: true
      metricsExposerUrl: "https://platform.<DOMAIN>/api/metrics"

Both values are described in Insight Configuration.

Verify the Insight screens show data

Check the two halves separately, because they fail for different reasons. A missing exposer pod or PodMonitor is a values problem in the charts, while a running exposer behind an empty graph is a scraping or routing problem.

kubectl get pods -n axual
kubectl get podmonitor -n kafka

The Metrics Exposer pod reads Running, and a PodMonitor for the Kafka cluster exists in the namespace the streaming layer runs in. Substitute your own namespaces for axual and kafka.

Then open a topic in Self-Service and confirm the message rate appears on the Topic Card and the Insights tab draws a graph. Topic Insights describes the metrics and filters on that tab.

Metrics are scraped every 30 seconds, so allow a minute before treating an empty graph as a failure.