OffBroadway.EMQTT.Producer (off_broadway_emqtt v0.2.0)

View Source

An MQTT producer based on emqtt for Broadway.

Producer options

  • :buffer_size (pos_integer/0) - The maximum number of messages that can be buffered The default value is 10000.

  • :buffer_overflow_strategy - The strategy to use when the buffer is full The default value is :reject.

  • :buffer_durability - Set to :durable to write buffer log to disk, or :transient to keep it in memory The default value is :transient.

  • :buffer_log_dir - A string or zero-arity function that returns the directory to store the buffer log The default value is &System.tmp_dir/0.

  • :topics (list of tuple of String.t/0, values) - The topics to subscribe to The default value is [].

  • :message_handler - A module that implements the OffBroadway.EMQTT.MessageHandler behaviour The default value is OffBroadway.EMQTT.MessageHandler.

  • :config (non-empty keyword/0) - Required. Configuration options that will be sent to the :emqtt process.

    • :host - Required. The host of the MQTT broker

    • :port (pos_integer/0) - The port to connect to The default value is 1883.

    • :username (String.t/0) - Username to authenticate with

    • :password (String.t/0) - Password to authenticate with

    • :ssl (boolean/0) - Whether to use SSL

    • :ssl_opts (keyword/0)

      • :cacertfile (String.t/0) - Path to CA certificate file

      • :server_name_indication - Server name indication

      • :verify - Verify mode The default value is :verify_peer.

      • :certfile (String.t/0) - Path to client certificate file

      • :keyfile (String.t/0) - Path to client key file

    • :ws_path (String.t/0) - The path to the resource.

    • :connect_timeout (pos_integer/0) - The timeout in seconds for the connection The default value is 60.

    • :bridge_mode (boolean/0) - Enable bridge mode or not. The default value is false.

    • :clientid (String.t/0) - Specify the client identifier. The default value is "emqtt-aa-0-c-383-a765a142ae2d1f8e244f".

    • :clean_start (boolean/0) - Whether the server should discard any existing sessions and start a new one. The default value is true.

    • :proto_ver - The MQTT protocol version to use. The default value is :v4.

    • :keepalive (pos_integer/0) - The maximum time interval in seconds that is permitted to elapse between the client finishes transmitting one MQTT Control Packet and starts sending the next. Will be replaced by server keepalive from MQTT server.

    • :max_inflight - The maximum number of QoS 1 and QoS 2 packets in flight. This means the number of packets that have been sent, but not yet acked. Will be replaced by server Receive-Maximum property in a CONNACK package. In that case, the lesser of the two values will act as the limit. The default value is :infinity.

    • :retry_interval (pos_integer/0) - Interval in seconds to retry sending packets that have been sent but not received a response. The default value is 30.

    • :will_topic (String.t/0) - Topic of will message, a predefined message that the client sets to be sent by the server in case of an unexpected disconnects.

    • :will_payload (String.t/0) - The payload of the will message.

    • :will_retain (boolean/0) - Whether the will message should be published as a retained message. The default value is false.

    • :will_qos - The QoS level of the will message. The default value is 0.

    • :auto_ack (boolean/0) - The client process will automacally send ack packages like PUBACK when receiving a packet. The default value is true.

    • :ack_timeout (pos_integer/0) - The timeout in seconds for the ack package. The default value is 30.

    • :force_ping (boolean/0) - If false and any other packets are sent during the keepalive interval, the ping packet will not be sent this time. If true, the ping packet will be sent regardless of other packets. The default value is false.

    • :custom_auth_callbacks - A map of custom authentication callback MFAs. This configuration enables enhanced authentication mechanisms in MQTT v5.

Acknowledgements

TBD

Telemetry

