# Best Practices for Organizing and Naming Chaos Experiments in ChaosBlade

> Master organizing and naming ChaosBlade experiments. Learn best practices for target action tuples and command specifications to streamline your chaos engineering. Optimize your experiments today.

- Repository: [ChaosBlade/chaosblade](https://github.com/chaosblade-io/chaosblade)
- Tags: best-practices
- Published: 2026-02-27

---

**ChaosBlade organizes chaos experiments using a strict target-action tuple where targets are nouns (e.g., network, docker) and actions are verbs (e.g., delay, kill), enforced through the ExpModelCommandSpec and ExpActionCommandSpec interfaces in the exec/ directory.**

Organizing and naming chaos experiments consistently is critical for maintaining readable, maintainable chaos engineering suites. In the chaosblade-io/chaosblade repository, the project enforces a rigid semantic model that governs how experiments are structured, named, and extended. This guide explains the proven conventions derived from the source code that keep the CLI predictable and the codebase modular.

## Understanding the ChaosBlade Experiment Model

The foundation of organizing chaos experiments in ChaosBlade rests on a four-part tuple: **target → scope → matcher → action**. This model is formally defined in [`docs/chaos_experiment_model_EN.md`](https://github.com/chaosblade-io/chaosblade/blob/main/docs/chaos_experiment_model_EN.md) and implemented through three core interfaces in the Go source code:

- `ExpModelCommandSpec` – Defines the target (noun)
- `ExpActionCommandSpec` – Defines the action (verb) and its matchers
- `ExpFlagSpec` – Defines parameters for both matchers and actions

In `exec/<target>/spec.go`, the target specification returns a slice of action specifications, creating a hierarchical relationship that the CLI renders as subcommands. For example, the network target in [`exec/network/spec.go`](https://github.com/chaosblade-io/chaosblade/blob/main/exec/network/spec.go) groups actions like `delay`, `loss`, and `dns`.

## Naming Conventions for Targets and Actions

ChaosBlade enforces a strict linguistic pattern documented in [`docs/logic_flow_Introduction_EN.md`](https://github.com/chaosblade-io/chaosblade/blob/main/docs/logic_flow_Introduction_EN.md): **targets are nouns, actions are verbs**.

### Target Naming (Nouns)

Targets represent the component under test and must be concrete nouns:

- `network` – Network interfaces and traffic
- `docker` – Docker containers
- `k8s` – Kubernetes resources
- `jvm` – Java virtual machine
- `dubbo` – Dubbo services

In `exec/<target>/spec.go`, the `Name()` method returns this noun, which becomes the first-level subcommand in the CLI.

### Action Naming (Verbs)

Actions describe the fault being injected and must be verbs:

- `delay` – Add latency
- `loss` – Drop packets
- `kill` – Terminate processes
- `fullload` – Generate resource exhaustion
- `corrupt` – Damage data

In `exec/<target>/<action>_executor.go`, the executor implementation follows the naming convention `<Target><Action>Executor` (e.g., `NetworkDelayExecutor`).

## Repository Organization and File Structure

The directory layout in `chaosblade-io/chaosblade` mirrors the target-action model, making it straightforward to locate and extend experiments.

### Target Directories

Each target resides in its own package under `exec/`:

```

exec/
├── network/
│   ├── spec.go          # NetworkCommandSpec

│   ├── delay.go         # DelayActionSpec + executor

│   └── loss.go          # LossActionSpec + executor

├── docker/
│   ├── spec.go
│   └── container_kill.go
└── k8s/
    ├── spec.go
    └── pod_kill.go

```

### Key Files and Their Roles

| File | Purpose | Naming Convention |
|------|---------|-----------------|
| `exec/<target>/spec.go` | Declares `*TargetCommandSpec` and lists available actions | Lower-case directory matching target noun |
| `exec/<target>/executor.go` | Implements `Executor` interface for actions | `<Target><Action>Executor` struct name |
| [`cli/cmd/exp.go`](https://github.com/chaosblade-io/chaosblade/blob/main/cli/cmd/exp.go) | Registers all targets with Cobra CLI | Uses `createExecutorKey(target, action)` generating `target-action` keys |
| [`cli/cmd/create.go`](https://github.com/chaosblade-io/chaosblade/blob/main/cli/cmd/create.go) | Parses flags into `ExpModel.ActionFlags` | Iterates via `cmd.Flags().VisitAll` |
| [`data/experiment.go`](https://github.com/chaosblade-io/chaosblade/blob/main/data/experiment.go) | Persists experiment metadata | Column names mirror CLI flag names (snake_case) |

## Flag Naming and Matcher Patterns

Flags in ChaosBlade follow strict conventions to ensure consistency across the CLI and the underlying data model.

### Flag Naming Rules

As defined in [`docs/chaos_experiment_model_EN.md`](https://github.com/chaosblade-io/chaosblade/blob/main/docs/chaos_experiment_model_EN.md) and implemented in [`cli/cmd/create.go`](https://github.com/chaosblade-io/chaosblade/blob/main/cli/cmd/create.go), flags must be:

- **Lower-case, hyphen-separated** (e.g., `--cpu-percent`, `--container-id`)
- **Consistent across interfaces** – the `ExpFlag.Name` in the spec matches the Cobra flag name exactly
- **Marked required explicitly** – set `Required: true` in the `ExpFlagSpec` definition so Cobra enforces presence

### Matcher vs. Action Flags

The model distinguishes between two flag types:

**Matchers** (filtering criteria):
- Defined in the action spec's `Matchers()` method
- Examples: `--consumer`, `--service`, `--pid`, `--device`
- Narrow the blast radius before fault injection

**Action Flags** (injection parameters):
- Defined in the action spec's `Flags()` method
- Examples: `--time`, `--offset`, `--cpu-percent`
- Control the specific behavior of the fault

In [`cli/cmd/create.go`](https://github.com/chaosblade-io/chaosblade/blob/main/cli/cmd/create.go), the `createExpModel` function automatically populates `ActionFlags` by visiting all non-boolean flags, ensuring no manual duplication is needed.

## Extending ChaosBlade with New Experiments

Adding a new chaos experiment requires following the established organizational patterns to maintain CLI consistency and code readability.

### Step 1: Create the Target Specification

Create `exec/<target>/spec.go` implementing `ExpModelCommandSpec`:

```go
type DiskCommandSpec struct{}

func (*DiskCommandSpec) Name() string { 
    return "disk"  // noun
}

func (*DiskCommandSpec) Actions() []exec.ExpActionCommandSpec {
    return []exec.ExpActionCommandSpec{
        &CorruptActionSpec{},
    }
}

```

### Step 2: Define the Action Specification

Create `exec/<target>/<action>.go` implementing `ExpActionCommandSpec`:

```go
type CorruptActionSpec struct{}

func (*CorruptActionSpec) Name() string { 
    return "corrupt"  // verb
}

func (*CorruptActionSpec) Matchers() []exec.ExpFlagSpec {
    return []exec.ExpFlagSpec{
        &exec.ExpFlag{Name: "path", Desc: "file path to corrupt", Required: true},
    }
}

func (*CorruptActionSpec) Flags() []exec.ExpFlagSpec {
    return []exec.ExpFlagSpec{
        &exec.ExpFlag{Name: "bytes", Desc: "number of bytes to overwrite", Required: true},
    }
}

func (*CorruptActionSpec) Executor(channel exec.Channel) exec.Executor {
    return &DiskCorruptExecutor{channel}
}

```

### Step 3: Implement the Executor

Create `exec/<target>/<action>_executor.go`:

```go
type DiskCorruptExecutor struct {
    channel exec.Channel
}

func (dce *DiskCorruptExecutor) Exec(uid string, ctx context.Context, model *spec.ExpModel) *spec.Response {
    // Implementation here
    return dce.channel.Run(ctx, "corrupt", model.ActionFlags)
}

```

### Step 4: Registration

The [`cli/cmd/exp.go`](https://github.com/chaosblade-io/chaosblade/blob/main/cli/cmd/exp.go) file automatically registers any new target via the `AddCommand` method. No additional registration is required if the target spec is properly placed in `exec/`.

After these steps, the command `blade create disk corrupt --path /var/log/app.log --bytes 1024` becomes available immediately.

## Summary

- **ChaosBlade uses a strict target-action tuple** (noun-verb) defined in [`docs/chaos_experiment_model_EN.md`](https://github.com/chaosblade-io/chaosblade/blob/main/docs/chaos_experiment_model_EN.md) and implemented via `ExpModelCommandSpec` and `ExpActionCommandSpec`.
- **Targets are always nouns** (e.g., `network`, `docker`, `k8s`) and reside in `exec/<target>/spec.go`.
- **Actions are always verbs** (e.g., `delay`, `kill`, `corrupt`) with executors named `<Target><Action>Executor`.
- **Flags are lower-case and hyphen-separated** (e.g., `--cpu-percent`), defined in the action spec's `Matchers()` and `Flags()` methods.
- **Extending the suite** requires only adding files to `exec/<target>/` following the established patterns; [`cli/cmd/exp.go`](https://github.com/chaosblade-io/chaosblade/blob/main/cli/cmd/exp.go) handles registration automatically.

## Frequently Asked Questions

### How does ChaosBlade enforce the noun-verb naming convention?

The convention is documented in [`docs/logic_flow_Introduction_EN.md`](https://github.com/chaosblade-io/chaosblade/blob/main/docs/logic_flow_Introduction_EN.md) and enforced structurally through the interface design. The `ExpModelCommandSpec` interface requires a `Name()` method that returns the target (noun), while `ExpActionCommandSpec` requires a `Name()` method that returns the action (verb). The CLI construction in [`cli/cmd/exp.go`](https://github.com/chaosblade-io/chaosblade/blob/main/cli/cmd/exp.go) concatenates these values to form commands like `blade create network delay`, making the grammatical structure visible to users.

### What is the difference between matchers and action flags in ChaosBlade?

**Matchers** are filtering criteria defined in the `Matchers()` method of an action spec that narrow the blast radius before injection, such as `--service`, `--consumer`, or `--device`. **Action flags** are parameters that control the fault behavior itself, defined in the `Flags()` method, such as `--time`, `--offset`, or `--cpu-percent`. In [`cli/cmd/create.go`](https://github.com/chaosblade-io/chaosblade/blob/main/cli/cmd/create.go), both are parsed into the `ExpModel.ActionFlags` map, but they serve distinct semantic purposes in the experiment definition.

### Where should I place files when adding a new chaos experiment target?

New targets belong in a dedicated package under `exec/<target>/`, following the pattern established by existing modules like `exec/network/` or `exec/docker/`. You must create [`spec.go`](https://github.com/chaosblade-io/chaosblade/blob/main/spec.go) to implement `ExpModelCommandSpec`, individual action files (e.g., [`delay.go`](https://github.com/chaosblade-io/chaosblade/blob/main/delay.go)) to implement `ExpActionCommandSpec`, and `<action>_executor.go` files for the `Executor` implementation. The [`cli/cmd/exp.go`](https://github.com/chaosblade-io/chaosblade/blob/main/cli/cmd/exp.go) file automatically discovers and registers these packages, requiring no manual updates to the command registry.

### How does ChaosBlade ensure flag consistency across the CLI and data persistence?

Flag consistency is enforced by convention and implementation. In the source code, flag names defined in `ExpFlagSpec` implementations (e.g., `cpu-percent`, `container-id`) use lower-case, hyphen-separated formatting. These same names are used as keys in the `ExpModel.ActionFlags` map populated by [`cli/cmd/create.go`](https://github.com/chaosblade-io/chaosblade/blob/main/cli/cmd/create.go). When persisting experiment metadata in [`data/experiment.go`](https://github.com/chaosblade-io/chaosblade/blob/main/data/experiment.go), column names mirror these CLI flag names (using snake_case for database compatibility), ensuring traceability from command-line invocation through to stored experiment records.