Module: EzLogsAgent::EventBuilder

Defined in:
lib/ez_logs_agent/event_builder.rb

Overview

EventBuilder constructs valid Event hashes according to the Event Structure contract.

This is a pure, side-effect-free builder that:

  • Validates required fields

  • Validates enum values

  • Enforces conditional rules (outcome ↔ error_message)

  • Sanitizes sensitive data

  • Returns a valid Event hash

EventBuilder does NOT:

  • Buffer or send Events

  • Generate correlation IDs

  • Interact with Rails or ActiveRecord

  • Mutate global state

See Also:

  • for complete specification

Constant Summary collapse

SENSITIVE_KEYS =

Sensitive keys that should be filtered from source_data and context

%w[password token secret api_key credit_card].freeze
VALID_SOURCE_TYPES =

Valid source types

%w[http_request background_job database_callback].freeze
VALID_OUTCOMES =

Valid outcome values

%w[success failure].freeze

Class Method Summary collapse

Class Method Details

.build(source_type:, source_data:, outcome:, correlation_id: nil, resource_ids: [], context: nil, duration_ms: nil, error_message: nil, timestamp: nil) ⇒ Hash

Builds a valid Event hash

Examples:

Building an HTTP request event

EventBuilder.build(
  source_type: "http_request",
  source_data: { method: "POST", path: "/api/users", status_code: 201 },
  outcome: "success",
  duration_ms: 124
)

Parameters:

  • source_type (String, Symbol) —

    Event source type (http_request, background_job, database_callback)

  • source_data (Hash) —

    Technical details about the event source

  • outcome (String, Symbol) —

    Event outcome (success, failure)

  • correlation_id (String, nil) (defaults to: nil) —

    Optional correlation identifier

  • resource_ids (Array<Hash>) (defaults to: []) —

    Optional array of resource identifiers

  • context (Hash, nil) (defaults to: nil) —

    Optional human-readable context

  • duration_ms (Integer, nil) (defaults to: nil) —

    Optional operation duration in milliseconds

  • error_message (String, nil) (defaults to: nil) —

    Optional error message (required if outcome is failure)

  • timestamp (String, Time, nil) (defaults to: nil) —

    Optional timestamp (defaults to current time)

Returns:

  • (Hash) —

    Valid Event hash

Raises:

  • (ArgumentError) —

    If validation fails



55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
 
# File 'lib/ez_logs_agent/event_builder.rb', line 55

def self.build(
  source_type:,
  source_data:,
  outcome:,
  correlation_id: nil,
  resource_ids: [],
  context: nil,
  duration_ms: nil,
  error_message: nil,
  timestamp: nil
)
  # Validate and normalize inputs
  validated_source_type = validate_source_type!(source_type)
  validated_source_data = validate_source_data!(source_data)
  validated_outcome = validate_outcome!(outcome)
  validated_timestamp = validate_timestamp!(timestamp)
  validated_resource_ids = validate_resource_ids!(resource_ids)
  validated_context = validate_context!(context)
  validated_duration_ms = validate_duration_ms!(duration_ms)

  # Validate conditional rules
  validate_outcome_error_consistency!(validated_outcome, error_message)

  # Sanitize sensitive data
  sanitized_source_data = sanitize_hash(validated_source_data)
  sanitized_context = validated_context.nil? ? nil : sanitize_hash(validated_context)

  # Build and return Event hash
  {
    timestamp: validated_timestamp,
    source_type: validated_source_type,
    source_data: sanitized_source_data,
    outcome: validated_outcome,
    correlation_id: correlation_id,
    resource_ids: validated_resource_ids,
    context: sanitized_context,
    duration_ms: validated_duration_ms,
    error_message: error_message
  }
end