Telemetry events for MqttX.

MqttX emits telemetry events at key points in the client and server lifecycle. You can attach handlers to these events to collect metrics, log events, or integrate with your observability stack.

Event Naming Convention

All events are prefixed with [:mqttx, ...]. Client events use [:mqttx, :client, ...] and server events use [:mqttx, :server, ...].

Client Events

[:mqttx, :client, :connect, :start]

Emitted when a client starts connecting to a broker.

• Measurements: %{system_time: integer()}

• Metadata: %{host: binary(), port: integer(), client_id: binary(), transport: :tcp | :ssl}

[:mqttx, :client, :connect, :stop]

Emitted when a client successfully connects.

• Measurements: %{duration: integer()} (in native time units)
• Metadata: %{host: binary(), port: integer(), client_id: binary()}

[:mqttx, :client, :connect, :exception]

Emitted when a client fails to connect.

• Measurements: %{duration: integer()}
• Metadata: %{host: binary(), port: integer(), client_id: binary(), reason: term()}

[:mqttx, :client, :disconnect]

Emitted when a client disconnects.

• Measurements: %{system_time: integer()}
• Metadata: %{client_id: binary(), reason: atom()}

[:mqttx, :client, :publish, :start]

Emitted when a client starts publishing a message.

• Measurements: %{system_time: integer()}
• Metadata: %{client_id: binary(), topic: binary(), qos: 0..2, payload_size: integer()}

[:mqttx, :client, :publish, :stop]

Emitted when a publish completes (QoS 0) or is acknowledged (QoS 1/2).

• Measurements: %{duration: integer()}
• Metadata: %{client_id: binary(), topic: binary(), qos: 0..2}

[:mqttx, :client, :publish, :exception]

Emitted when the broker rejects a QoS 1/2 publish (PUBACK/PUBREC carrying a reason code >= 0x80).

• Measurements: %{duration: integer()}
• Metadata: %{client_id: binary(), topic: binary(), qos: 0..2, reason_code: 0..255}

[:mqttx, :client, :subscribe]

Emitted when a client subscribes to topics.

• Measurements: %{system_time: integer()}
• Metadata: %{client_id: binary(), topics: list()}

[:mqttx, :client, :message]

Emitted when a client receives a message.

• Measurements: %{system_time: integer(), payload_size: integer()}

• Metadata: %{client_id: binary(), topic: [binary() | atom()], qos: 0..2}

Server Events

[:mqttx, :server, :client_connect, :start]

Emitted when a client starts connecting to the server.

• Measurements: %{system_time: integer()}
• Metadata: %{client_id: binary(), protocol_version: integer()}

[:mqttx, :server, :client_connect, :stop]

Emitted when a client successfully connects to the server.

• Measurements: %{duration: integer()}
• Metadata: %{client_id: binary(), protocol_version: integer()}

[:mqttx, :server, :client_connect, :exception]

Emitted when a client connection is rejected.

• Measurements: %{duration: integer()}
• Metadata: %{client_id: binary(), reason_code: integer()}

[:mqttx, :server, :client_disconnect]

Emitted when a client disconnects from the server.

• Measurements: %{system_time: integer()}
• Metadata: %{client_id: binary(), reason: atom()}

[:mqttx, :server, :publish]

Emitted when the server receives a PUBLISH packet.

• Measurements: %{system_time: integer(), payload_size: integer()}

• Metadata: %{client_id: binary(), topic: [binary() | atom()], qos: 0..2} (decoded segment list — see the topic-shape note above)

[:mqttx, :server, :subscribe]

Emitted when a client subscribes.

• Measurements: %{system_time: integer()}
• Metadata: %{client_id: binary(), topics: list()}

Example Usage

# Attach a handler in your application startup
:telemetry.attach_many(
  "mqttx-logger",
  [
    [:mqttx, :client, :connect, :stop],
    [:mqttx, :client, :disconnect],
    [:mqttx, :server, :publish]
  ],
  &MyApp.TelemetryHandler.handle_event/4,
  nil
)