ChaosBlade Documentation

ChaosBlade is an open-source chaos engineering toolkit designed to improve the fault tolerance of distributed systems. It supports a wide range of experimental scenarios including:

• Basic Resources: CPU, memory, network, disk, and processes.
• Java Applications: Databases, caches, messages, JVM, and microservices (via Java Agent).
• C++ Applications: Method and code line level injection (via GDB).
• Containers: Docker container resource and process scenarios.
• Cloud-Native (Kubernetes): Node, Pod, and Container level scenarios via the chaosblade-operator.

BLADE AI is the intelligent agent layer for the ChaosBlade ecosystem. It acts as an intelligent assistant that orchestrates ChaosBlade to perform fault injection through natural language rather than manual commands.

Key distinctions:

• ChaosBlade is the injection engine (handles how to inject, e.g., K8s Pod CPU stress or network packet loss).
• BLADE AI is the orchestration layer (handles how to safely and completely complete an experiment). It manages intent understanding, safety reviews, effect verification, safe recovery, and structured reporting.

The BLADE AI workflow follows a closed loop: Intent → Safety → Injection → Verification → Recovery.

Chaosblade commands follow a specific logical flow: blade <command> <model> <action>.

1. Primary Commands: Basic operations like version, prepare, revoke, and create.
2. Model Objects (Nouns): These represent the target of the fault injection (e.g., cpu, disk, network, mem, jvm, k8s, or docker). These are implemented via the ExpModelCommandSpec interface.
3. Actions (Verbs): These are the specific operations performed on a model (e.g., fullload for cpu, or delay/drop for network). These are implemented via the ExpActionCommandSpec interface.

Example: blade create cpu fullload targets the cpu model to perform a fullload action.

BLADE AI is an orchestration layer that sits on top of the ChaosBlade ecosystem. It does not replace ChaosBlade; instead, it acts as an intelligent assistant to make fault injection safer and more automated.

Key distinctions:

• ChaosBlade: The injection engine. It handles the technical implementation of how to inject faults (e.g., applying CPU pressure to a K8s Pod or dropping network packets).
• BLADE AI: The orchestration layer. It handles the lifecycle of a fault drill, including intent understanding, safety reviews, effect verification, and reliable recovery.

Use BLADE AI when you want to describe a fault in plain English rather than memorizing specific CLI flags and manual verification steps.

Chaosblade experiments are structured around a four-part model to ensure precision and control the 'explosion radius' of a fault. When designing or using an experiment, identify these four components:

1. Target: The component being experimented on (e.g., container, dubbo, redis, network).
2. Scope: The specific machine or cluster where the experiment is triggered. Note that for the blade CLI, the scope defaults to the local machine.
3. Matcher: Rules used to identify the specific instance to affect (e.g., matching a specific Dubbo service name, a specific IP, or a specific port).
4. Action: The specific fault scenario to simulate (e.g., delay, exception, disk full, packet loss).

Chaosblade uses a structured model to define chaos experiments, ensuring precise control over the blast radius. An experiment is composed of four key elements:

• Target: The component being experimented on (e.g., dubbo, network, cpu, disk, redis).
• Scope: The execution range, such as a specific host or cluster. Note that for the blade CLI, the scope defaults to the local machine.
• Matcher: Rules used to match specific traffic or components (e.g., matching a specific Dubbo service name or a specific network port).
• Action: The specific fault scenario to simulate (e.g., delay, loss, fullload).

Example logic flow: Target (dubbo) -> Scope (local host) -> Matcher (service com.example.HelloService) -> Action (delay 3000ms).

BLADE AI uses a LangGraph-based three-phase ReAct state machine to manage fault injection workflows. This separation ensures stability and prevents prompt bloat by giving each phase a specific focus, toolset, and loop limit:

1. Phase 1: Planning — Translates natural language intent into an execution plan. It matches skills, queries target states, and requires rich context (skill directories, K8s resource info).
2. Phase 2: Execution — Calls ChaosBlade to create experiments and verifies the immediate return. Focuses on precise tool calls and error handling.
3. Phase 3: Verification — Confirms the fault is actually active and can be recovered. Uses time-based strategies like delayed waiting and polling.

If Phase 2 fails due to recoverable errors (e.g., missing resources), the system can trigger a Replan (up to 3 attempts) to return to Phase 1.