Config Events¶
Config Events provide a mechanism to record noteworthy occurrences during the configuration lifecycle that are not exceptional enough to interrupt program flow but may require programmatic handling or reporting.
"severity below Exception, above logging"
Example: Parsing of a discovered file fails. This happens often enough (typo), is no reason to abort operation, but logging alone may go unnoticed by users (invisible, no logger).
Key Concepts¶
- Domain: Broad category of the event (e.g.,
PARSE,DISCOVERY,WRITE). - Kind: Specific classification within a domain (e.g.,
UNSUPPORTED_SYNTAX,SKIPPED_PERMISSION_DENIED). - Severity: Importance of the event (
INFO,NOTICE,WARNING,ERROR). - Remediation: Programmatic hint for resolving the issue (e.g.,
CHANGE_FORMAT,FIX_SYNTAX). - Attributes: Machine-readable metadata (e.g.,
line,column,filePath).
Feature Flags¶
EVENTS_DETAIL_LEVEL: Gating level for event recording.OFF: No events recorded.FAILURES_ONLY(Default): Only failures and blockers (e.g., parse errors).NORMAL: Adds important informational events (e.g., merge overrides).VERBOSE: Includes high-volume events (e.g., watcher notifications).EVENTS_MAX_FACTORY: Max events to retain at theConfigFactorylevel (Default: 1000).EVENTS_MAX_CONFIGURATION: Max events to retain perConfiguration(Default: 1000).EVENTS_DEDUP_RECENT_LIMIT: Size of the ring buffer used to suppress recent duplicate events (Default: 32).
Programmatic Access¶
Events can be retrieved from the ConfigFactory or individual Configuration instances:
List<ConfigEvent> factoryEvents = factory.getEvents();
List<ConfigEvent> configEvents = config.getEvents();
Example: JSON with Comments¶
When JSONwithJacksonFormat encounters a file with // comments, it emits a PARSE/UNSUPPORTED_SYNTAX event:
for (ConfigEvent ev : factory.getEvents()) {
if (ev.getKind() == ConfigEvent.Kind.UNSUPPORTED_SYNTAX) {
System.out.println("Hint: " + ev.getRemediationMessage());
// Remediation: CHANGE_FORMAT
}
}
Example: Unavailable Sources¶
When a source cannot be read (Vault or AWS Secrets Manager unreachable or refusing access, a Kubernetes
API error, a failing secrets provider), mConfig logs a WARNING and records a DISCOVERY/SOURCE_UNAVAILABLE
event naming the location (since 0.8.16). Lower-precedence sources may then supply the value, so the event
is the way to notice that a value did not come from where it should have. It counts as a failure for
FAILURES_ONLY.
factory.getEvents().stream()
.filter(ev -> ev.getKind() == ConfigEvent.Kind.SOURCE_UNAVAILABLE)
.forEach(ev -> System.err.println(ev.getDetailCode()+": "+ev.getMessage()));
Cleanup¶
To clear accumulated events:
factory.getEvents().clean();
CLI Usage¶
The mconfig tool can display events using the --show-events (or -E) flag.
This is particularly useful for diagnosing why certain configuration files are being ignored:
mconfig --config myapp --show-events show