ExESDB.OperationalMessageHelpers (ex_esdb v0.11.0)

Common utilities for ExESDB operational message creation and handling.

This module provides consistent patterns for operational/system messages to ensure compatibility with ExESDBGater messaging patterns. This is SEPARATE from application domain events that flow through :ex_esdb_events.

Scope

This module handles operational messages for:

  • System lifecycle and configuration (:ex_esdb_system)
  • Health monitoring (:ex_esdb_health)
  • Performance metrics (:ex_esdb_metrics)
  • Security events (:ex_esdb_security)
  • Audit trail (:ex_esdb_audit)
  • Critical alerts (:ex_esdb_alerts)
  • Diagnostic information (:ex_esdb_diagnostics)
  • Process lifecycle (:ex_esdb_lifecycle)
  • Log aggregation (:ex_esdb_logging)

Node Field Guidelines

All operational message structs should include node tracking:

  • :node - for general operational events originating on a node
  • :source_node - for ExESDB-specific events where source context is important
  • :originating_node - for cluster events where distinction is needed from affected nodes

Integration with ExESDBGater

This module ensures ExESDB operational messages are compatible with ExESDBGater message formats, enabling seamless integration between the two systems.

Usage

# Create operational health message
health_payload = OperationalMessageHelpers.create_health_message(
  :store_worker, :healthy, %{store_id: :main_store}
)

# Create system lifecycle message  
lifecycle_payload = OperationalMessageHelpers.create_system_lifecycle(
  :started, :ex_esdb, version
)

Summary

Functions

cluster_context()

Extracts ExESDB cluster context information for enhanced operational message tracking.

create_alert_message(severity, category, title, description, opts \\ [])

Creates ExESDBGater-compatible alert message payload.

create_health_message(component, status, details \\ %{}, opts \\ [])

Creates ExESDBGater-compatible health message payload.

create_metrics_message(component, metrics_data, opts \\ [])

Creates ExESDBGater-compatible metrics message payload.

create_system_lifecycle(event, system_name, version, opts \\ [])

Creates ExESDBGater-compatible system lifecycle message payload.

current_timestamp()

Returns the current timestamp with millisecond precision in UTC.

generate_operational_id(prefix \\ "op")

Creates a unique identifier for operational messages that need tracking.

get_node(opts \\ [])

Gets the node value from options, defaulting to Node.self().

get_originating_node(opts \\ [])

Gets the originating_node value from options, defaulting to Node.self().

get_source_node(opts \\ [])

Gets the source_node value from options, defaulting to Node.self().

validate_node_fields(message)

Validates that all node-related fields in an operational message are atoms.

validate_operational_fields(message, required_fields)

Validates that an operational message has all required fields.

validate_operational_message(message, required_fields)

Common validation for operational messages.

Functions

cluster_context()

Extracts ExESDB cluster context information for enhanced operational message tracking.

This provides additional context that can be useful for debugging and monitoring ExESDB cluster operations.

create_alert_message(severity, category, title, description, opts \\ [])

Creates ExESDBGater-compatible alert message payload.

create_health_message(component, status, details \\ %{}, opts \\ [])

Creates ExESDBGater-compatible health message payload.

This bridges ExESDB health information to ExESDBGater HealthMessages format.

create_metrics_message(component, metrics_data, opts \\ [])

Creates ExESDBGater-compatible metrics message payload.

create_system_lifecycle(event, system_name, version, opts \\ [])

Creates ExESDBGater-compatible system lifecycle message payload.

current_timestamp()

Returns the current timestamp with millisecond precision in UTC.

This ensures consistent timestamp formatting across all operational message types and maintains compatibility with ExESDBGater messaging patterns.

generate_operational_id(prefix \\ "op")

Creates a unique identifier for operational messages that need tracking.

get_node(opts \\ [])

Gets the node value from options, defaulting to Node.self().

Examples

iex> OperationalMessageHelpers.get_node([])
:"node@hostname"

iex> OperationalMessageHelpers.get_node([node: :test_node])
:test_node

get_originating_node(opts \\ [])

Gets the originating_node value from options, defaulting to Node.self().

Used for cluster operational events where the originating node needs to be distinguished from affected nodes.

get_source_node(opts \\ [])

Gets the source_node value from options, defaulting to Node.self().

Used for ExESDB-specific operational events where source context is important.

validate_node_fields(message)

Validates that all node-related fields in an operational message are atoms.

validate_operational_fields(message, required_fields)

Validates that an operational message has all required fields.

validate_operational_message(message, required_fields)

Common validation for operational messages.

Ensures messages follow both ExESDB and ExESDBGater compatibility requirements.