Diagnostics - Eventvisor

Diagnostics are structured reports from the SDK and its modules. They make rejected events, invalid configuration, missing capabilities, and delivery failures observable without replacing application logging.

const eventvisor = createEventvisor({
  datafile,
  logLevel: "warn",
  onDiagnostic(diagnostic) {
    observability.capture(diagnostic);
  },
});
const unsubscribe = eventvisor.onDiagnostic((diagnostic) => {
  console.log(diagnostic.level, diagnostic.code, diagnostic.message);
});

Each diagnostic contains level, code, message, and details. Module reports include moduleName, and failures can include the original error. Error diagnostics also emit the SDK error event.

Stable codes#

Codes are intended for monitoring and alerting. Important families include:

Area	Examples
Datafiles and initialization	`invalid_datafile`, `initialization_failed`
Events and attributes	`event_not_found`, `event_validation_failed`, `attribute_not_found`, `attribute_validation_failed`
Conditions and sampling	`conditions_parse_failed`, `condition_evaluation_failed`, `sample_by_invalid`
Transforms	`transform_conversion_failed`, `transform_invalid_input`, `transform_output_invalid`
Effects	`effect_handler_failed`, `effect_reentrancy_blocked`
Modules	`duplicate_module`, `module_setup_failed`, `module_transport_failed`, `module_flush_failed`
Queueing transports	`http_queue_full`, `http_delivery_failed`, `beacon_queue_full`, `beacon_delivery_failed`

Treat codes as identifiers. Human readable messages may gain more context over time.

Module authors can subscribe and report through the module API:

setup(api) {
  const unsubscribe = api.onDiagnostic(handleDiagnostic);
  api.reportDiagnostic({
    level: "info",
    code: "custom_ready",
    message: "Custom module is ready",
    details: {},
  });
}

Subscriptions created through a module API are removed when that module is removed or the instance is closed.