Implementation:Apache Kafka Trogdor Script

Knowledge Sources	Apache_Kafka
Domains	Testing, Fault_Injection, CLI
Last Updated	2026-02-09 12:00 GMT

Overview

External Tool Doc for launching the Trogdor fault injection and workload generation framework via the trogdor.sh shell script.

Description

The trogdor.sh script is the entry point for Kafka's built-in distributed testing framework. It supports four modes of operation by mapping subcommands to Java classes:

• agent maps to org.apache.kafka.trogdor.agent.Agent — the agent that runs on each node and executes fault injection tasks.
• coordinator maps to org.apache.kafka.trogdor.coordinator.Coordinator — the central coordinator that manages and distributes tasks.
• client maps to org.apache.kafka.trogdor.coordinator.CoordinatorClient — a CLI client for interacting with the coordinator.
• agent-client maps to org.apache.kafka.trogdor.agent.AgentClient — a CLI client for interacting with agents directly.

The script sets INCLUDE_TEST_JARS=1 to ensure test dependencies are on the classpath, then delegates to kafka-run-class.sh with the selected Java class.

Usage

Use this script to perform chaos testing and workload generation across a Kafka cluster. Trogdor enables fault injection (network partitions, process kills, disk faults) and produce/consume benchmarks for validating Kafka's resilience to failure scenarios.

Code Reference

Source Location

• Repository: Apache_Kafka
• File: bin/trogdor.sh
• Lines: 1-50

Signature

#!/bin/bash
# Usage: trogdor.sh [action] [options]
#
# Actions:
#   agent:        Run the trogdor agent
#   coordinator:  Run the trogdor coordinator
#   client:       Run the client which communicates with the trogdor coordinator
#   agent-client: Run the client which communicates with the trogdor agent
#   help:         Display help message

# Subcommand-to-class mapping:
#   agent        -> org.apache.kafka.trogdor.agent.Agent
#   coordinator  -> org.apache.kafka.trogdor.coordinator.Coordinator
#   client       -> org.apache.kafka.trogdor.coordinator.CoordinatorClient
#   agent-client -> org.apache.kafka.trogdor.agent.AgentClient

export INCLUDE_TEST_JARS=1
exec kafka-run-class.sh "${CLASS}" "$@"

Import

# No import required; invoke directly from the Kafka installation bin/ directory:
bin/trogdor.sh agent --agent.config config/trogdor.conf --node-name node0

I/O Contract

Inputs

Name	Type	Required	Description
action	String	Yes	One of: agent, coordinator, client, agent-client, help
options	Varies	Depends on action	Action-specific options (e.g., --agent.config, --coordinator.config, --target)

Outputs

Name	Type	Description
Trogdor process	JVM process	A running Trogdor agent, coordinator, or CLI client
Task results	JSON/stdout	For client actions, task status and results are printed to stdout

Usage Examples

Start Trogdor Agent

# Start a Trogdor agent on a cluster node
bin/trogdor.sh agent --agent.config config/trogdor.conf --node-name node0

Start Trogdor Coordinator

# Start the Trogdor coordinator
bin/trogdor.sh coordinator --coordinator.config config/trogdor.conf --node-name node0

Submit a Task via Client

# Use the client to create a task on the coordinator
bin/trogdor.sh client --target localhost:8889 createTask --id produce0 \
    --spec '{"class":"org.apache.kafka.trogdor.workload.ProduceBenchSpec","startMs":0,"durationMs":60000,"producerNode":"node0","bootstrapServers":"localhost:9092","targetTopic":"test-topic","maxMessages":10000}'

Show Help

# Display usage information
bin/trogdor.sh help

Related Pages

• Environment:Apache_Kafka_JVM_Runtime_Environment