Jido.Messaging.Signal (Jido Messaging v1.0.0)

Copy Markdown View Source

Signal emission for messaging events using dual-emission pattern.

Emits both:

  • :telemetry events for metrics and instrumentation
  • Jido.Signal CloudEvents for domain events with causality tracking

Telemetry Events

  • [:jido_messaging, :message, :received] - when a message is ingested
  • [:jido_messaging, :message, :sent] - when a message is delivered successfully
  • [:jido_messaging, :message, :failed] - when delivery fails

Jido.Signal CloudEvents

  • jido.messaging.message.received - message ingested
  • jido.messaging.message.sent - message delivered
  • jido.messaging.message.failed - delivery failed
  • jido.messaging.agent.triggered - agent trigger detected
  • jido.messaging.agent.started - agent execution started
  • jido.messaging.agent.completed - agent execution completed
  • jido.messaging.agent.failed - agent execution failed
  • jido.messaging.instance.* - instance lifecycle events

Usage

To attach a telemetry handler:

:telemetry.attach(
  "my-handler",
  [:jido_messaging, :message, :received],
  &MyHandler.handle_event/4,
  nil
)

To subscribe to Jido.Signal events:

Jido.Signal.Bus.subscribe(MyApp.Messaging.SignalBus, "jido.messaging.message.*")

Standard Metadata Keys

All signals include a consistent set of metadata keys for correlation and tracing. See @metadata_keys for the standard keys included in all events.

Summary

Functions

emit(event_type, instance_module, room_id, data)

Generic emit function for room-level events.

emit_agent(event_type, instance_module, room_id, agent_id, data \\ %{})

Emits an agent lifecycle signal.

emit_failed(room_id, reason, context)

Emits a :failed signal when message delivery has failed.

emit_instance(event_type, instance_module, instance_id, data \\ %{})

Emits an instance lifecycle signal.

emit_received(message, context)

Emits a :received signal when a message has been ingested.

emit_sent(message, context)

Emits a :sent signal when a message has been delivered successfully.

metadata_keys()

Returns the list of standard metadata keys included in all signals.

Functions

emit(event_type, instance_module, room_id, data)

@spec emit(atom(), module(), String.t(), map()) :: :ok

Generic emit function for room-level events.

Used by RoomServer to emit signals for various events like:

  • :presence_changed - participant presence updated
  • :typing - typing indicator changed
  • :reaction_added - reaction added to message
  • :reaction_removed - reaction removed from message
  • :message_delivered - message marked as delivered
  • :message_read - message marked as read
  • :thread_created - thread created from message
  • :thread_reply_added - reply added to thread

emit_agent(event_type, instance_module, room_id, agent_id, data \\ %{})

@spec emit_agent(atom(), module(), String.t(), String.t(), map()) :: :ok

Emits an agent lifecycle signal.

Events

  • :triggered - agent trigger condition matched
  • :started - agent execution began
  • :completed - agent execution finished successfully
  • :failed - agent execution failed

emit_failed(room_id, reason, context)

@spec emit_failed(String.t(), term(), map()) :: :ok

Emits a :failed signal when message delivery has failed.

Metadata

  • :room_id - the room ID where delivery was attempted
  • :reason - the failure reason
  • :channel - the channel module used for delivery attempt
  • :external_room_id - the external room identifier
  • :instance_module - the messaging module
  • :bridge_id - the bridge ID
  • :timestamp - when the event occurred
  • :correlation_id - message ID or generated ID for tracing

emit_instance(event_type, instance_module, instance_id, data \\ %{})

@spec emit_instance(atom(), module(), String.t(), map()) :: :ok

Emits an instance lifecycle signal.

Events

  • :started - instance started
  • :connecting - instance connecting to external service
  • :connected - instance connected
  • :disconnected - instance disconnected
  • :stopped - instance stopped
  • :error - instance error

emit_received(message, context)

@spec emit_received(Jido.Messaging.Message.t(), map()) :: :ok

Emits a :received signal when a message has been ingested.

Metadata

  • :message - the ingested Jido.Messaging.Message struct
  • :room_id - the room ID where the message was received
  • :participant_id - the sender's participant ID
  • :channel - the channel module that received the message
  • :bridge_id - the bridge ID of the channel
  • :instance_module - the messaging module
  • :timestamp - when the event occurred
  • :correlation_id - message ID or generated ID for tracing

emit_sent(message, context)

@spec emit_sent(Jido.Messaging.Message.t(), map()) :: :ok

Emits a :sent signal when a message has been delivered successfully.

Metadata

  • :message - the sent Jido.Messaging.Message struct
  • :room_id - the room ID where the message was sent
  • :channel - the channel module used for delivery
  • :external_room_id - the external room identifier
  • :instance_module - the messaging module
  • :bridge_id - the bridge ID
  • :timestamp - when the event occurred
  • :correlation_id - message ID or generated ID for tracing

metadata_keys()

@spec metadata_keys() :: [atom()]

Returns the list of standard metadata keys included in all signals.