Kafka

The plugin displays the performance metrics of producers and consumers.

Introduction

Plugin version: 1.1

The Kafka plugin retrieves the internal metrics of a Kafka producer and consumer using the kafka-python library. It creates one Pandora FMS agent for each specified broker and sends its metrics in XML format.

The collected metrics are based on Kafka client metrics. For more information, see the official documentation:

Type: Server plugin.

Compatibility matrix

Systems where it has been tested

Rocky linux
Systems where it should work

Any linux system

Pre requisites

Parameters

Parameter Description Default
-h, --help Displays the help text, plugin version, and execution example. —
--bootstrap_servers One or more comma-separated Kafka brokers in host:port format. One agent is created for each specified value. Required
--topics Comma-separated list of topics to which the consumer subscribes. Empty string
--topic_regex Regular expression used to subscribe to topics. When specified, it takes precedence over --topics. Empty string
--agent_prefix Prefix added to the name and alias of each generated agent. Empty string
--module_prefix Prefix added to the name of every generated module. Empty string
--transfer_mode Transfer mode used by pandoraPlugintools to send the XML files. tentacle
--tentacle_ip Tentacle server IP address. 127.0.0.1
--tentacle_port Tentacle server port. 41121
--verbose Displays error and debug messages during execution. Disabled

Manual execution

Use the following syntax:

./pandora_kafka \
  --bootstrap_servers <host:port[,host:port,...]> \
  [--topics <topic1,topic2,...>] \
  [--topic_regex <regex>] \
  [--agent_prefix <prefix>] \
  [--module_prefix <prefix>] \
  [--transfer_mode <mode>] \
  [--tentacle_ip <ip>] \
  [--tentacle_port <port>] \
  [--verbose]

Example using a regular expression to select topics:

./pandora_kafka \
  --bootstrap_servers kafka1:9092,kafka2:9092 \
  --topic_regex '^prod-.*' \
  --agent_prefix 'KAFKA_' \
  --module_prefix 'METRIC_' \
  --transfer_mode tentacle \
  --tentacle_ip 10.0.0.20 \
  --tentacle_port 41121 \
  --verbose

A specific list of topics can also be selected:

./pandora_kafka \
  --bootstrap_servers kafka1:9092 \
  --topics orders,payments

If both --topics and --topic_regex are specified, the plugin uses --topic_regex.

When the execution finishes, the plugin prints 1 if no error occurred while processing the brokers and 0 if any broker raised an exception. The --verbose option displays details about the detected errors.

Configuration in PandoraFMS

As a server plugin

Go to Servers > Plugins in the Pandora FMS console and click Add.

Set the desired name and description. In the command field, enter the full path to the executable:

/usr/share/pandora_server/util/plugin/pandora_kafka

/usr/share/pandora_server/util/plugin/

In the plugin parameters, include --bootstrap_servers as a required field and add any other arguments you need using _field<N>_ macros.

Example:

--bootstrap_servers _field1_ --topics _field2_ --agent_prefix _field3_ --module_prefix _field4_ --transfer_mode tentacle --tentacle_ip 127.0.0.1 --tentacle_port 41121

After creating the server plugin, open an agent, create a plugin module, and select the configured plugin. This module receives the final 1 or 0 returned by the execution, while the Kafka metrics are sent through separate XML agents.

Modules generated by the plugin

Agents

The plugin creates one agent for each entry in --bootstrap_servers.

The agent name and alias use the following format:

<agent_prefix><host:port>

For example, with --agent_prefix KAFKA_ and the kafka1:9092 broker, the generated agent is:

KAFKA_kafka1:9092

Agents are created with a 300-second interval and the Created by plugin description.

Modules

The plugin iterates over all metrics returned by producer.metrics() and consumer.metrics(). Therefore, the exact list may vary depending on the kafka-python version, Kafka version, available nodes, and client activity.

All modules use the generic_data type and have no unit or description. Module names use the following format:

<module_prefix><metric_group>.<metric_name>

Floating-point values that are NaN or infinite are converted to 0.0.

The main generated metric groups are listed below:

Source Metric group Module examples without a prefix Type
Producer and consumer kafka-metrics kafka-metrics.count generic_data
Producer producer-metrics producer-metrics.connection-count, producer-metrics.request-rate, producer-metrics.request-latency-avg, producer-metrics.record-send-rate, producer-metrics.record-error-rate generic_data
Producer producer-node-metrics.node-<node> producer-node-metrics.node-<node>.outgoing-byte-rate, producer-node-metrics.node-<node>.request-rate, producer-node-metrics.node-<node>.response-rate generic_data
Consumer consumer-metrics consumer-metrics.connection-count, consumer-metrics.request-rate, consumer-metrics.request-latency-avg, consumer-metrics.incoming-byte-rate generic_data
Consumer consumer-node-metrics.node-<node> consumer-node-metrics.node-<node>.incoming-byte-rate, consumer-node-metrics.node-<node>.request-rate, consumer-node-metrics.node-<node>.response-rate generic_data
Consumer consumer-fetch-manager-metrics consumer-fetch-manager-metrics.fetch-size-avg, consumer-fetch-manager-metrics.bytes-consumed-rate, consumer-fetch-manager-metrics.records-consumed-rate, consumer-fetch-manager-metrics.records-lag-max generic_data
Consumer consumer-coordinator-metrics consumer-coordinator-metrics.heartbeat-rate, consumer-coordinator-metrics.join-rate, consumer-coordinator-metrics.commit-rate, consumer-coordinator-metrics.assigned-partitions generic_data

For example, when --module_prefix METRIC_ is used, the producer-metrics.request-rate module is created as:

METRIC_producer-metrics.request-rate