Configuration reference

All configuration keys are under the quarkus.goblin prefix.

The chaos layers are not configuration keys: every application starts with HTTP_IN and HTTP_OUT armed, and the layers are armed at runtime from the Dev UI or through JSON-RPC (applyConfig with a layers array); in dev mode the choice is persisted in .goblin-state.json. DATABASE requires a JDBC datasource and MESSAGING requires quarkus-messaging.

Every key is read at runtime and can be overridden when the application starts (environment variable, system property, profile), except the three quarkus.goblin.target.include-packages / exclude-packages / exclude-annotations targeting rules: they decide at build time which beans receive the service and messaging interceptors, so they are fixed at build time (a dev-mode live reload rebuilds the application and picks them up).

Key Type Default Description

quarkus.goblin.enabled

boolean

true

Enable/disable the Goblin extension. Takes effect in dev mode, and in test mode together with quarkus.goblin.test.enabled. Never overridden by the persisted state file; disabling this property keeps chaos off even if a previous session left assault toggles enabled.

quarkus.goblin.test.enabled

boolean

false

Whether chaos is active in test mode (@QuarkusTest). Off by default so the extension never slows down nor breaks an application’s test suite; the engine still loads its configuration, and a test can switch chaos on with AssaultEngine.setActive(true).

quarkus.goblin.assault.type

AssaultType

LATENCY

Initial assault type enabled at startup. Values: LATENCY, EXCEPTION, HTTP_STATUS, DEPENDENCY_DEGRADATION, RESPONSE_BODY, RESPONSE_HEADER. Can be changed at runtime via the Dev UI. Ignored when a non-NONE profile is selected.

quarkus.goblin.assault.profile

AssaultProfile

NONE

Predefined composite assault mode. Values: NONE, SLOW_FAILURE, INTERMITTENT, TIMEOUT. A non-NONE profile enables a set of assaults with sensible defaults; individual assaults stay user-overridable afterwards. Can be changed at runtime via the Dev UI.

quarkus.goblin.assault.latency.min-milliseconds

long

100

Minimum latency in milliseconds. Must be lower than or equal to max-milliseconds; inverted values are swapped with a WARN log

quarkus.goblin.assault.latency.max-milliseconds

long

5000

Maximum latency in milliseconds

quarkus.goblin.assault.exception.type

String

java.lang.RuntimeException

Fully qualified exception class name. Must extend RuntimeException and have a public String constructor; otherwise the engine falls back to RuntimeException with an ERROR log

quarkus.goblin.assault.exception.message

String

Goblin chaos: simulated exception

Exception message

quarkus.goblin.assault.http-status.code

int

503

HTTP status code to return. Must be in the 100-599 range; out-of-range values default to 503 with an ERROR log

quarkus.goblin.assault.http-status.message

String

Service Unavailable (Goblin chaos)

HTTP response body

quarkus.goblin.assault.body.mode

ResponseBodyMode

TRUNCATE

Response body transformation to apply. Values: TRUNCATE (keep the first percentage% of the body), INFLATE (pad the body up to percentage% of its original size).

quarkus.goblin.assault.body.percentage

int

50

Target size of the transformed body in percent of the original, rounded down (floor). Valid range: 0-100 for TRUNCATE, 101-1000 for INFLATE. Out-of-range values are clamped with a WARN log.

quarkus.goblin.assault.headers.<name>.action

ResponseHeaderAction

SET

Action applied to the <name> response header. Values: SET (force the header with the configured value, replacing any existing one or adding it when absent), REMOVE (delete the header when present). Any other value is rejected at startup as a configuration error.

quarkus.goblin.assault.headers.<name>.value

String

empty

Header value written by the SET action. Ignored by REMOVE.

quarkus.goblin.target.level

int

100

Percentage of requests to affect (0-100; values are clamped with a WARN log)

quarkus.goblin.target.include-packages

Optional<List<String>>

empty

Package prefixes to include (empty = all packages). Fixed at build time.

quarkus.goblin.target.exclude-packages

Optional<List<String>>

empty

Package prefixes to exclude from chaos; an exclusion always wins over an inclusion. Fixed at build time.

quarkus.goblin.target.exclude-annotations

Optional<List<String>>

empty

Exclude methods/classes carrying these annotations (every layer). Fixed at build time.

Configuration validation

Goblin validates assault parameters at startup and whenever you save a change in the Dev UI. Invalid values are never applied: Goblin logs a clear message and applies a safe fallback, so a misconfiguration cannot silently corrupt your chaos experiments.

Parameter

Rule

What happens

assault.latency.min-milliseconds / assault.latency.max-milliseconds

min must be lower than or equal to max, both within 0-300000

Out-of-range values are clamped, inverted values are swapped, and a WARN is logged

assault.http-status.code

Must be in the 100-599 range

Defaults to 503 and an ERROR is logged

assault.exception.type

Class must exist, extend RuntimeException and expose a String constructor

Falls back to RuntimeException and an ERROR is logged

assault.body.percentage

Must be in 0-100 for TRUNCATE, 101-1000 for INFLATE

Clamped to the valid range and a WARN is logged

target.level

Must be in the 0-100 range

Clamped and a WARN is logged

At startup the checks run in AssaultEngine.onStart() and cover both the application.properties configuration and the state loaded from .goblin-state.json. When you edit a parameter in the Dev UI, the same rules apply: the corrected value is persisted back to .goblin-state.json, and the dashboard shows a warning toast explaining what changed — for example, entering min=10000, max=500 swaps them to min=500, max=10000.