ZooKeeper

The Apache ZooKeeper source collects metrics and logs from a ZooKeeper server. Metrics are scraped from the ZooKeeper admin interface using the mntr four-letter-word command over the client port (default 2181), exposing server-state, latency, request, watch, and znode statistics. Logs are read from ZooKeeper's log files on disk and optionally parsed into structured fields.

Supported Telemetry

Platform	Metrics	Logs	Traces
Linux	✓	✓
Windows	✓	✓
macOS	✓	✓

Prerequisites

Metrics

• A reachable ZooKeeper server and its client port (default 2181) accessible from the collector host.
• The mntr four-letter-word command must be enabled. ZooKeeper 3.5+ disables most four-letter-word commands by default; only srvr is whitelisted. Add mntr (and srvr) to the 4lw.commands.whitelist configuration on each ZooKeeper server. See the ZooKeeper Administrator's Guide.

Logs

• ZooKeeper writing log files on the host, and the collector running with read access to those file path(s). The default path is /opt/zookeeper/logs/zookeeper.log; adjust to your installation.

Configuration

Telemetry

Parameter	Type	Required	Default	Description
Choose Telemetry Type	Telemetry Selector	No	["Logs", "Metrics"]	Which signals this source collects. Valid values: Logs, Metrics.

Logs

Relevant when Choose Telemetry Type includes Logs.

Parameter	Type	Required	Default	Description
Log Path(s)	Strings	Yes	/opt/zookeeper/logs/zookeeper.log	File paths to ZooKeeper logs.

Metrics

Relevant when Choose Telemetry Type includes Metrics.

Parameter	Type	Required	Default	Description
Address	String	No	localhost	IP address or hostname of the ZooKeeper system.
Port	Integer	No	2181	Port of the ZooKeeper system.

Advanced

Parameter	Type	Required	Default	Description
Start At	Enum: beginning, end	No	end	Start reading logs from the beginning or end of the file. Relevant when Choose Telemetry Type includes Logs.
Parse	Boolean	No	true	Parse the log fields into structured data. Relevant when Choose Telemetry Type includes Logs.
Collection Interval	Integer	No	60	How often (seconds) to scrape for metrics. Relevant when Choose Telemetry Type includes Metrics.

Examples

Collect metrics from a local ZooKeeper server

Scrape metrics from a ZooKeeper server listening on the default client port, every 30 seconds, without log collection.

apiVersion: bindplane.observiq.com/v1
kind: Source
metadata:
  name: zookeeper-metrics
spec:
  type: zookeeper
  parameters:
    - name: telemetry_types
      value: ["Metrics"]
    - name: address
      value: localhost
    - name: port
      value: 2181
    - name: collection_interval
      value: 30

Collect metrics and logs together

Scrape metrics from a remote ZooKeeper server and tail its log file, reading new entries from the end.

apiVersion: bindplane.observiq.com/v1
kind: Source
metadata:
  name: zookeeper-all
spec:
  type: zookeeper
  parameters:
    - name: telemetry_types
      value: ["Logs", "Metrics"]
    - name: address
      value: zookeeper-1.internal
    - name: port
      value: 2181
    - name: file_path
      value:
        - /opt/zookeeper/logs/zookeeper.log
    - name: start_at
      value: end
    - name: parse
      value: true

Configuration Tips

• ZooKeeper 3.5+ requires mntr in 4lw.commands.whitelist; if it is not whitelisted the receiver collects no metrics even though the port is reachable.
• The metrics endpoint is the ZooKeeper client port (default 2181), not a JMX/RMI port. No Java agent or JMX configuration is required for this source.
• Run the collector on (or with file access to) the host where ZooKeeper writes its logs, since logs are read directly from the file path(s).

Troubleshooting

Connection refused on the metrics endpoint

Symptoms: no metrics arrive; the collector logs a connection error to the ZooKeeper address/port.

Solutions:

1. Confirm ZooKeeper is listening on the configured Address and Port (default 2181) and that a firewall is not blocking the collector host.
2. Verify the client port is the one ZooKeeper is actually serving (clientPort).

Metrics endpoint reachable but no metrics

Symptoms: the port connects but no ZooKeeper metrics are produced.

Solutions:

1. Add mntr to the 4lw.commands.whitelist on each ZooKeeper server (3.5+ disables it by default) and restart ZooKeeper.
2. Confirm the ZooKeeper version supports the mntr command (3.4.0+).

No logs collected

Symptoms: log collection is enabled but no log records appear.

Solutions:

1. Verify the Log Path(s) match the actual ZooKeeper log location and that the collector user has read permission.
2. If logs were written before the collector started and Start At is end, set Start At to beginning to read existing content.

Standalone Source

apiVersion: bindplane.observiq.com/v1
kind: Source
metadata:
  name: zookeeper
spec:
  type: zookeeper
  parameters:
    - name: telemetry_types
      value: ["Logs", "Metrics"]
    - name: address
      value: localhost
    - name: port
      value: 2181
    - name: collection_interval
      value: 60
    - name: file_path
      value:
        - /opt/zookeeper/logs/zookeeper.log
    - name: start_at
      value: end
    - name: parse
      value: true

Related Resources

• ZooKeeper Monitor Guide
• ZooKeeper Administrator's Guide (four-letter-word whitelist)
• OpenTelemetry zookeeperreceiver