|
1 | | -# Custom Kafka Log integration |
| 1 | +# Custom Kafka Integration |
2 | 2 |
|
3 | | -The custom Kafka log integration is used to read from topics in a Kafka cluster. |
| 3 | +## Overview |
4 | 4 |
|
5 | | -To configure this integration, specify a list of one or more hosts in the cluster to bootstrap the connection with, a list of topics to track, and a group_id for the connection. |
| 5 | +The Custom Kafka integration is an **input** package for Elastic Agent. It runs the Filebeat **Kafka** input so agents can **consume** records from Apache Kafka topics and ship them to Elasticsearch. Use it when applications or pipelines already publish logs or events to Kafka and you want Elastic to read from those topics without an intermediate forwarder. |
6 | 6 |
|
| 7 | +### Compatibility |
7 | 8 |
|
8 | | -## Compatibility |
9 | | -This Integration works with all Kafka versions in between 0.11 and 2.8.0. Older versions might work as well, but are not supported. |
| 9 | +This integration is intended for Kafka clusters where brokers speak the standard Kafka protocol. It is tested and supported for Kafka broker versions roughly between **0.11** and **2.8.0**. Earlier or later brokers can work but are not guaranteed. |
10 | 10 |
|
| 11 | +### How it works |
11 | 12 |
|
12 | | -## Ingest Pipelines |
13 | | -Custom ingest pipelines may be added by adding the name to the pipeline configuration option, creating custom ingest pipelines can be done either through the API or the [Ingest Node Pipeline UI](/app/management/ingest/ingest_pipelines/). |
| 13 | +Elastic Agent connects to your cluster using the **bootstrap hosts** you configure, joins a **consumer group** (`group_id`), and subscribes to one or more **topics**. Messages are read by the agent, enriched with Kafka metadata (for example topic, partition, offset), and written to Elasticsearch using the **dataset** name you choose (default `kafka_log.generic`). Optional **SASL**, **Kerberos**, and **TLS** settings secure the connection to the brokers. Optional **parsers** and **processors** adjust the payload on the agent before ingest. |
14 | 14 |
|
15 | | -**ECS Field Reference** |
| 15 | +## What data does this integration collect? |
16 | 16 |
|
17 | | -Please refer to the following [document](https://www.elastic.co/guide/en/ecs/current/ecs-field-reference.html) for detailed information on ECS fields. |
| 17 | +The integration collects **events** derived from Kafka messages: |
| 18 | + |
| 19 | +- **Message payload**: Typically stored in the `message` field (format depends on your producers—plain text, JSON, syslog, and so on). |
| 20 | +- **Kafka metadata**: Fields such as `kafka.topic`, `kafka.partition`, `kafka.offset`, `kafka.key`, and `kafka.headers` where applicable. |
| 21 | +- **Routing fields**: `data_stream.dataset`, `data_stream.type`, and `data_stream.namespace` follow your Fleet policy and dataset name. |
| 22 | + |
| 23 | +The default **dataset** is `kafka_log.generic`. Changing the **Dataset name** in the policy sends data to a different backing data stream. Dataset names must follow Elasticsearch naming rules (no `-` in the dataset segment). |
| 24 | + |
| 25 | +### Supported use cases |
| 26 | + |
| 27 | +- Ingest logs or telemetry already landed on Kafka by microservices or stream processors. |
| 28 | +- Centralize topic data for search and observability in Kibana without maintaining a separate log shipper per producer. |
| 29 | +- Apply a custom **Ingest Pipeline** in Elasticsearch when you need parsing or ECS normalization beyond agent-side parsers. |
| 30 | + |
| 31 | +## What do I need to use this integration? |
| 32 | + |
| 33 | +### Kafka prerequisites |
| 34 | + |
| 35 | +- **Network reachability** from the host running Elastic Agent to each configured bootstrap broker (hostnames and ports). |
| 36 | +- **Topic access**: ACLs or permissions that allow your consumer **group** to read the configured topics. |
| 37 | +- **Authentication details** if the cluster uses SASL (PLAIN, SCRAM), Kerberos, or TLS client certificates—match these to your broker configuration. |
| 38 | + |
| 39 | +### Elastic prerequisites |
| 40 | + |
| 41 | +- A stack version that satisfies the integration’s **Kibana** requirement (refer to the integration manifest in Kibana or this package’s `manifest.yml`). |
| 42 | + |
| 43 | +## How do I deploy this integration? |
| 44 | + |
| 45 | +### Agent-based deployment |
| 46 | + |
| 47 | +Elastic Agent runs the Kafka input and forwards events to Elasticsearch. Install the agent on a host that can reach your Kafka brokers (same VPC or routed network, firewall rules allowing outbound connections to broker listeners). |
| 48 | + |
| 49 | +### Set up steps for Kafka |
| 50 | + |
| 51 | +1. Identify **bootstrap broker addresses** (for example `kafka1:9092`) and the **topic names** to consume. |
| 52 | +2. Choose a unique **consumer group id** (`group_id`) for this policy integration—duplicate group membership affects partition assignment when multiple agents share the same group. |
| 53 | +3. If the cluster uses TLS or SASL, gather certificates, credentials, or Kerberos configuration paths before editing the integration. |
| 54 | + |
| 55 | +### Set up steps in Kibana |
| 56 | + |
| 57 | +1. Go to **Management → Integrations**. |
| 58 | +2. Search for **Custom Kafka Logs** and open it. |
| 59 | +3. Click **Add Custom Kafka Logs** (or add the integration to an existing policy). |
| 60 | +4. Configure the main options: |
| 61 | + - **Hosts**: Bootstrap servers for the Kafka cluster. |
| 62 | + - **Topics**: Topics to subscribe to. |
| 63 | + - **Group ID**: Consumer group for this input. |
| 64 | + - **Dataset name**: Target dataset (default `kafka_log.generic`). |
| 65 | + - **Client ID**, **Kafka protocol version**, **initial offset**, fetch/rebalance tuning: expand **Advanced options** when needed. |
| 66 | +5. Configure **SSL**, **SASL**, or **Kerberos** under advanced sections if your brokers require them. |
| 67 | +6. Optionally set **Parsers** (for example NDJSON) or **Processors**, and **Tags**. |
| 68 | +7. Optionally set **Ingest Pipeline** to an Elasticsearch pipeline ID for server-side processing. |
| 69 | +8. Save the policy and confirm the agent receives the updated configuration. |
| 70 | + |
| 71 | +### Validation |
| 72 | + |
| 73 | +1. Produce a test message to one of the configured topics (use your usual producer tooling or `kafka-console-producer`). |
| 74 | +2. In Kibana, open **Analytics → Discover** and select a logs-related data view (for example `logs-*`). |
| 75 | +3. Filter with KQL, for example: `data_stream.dataset : "kafka_log.generic"` — adjust to match your configured **Dataset name** (default `kafka_log.generic`). |
| 76 | +4. Confirm fields such as `message`, `kafka.topic`, `input.type` (`kafka`), and timestamps look correct. |
| 77 | + |
| 78 | +## Troubleshooting |
| 79 | + |
| 80 | +For help with Elastic ingest tools, refer to [Common problems](https://www.elastic.co/docs/troubleshoot/ingest/fleet/common-problems). |
| 81 | + |
| 82 | +### Common configuration issues |
| 83 | + |
| 84 | +- **Connection or timeout errors**: Verify broker addresses, ports, TLS (`ssl.enabled`), and that firewalls allow outbound traffic from the agent host to every bootstrap broker. |
| 85 | +- **Authentication failures**: Confirm SASL mechanism, username/password, or Kerberos settings align with the broker, check broker logs for `Authentication failed` or similar. |
| 86 | +- **No documents in Discover**: Confirm the agent is healthy, the policy applied, and the **Dataset name** matches your Discover filter. Dataset names **must not** contain hyphens. |
| 87 | +- **Duplicate or competing consumers**: Using the same `group_id` on many agents splits partitions across them by design, use distinct groups if you need full duplicate reads. |
| 88 | +- **Offset / replay behavior**: `initial_offset` (for example `oldest` vs `newest`) affects where consumption starts for new groups. Changing `group_id` starts a new consumer group offset state. |
| 89 | +- **Parsing issues**: If JSON or multiline payloads look wrong, review **Parsers** and consider an Elasticsearch **Ingest Pipeline** for complex structures. |
| 90 | + |
| 91 | +## Performance and scaling |
| 92 | + |
| 93 | +For architectures used to scale ingest, refer to [Ingest Architectures](https://www.elastic.co/docs/manage-data/ingest/ingest-reference-architectures). |
| 94 | + |
| 95 | +- **Throughput**: Kafka throughput scales with **partitions** and consumer parallelism, multiple agents with the **same** `group_id` share partitions (one consumer per partition per group). |
| 96 | +- **Fetch settings**: Tune **fetch** sizes and **max_wait_time** in advanced options if you need higher batching or lower latency—balance broker load and agent memory. |
| 97 | +- **Multiple integrations**: Separate policies or dataset names help isolate indices and retention for different topic groups. |
| 98 | +- **Elasticsearch**: Size your cluster for the volume of documents and consider ingest pipelines and index lifecycle policies for hot/warm tiers. |
| 99 | + |
| 100 | +## Reference |
| 101 | + |
| 102 | +Refer to the [ECS field reference](https://www.elastic.co/guide/en/ecs/current/ecs-field-reference.html) for ECS fields. |
| 103 | + |
| 104 | +Additional documentation: |
| 105 | + |
| 106 | +- [Filebeat Kafka input](https://www.elastic.co/guide/en/beats/filebeat/current/filebeat-input-kafka.html) |
| 107 | +- [Filebeat SSL settings](https://www.elastic.co/guide/en/beats/filebeat/current/configuration-ssl.html#ssl-common-config) |
0 commit comments