Generated reference

fault, field by field

The exact wire format for run files, live progress, completed results, and journal records. This page is generated from the Rust model beside the JSON Schemas; do not edit it by hand.

The smallest useful run

A run declares one or more proxies and an ordered list of phases. A phase without duration remains active until stopped and must be last.

schema_version: 1
name: slow database
proxies:
  - name: database
    protocol: tcp
    listen: 127.0.0.1:15432
    upstream: database.internal:5432
phases:
  - name: degraded
    proxies:
      - proxy: database
        faults:
          - type: latency
            flow: both
            distribution: { type: normal, mean_ms: 200, stddev_ms: 20 }

Fault and transport compatibility

Fault	TCP	UDP	Meaning
`latency`	yes	yes	Delay selected traffic using a sampled distribution.
`jitter`	yes	yes	Probabilistically delay selected traffic.
`bandwidth`	yes	no	Limit bytes per second for each connection stream.
`blackhole`	yes	yes	Leave TCP traffic pending or drop UDP datagrams.
`connection-reset`	yes	no	Reset a TCP connection when selected traffic is first used.
`dns`	no	yes	Alter DNS queries carried by a UDP proxy.

Run

Open the JSON Schema

Field	Required	Type and constraints	Description
`name`	yes	string (min length 1)	Human-readable name used in progress, results, and journals.
`phases`	yes	array of `Phase` (min items 1)	Ordered phases. Each begins when the previous phase ends.
`proxies`	yes	array of `Proxy` (min items 1)	Network entry points available throughout the run.
`schema_version`	yes	constant `1`	Version of the serialized run format. The current value is `1`.

DelayDistribution

Variant	Fields	Description
`normal`	`mean_ms`: number (min 0.0), `stddev_ms`: number (> 0.0)
`pareto`	`scale_ms`: number (> 0.0), `shape`: number (> 0.0)
`pareto-normal`	`normal_mean_ms`: number (min 0.0), `normal_stddev_ms`: number (> 0.0), `pareto_scale_ms`: number (> 0.0), `pareto_shape`: number (> 0.0)
`uniform`	`max_ms`: number (min 0.0), `min_ms`: number (min 0.0)

DnsCase

FaultSpec

Variant	Fields	Description
`latency`	`distribution`: `DelayDistribution`, `flow`: `TrafficFlow`	Adds one sampled delay to the selected direction. TCP applies it to the first non-empty traffic after activation; UDP applies it once to each selected datagram in an exchange.
`jitter`	`flow`: `TrafficFlow`, `max_delay_ms`: number (min 0.0), `min_delay_ms`: number (min 0.0), `probability`: number (min 0.0, max 1.0)	Adds a probabilistic sampled delay. TCP evaluates it per data operation; UDP evaluates it once for each selected datagram in an exchange.
`bandwidth`	`bytes_per_second`: integer (min 1), `flow`: `TrafficFlow`	Limits transferred bytes per second independently for each connection stream in the selected flow.
`blackhole`	`flow`: `TrafficFlow`	Leaves TCP operations pending until cancellation, or drops UDP datagrams in the selected direction.
`connection-reset`	`flow`: `TrafficFlow`, `probability`: number (min 0.0, max 1.0)	Resets a selected connection when traffic first uses the chosen flow.
`dns`	`case`: `DnsCase`, `delay_ms`: integer or null (min 0)	Alters DNS queries carried by a UDP proxy.

HumanDuration

HumanDuration: string (min length 1)

Phase

Field	Required	Type and constraints	Description
`duration`	no	`HumanDuration` or null	Omit to keep this phase active until explicitly stopped.
`name`	yes	string (min length 1)	Human-readable phase name exposed in progress events.
`proxies`	yes	array of `ProxyFaults`	Fault chains applied to named proxies during this phase.

Proxy

Field	Required	Type and constraints	Description
`listen`	yes	string	Local socket address clients connect or send datagrams to.
`name`	yes	string (min length 1)	Stable name used by phases to select this proxy.
`protocol`	yes	`TransportProtocol`	Transport accepted and forwarded by this proxy.
`upstream`	yes	string	Remote socket address to which traffic is forwarded.

ProxyFaults

Field	Required	Type and constraints	Description
`faults`	yes	array of `FaultSpec`	Ordered chain of faults applied to traffic on this proxy.
`proxy`	yes	string (min length 1)	Name of a proxy declared by the containing run.

TrafficFlow

Variant	Fields	Description
`to-upstream`		Traffic sent by the client toward the upstream service.
`to-client`		Traffic returned by the upstream service toward the client.
`both`		Traffic in both directions.

TransportProtocol

Variant	Fields	Description
`tcp`		A connection-oriented byte stream.
`udp`		Connectionless datagrams, including DNS traffic.

RunProgress

A lightweight phase transition published while a run executes.

Open the JSON Schema