This library exposes the following telemetry events:

  • [:off_broadway_emqtt, :replay_buffer, :start] - Dispatched when the OffBroadway.EMQTT.Broker process is started if the buffer_durability option is set to :durable.

    • measurement: %{time: System.monotonic_time}
    • metadata: %{client_id: string, buffer_size: non_neg_integer}

    This event is only dispatched if the buffer_durability option is set to :durable.

    When this event is dispatched, the buffer_size contains the number of messages currently in the disk log, not the ETS buffer.

  • [:off_broadway_emqtt, :replay_buffer, :stop] - Dispatched after the OffBroadway.EMQTT.Broker process has replayed and truncated the disk log.

    • measurement: %{time: System.monotonic_time}
    • metadata: %{client_id: string, buffer_size: non_neg_integer}

    This event is only dispatched if the buffer_durability option is set to :durable.

    When this event is dispatched, the buffer_size contains the number of messages remaining in the disk log (should be 0 to indicate all logged events was replayed to the ETS cache).

  • [:off_broadway_emqtt, :sync_buffer, :start] - Dispatched when the OffBroadway.EMQTT.Broker process terminates and the ETS buffer is synced to the disk log.

    • measurement: %{time: System.monotonic_time}
    • metadata: %{client_id: string, buffer_size: non_neg_integer}

    This event is only dispatched if the buffer_durability option is set to :durable.

    When this event is dispatched, the buffer_size contains the number of messages that should be written to the disk log.

  • [:off_broadway_emqtt, :sync_buffer, :stop] - Dispatched after the OffBroadway.EMQTT.Broker process has written the ETS buffer to the disk log.

    • measurement: %{time: System.monotonic_time}
    • metadata: %{client_id: string, buffer_size: non_neg_integer}

    This event is only dispatched if the buffer_durability option is set to :durable.

    When this event is dispatched, the buffer_size contains the number of messages that has been written to the disk log.

  • [:off_broadway_emqtt, :receive_messages, :start] - Dispatched before messages are received from the ETS buffer.

    • measurement: %{time: System.monotonic_time}
    • metadata: %{client_id: string, demand: non_neg_integer}
  • [:off_broadway_emqtt, :receive_messages, :stop] - Dispatched after messages have been received from the ETS buffer and "wrapped".

    • measurement: %{time: native_time}
    • metadata: %{client_id: string, topics: [string], received: non_neg_integer, demand: non_neg_integer}
  • [:off_broadway_emqtt, :receive_messages, :exception] - Dispatched after a failure while receiving messages from the ETS buffer.

    • measurement: %{duration: native_time}
    • metadata: %{client_id: string, demand: non_neg_integer, reason: reason, stacktrace: stacktrace}
  • [:off_broadway_emqtt, :receive_messages, :ack] - Dispatched when acking a message if using the default OffBroadway.EMQTT.MessageHandler implementation.

    • measurement: %{time: System.system_time, count: 1}
    • metadata: %{topic: string, receipt: receipt}
  • [:off_broadway_emqtt, :buffer, :accept_message] - Dispatched when a message is stored into the ETS buffer.

    • measurement: %{time: System.system_time, count: 1}
    • metadata: %{client_id: string, topic: string, buffer_size: non_neg_integer}
  • [:off_broadway_emqtt, :buffer, :reject_message] - Dispatched when a message is rejected to be stored in the ETS buffer because it is full. This occurs when the buffer is full and the buffer_overflow_strategy is set to :reject.

    • measurement: %{time: System.system_time, count: 1}
    • metadata: %{client_id: string, topic: string, buffer_size: non_neg_integer}
  • [:off_broadway_emqtt, :buffer, :drop_message] - Dispatched when a message is dropped from the ETS buffer to make space for a new. This occurs when the buffer is full and the buffer_overflow_strategy is set to :drop_head.

    • measurement: %{time: System.system_time, count: 1}
    • metadata: %{client_id: string, topic: string, buffer_size: non_neg_integer}
  • [:off_broadway_emqtt, :buffer, :log_write] - Dispatched when a message is written to the disk log.

    • measurement: %{time: System.system_time, count: 1}
    • metadata: %{client_id: string, topic: string, buffer_size: non_neg_integer}

    This event is only dispatched if the buffer_durability option is set to :durable.

    When this event is dispatched, the buffer_size contains the number of messages currently in the disk log, not the ETS buffer.

Summary

Functions

emqtt_process_name(client_id)

@spec emqtt_process_name(String.t()) :: atom()

message_handler_module(message_handler_module)