Field	Required	Type and constraints	Description
`phase_count`	yes	integer (min 1)
`phase_duration_ms`	no	integer or null (min 0)	Planned duration, or absent for an indefinite final phase.
`phase_index`	yes	integer (min 1)	One-based position of the active phase.
`phase_name`	yes	string	Name of the phase that has just started.
`phase_started_at`	yes	string	UTC instant at which the phase became active.
`proxies`	yes	array of `ProxyFaults`	Fault chains active for this phase.
`run_name`	yes	string	Name of the executing run.

RunResult

Open the JSON Schema

Field	Required	Type and constraints	Description
`completed_at`	yes	string	UTC instant at which execution ended.
`outcome`	yes	`RunOutcome`	Whether the run completed successfully or failed.
`run_name`	yes	string	Name of the completed run.
`schema_version`	yes	constant `1`	Version of the serialized result format. The current value is `1`.
`started_at`	yes	string	UTC instant at which execution began.
`transport`	yes	`TransportSummary`	Aggregate TCP and UDP observations collected during the run.

DelayRecord

Field	Required	Type and constraints	Description
`applications`	yes	integer (min 0)
`total_delay_ms`	yes	number

FaultRecord

Field	Required	Type and constraints
`bandwidth_bytes_limited`	yes	integer (min 0)
`blackhole_activations`	yes	integer (min 0)
`connection_resets`	yes	integer (min 0)
`dns_interventions`	yes	integer (min 0)
`jitter`	yes	`DelayRecord`
`latency`	yes	`DelayRecord`

FaultStatus

Field	Required	Type and constraints
`average_jitter_ms`	yes	number
`average_latency_ms`	yes	number
`jitter_applications`	yes	integer (min 0)
`latency_applications`	yes	integer (min 0)

RunOutcome

Variant	Fields	Description
`success`
`failed`	`message`: string

TcpStreamOutcome

TcpStreamRecord

Field	Required	Type and constraints
`bytes_to_client`	yes	integer (min 0)
`bytes_to_upstream`	yes	integer (min 0)
`closed_at`	no	string or null
`failure`	no	`TransportFailure` or null
`faults`	yes	`FaultRecord`
`opened_at`	yes	string
`outcome`	yes	`TcpStreamOutcome`
`peer`	yes	string
`proxy`	yes	string
`stream_id`	yes	string
`upstream`	yes	string

TcpStreamStatus

Field	Required	Type and constraints
`active`	yes	integer (min 0)
`active_impacted`	yes	integer (min 0)
`average_bytes_to_client`	yes	integer (min 0)
`average_bytes_to_upstream`	yes	integer (min 0)
`completed`	yes	integer (min 0)
`failed`	yes	integer (min 0)
`impacted`	yes	integer (min 0)
`opened`	yes	integer (min 0)

TransportFailure

Field	Required	Type and constraints
`category`	yes	`TransportFailureCategory`
`message`	yes	string
`stage`	yes	`TransportFailureStage`

TransportFailureCategory

TransportFailureStage

TransportFailureStage: connect | transfer | exchange

TransportStatus

Field	Required	Type and constraints	Description
`dropped_records`	yes	integer (min 0)	Completed records omitted from the best-effort event stream.
`effects`	yes	`FaultStatus`
`last_failure`	no	`TransportFailure` or null
`tcp`	yes	`TcpStreamStatus`
`udp`	yes	`UdpExchangeStatus`

TransportSummary

Field	Required	Type and constraints
`status`	yes	`TransportStatus`
`tcp_streams`	yes	array of `TcpStreamRecord`
`udp_exchanges`	yes	array of `UdpExchangeRecord`

UdpExchangeOutcome

UdpExchangeOutcome: active | completed | transfer-failed | cancelled | fault-dropped

UdpExchangeRecord

Field	Required	Type and constraints
`completed_at`	no	string or null
`exchange_id`	yes	string
`failure`	no	`TransportFailure` or null
`faults`	yes	`FaultRecord`
`outcome`	yes	`UdpExchangeOutcome`
`peer`	yes	string
`proxy`	yes	string
`request_bytes`	yes	integer (min 0)
`response_bytes`	yes	integer (min 0)
`started_at`	yes	string
`upstream`	yes	string

UdpExchangeStatus

Field	Required	Type and constraints
`active`	yes	integer (min 0)
`active_impacted`	yes	integer (min 0)
`average_request_bytes`	yes	integer (min 0)
`average_response_bytes`	yes	integer (min 0)
`completed`	yes	integer (min 0)
`failed`	yes	integer (min 0)
`impacted`	yes	integer (min 0)
`started`	yes	integer (min 0)

JournalEvent

Open the JSON Schema

Variant	Fields	Description
`run-started`	`faults`: array of `ProxyFaults`, `name`: string or null, `proxies`: array of `Proxy`, `schema_version`: constant `1`, `started_at`: string
`tcp-stream-completed`	`stream`: `TcpStreamRecord`
`udp-exchange-completed`	`exchange`: `UdpExchangeRecord`
`run-completed`	`completed_at`: string, `status`: `TransportStatus`

Regenerate with cargo run -p fault-model --example generate_schemas.