HiveMQ Distributed Tracing Spans

HiveMQ distributed tracing spans represent work done within a specific trace including time intervals and associated metadata.

Resources

Resources capture information about the entity for which telemetry data is recorded.

All captured spans are correlated with OpenTelemetry Resources:

  • The HiveMQ Enterprise Distributed Tracing Extension provides values for all required and recommended Service resources.

  • If possible, the HiveMQ Enterprise Distributed Tracing Extension also displays values for optional resources related to the Host, Operating System, and Cloud provider.

Table 1. Available resource attributes
Resource Attribute Description

service.name

The name of the service as defined in the hivemq-distributed-tracing-extension.xml.
For example, HiveMQ Broker.

service.instance.id

The node ID of the HiveMQ Broker instance. For example, <kZpRK>.

service.namespace

The service namespace of the HiveMQ broker. For example, HiveMQ.

service.version

The version of the HiveMQ broker. For example, <4.9.0>.

host.name

The name of the host, if detected. For example, <hivemq-broker>.

host.arch

The CPU architecture on which the host system runs, if detected. For example, <amd64>.

os.name

The human-readable operating system name, if detected. For example, <Ubuntu>.

os.type

The operating system type, if detected. For example, <linux>.

os.version

The version string of the operating system, if detected. For example, <22.04>.

cloud.provider

The name of the cloud provider, if applicable and detected. For example, <aws>.

cloud.region

The geographical region in which the resource runs, if applicable and detected.
For example, <us-east-1>.

Span Attributes

The captured spans from HiveMQ follow the OpenTelemetry semantic conventions for Messaging systems as closely as possible.
Span attributes are key and value pairs that describe a span. The information in the span attributes provides the detailed information you need to effectively observe your application.

HiveMQ Broker Spans

HiveMQ Broker Spans

PUBLISH Receive Span

The PUBLISH receive span captures tracing data for incoming MQTT PUBLISH packets.
The OpenTelemetry SpanKind of PUBLISH receive spans is SERVER.

Table 2. Available PUBLISH receive span attributes
Span Attribute Description

messaging.system

A string that identifies the messaging system. For example, HiveMQ.

messaging.protocol

The name of the transport protocol. For example, MQTT.

messaging.protocol_version

The version of the transport protocol.
For example, MQTTv5 ,MQTTv3_1_1, or MQTTv3_1.

messaging.destination

The topic of the MQTT PUBLISH message. For example, <topic/name>.

messaging.message_id

The unique ID of the MQTT PUBLISH message. For example, <unique id>.

messaging.message_payload_size_bytes

The size of the MQTT message payload in bytes. For example, <number of bytes>.

net.sock.peer.addr

The IP address of the MQTT client that publishes the message. For example, <127.0.0.1>.

net.sock.peer.port

The port of the MQTT client that publishes the message. For example, <16456>.

net.sock.host.addr

The IP address of the HiveMQ broker. For example, <127.0.0.1>.

net.sock.host.port

The port of the HiveMQ broker. For example, <1883>.

messaging.mqtt.client.id

The identifier of the publishing MQTT client. For example, <client identifier>.

messaging.mqtt.publish.qos

The QoS level of the MQTT PUBLISH message. For example, 0, 1, or 2.

messaging.mqtt.publish.packet_id

The packet ID of the MQTT PUBLISH message. For example, <34201>.

messaging.mqtt.publish.retain

The retain flag of the MQTT PUBLISH message. For example, true or false.

messaging.mqtt.publish.duplicate_delivery

The duplicate delivery flag of the MQTT PUBLISH. For example, true or false.

messaging.mqtt.publish.message_expiry_interval

The message expiry interval in seconds of the MQTT PUBLISH message. For example, <12345>.

messaging.mqtt.publish.payload_format_indicator

The payload format indicator of the MQTT PUBLISH message. For example, UNSPECIFIED or UTF_8.

messaging.mqtt.publish.content_type

The content type of the MQTT PUBLISH message. For example, <content description>.

messaging.mqtt.publish.response_topic

The response topic of the MQTT PUBLISH message. For example, `<response/topic/name> `.

PUBLISH Send Span

The PUBLISH send span captures tracing data for outgoing MQTT PUBLISH packets.
The OpenTelemetry SpanKind of PUBLISH Send spans CLIENT.

Table 3. Available PUBLISH send span attributes
Span Attribute Description

messaging.system

A string that identifies the messaging system. For example, HiveMQ.

messaging.protocol

The name of the transport protocol. For example, MQTT.

messaging.protocol_version

The version of the transport protocol.
For example, MQTTv5 ,MQTTv3_1_1, or MQTTv3_1.

messaging.destination

The topic of the MQTT PUBLISH message. For example, <topic/name>.

messaging.message_id

The unique ID of the MQTT PUBLISH message. For example, <unique id>.

messaging.message_payload_size_bytes

The size of the MQTT message payload in bytes. For example, <number of bytes>.

net.sock.peer.addr

The IP address of the MQTT client that publishes the message. For example, <127.0.0.1>.

net.sock.peer.port

The port of the MQTT client that publishes the message. For example, <16456>.

net.sock.host.addr

The IP address of the HiveMQ broker. For example, <127.0.0.1>.

net.sock.host.port

The port of the HiveMQ broker. For example, <1883>.

messaging.mqtt.client.id

The identifier of the publishing MQTT client. For example, <client identifier>.

messaging.mqtt.publish.qos

The QoS level of the MQTT PUBLISH message. For example, 0, 1, or 2.

messaging.mqtt.publish.packet_id

The packet ID of the MQTT PUBLISH message. For example, <34201>.

messaging.mqtt.publish.retain

The retain flag of the MQTT PUBLISH message. For example, true or false.

messaging.mqtt.publish.duplicate_delivery

The duplicate delivery flag of the MQTT PUBLISH. For example, true or false.

messaging.mqtt.publish.message_expiry_interval

The message expiry interval in seconds of the MQTT PUBLISH message.
For example, <12345>.

messaging.mqtt.publish.payload_format_indicator

The payload format indicator of the MQTT PUBLISH message.
For example, UNSPECIFIED or UTF_8.

messaging.mqtt.publish.content_type

The content type of the MQTT PUBLISH message. For example, <content description>.

messaging.mqtt.publish.response_topic

The response topic of the MQTT PUBLISH message. For example, <response/topic/name>.

Publish Inbound Interceptor Process Span

The Publish Inbound Interceptor process span captures tracing data for each PublishInboundInterceptor.onInboundPublish() invocation.
The OpenTelemetry SpanKind of Publish Inbound Interceptor process spans is`INTERNAL`.

Table 4. Available Publish Inbound Interceptor process span attributes
Span Attribute Description

messaging.hivemq.extension.id

The ID of the extension. For example, <my-custom-interceptor-extension>.

messaging.hivemq.extension.version

The version of the extension. For example, <1.5.1>.

Publish Authorizer Process Span

The Publish Authorizer process span captures tracing data for each PublishAuthorizer.authorizePublish() invocation.
The OpenTelemetry SpanKind of Publish Authorizer process spans is INTERNAL.

Table 5. Available Publish Authorizer process span attributes
Span Attribute Description

messaging.hivemq.extension.id

The ID of the extension. For example, <my-custom-auth-extension>.

messaging.hivemq.extension.version

The version of the extension. For example, <1.2.4>.

Publish Outbound Interceptor Process Span

The Publish Outbound Interceptor process span captures tracing data for each PublishOutboundInterceptor.onOutboundPublish() invocation.
The OpenTelemetry SpanKind of Publish Outbound Interceptor process spans is INTERNAL.

Table 6. Available Publish Outbound Interceptor process span attributes
Span Attribute Description

messaging.hivemq.extension.id

The ID of the extension. For example, <my-custom-interceptor-extension>.

messaging.hivemq.extension.version

The version of the extension. For example, <1.8.2>.

Message Consumer Process Span

The Message Consumer process span captures tracing data for each MessageConsumer.consume() invocation.
The OpenTelemetry SpanKind of Message Consumer process spans is INTERNAL.

Table 7. Available Message Consumer process span attributes
Span Attribute Description

messaging.hivemq.extension.id

The ID of the extension. For example, <my-custom-consumer-extension>.

messaging.hivemq.extension.version

The version of the extension. For example, <1.5.1>.

messaging.hivemq.extension.consumer.id

The ID of the MessageConsumer. For example, <kafka-extension_mqtt-to-kafka>.

Publish Service Process Span

The Publish Service process span captures tracing data for each PublishService.publish() and PublishService.publishToClient() invocation.
The OpenTelemetry SpanKind of Publish Service process spans is INTERNAL.

Table 8. Available Publish Service process span attributes
Span Attribute Description

messaging.system

A string that identifies the messaging system. For example, HiveMQ.

messaging.protocol

The name of the transport protocol. For example, MQTT.

messaging.destination

The topic of the MQTT PUBLISH message. For example, <topic/name>.

messaging.message_id

The unique ID of the MQTT PUBLISH message. For example, <unique id>.

messaging.message_payload_size_bytes

The size of the MQTT message payload in bytes. For example, <number of bytes>.

messaging.mqtt.publish.qos

The QoS level of the MQTT PUBLISH message. For example, 0, 1, or 2.

messaging.mqtt.publish.packet_id

The packet ID of the MQTT PUBLISH message. For example, <34201>.

messaging.mqtt.publish.retain

The retain flag of the MQTT PUBLISH message. For example, true or false.

messaging.mqtt.publish.duplicate_delivery

The duplicate delivery flag of the MQTT PUBLISH. For example, true or false.

messaging.mqtt.publish.message_expiry_interval

The message expiry interval in seconds of the MQTT PUBLISH message.
For example, <12345>.

messaging.mqtt.publish.payload_format_indicator

The payload format indicator of the MQTT PUBLISH message.
For example, UNSPECIFIED or UTF_8.

messaging.mqtt.publish.content_type

The content type of the MQTT PUBLISH message. For example, <content description>.

messaging.mqtt.publish.response_topic

The response topic of the MQTT PUBLISH message. For example, <response/topic/name>.

HiveMQ Enterprise Extension for Kafka Spans

HiveMQ Enterprise Extension for Kafka Spans

Kafka Receive Span

The Kafka receive span captures tracing data for incoming Kafka records.
The OpenTelemetry SpanKind of Kafka receive spans is CONSUMER.

Table 9. Available Kafka receive span attributes
Span Attribute Description

messaging.system

A string that identifies the messaging system. For example, kafka.

messaging.destination

The topic of the Kafka record. For example, <kafka-topic>.

messaging.destination_kind

The kind of message destination. For example, topic.

messaging.message_payload_size_bytes

The size of the Kafka record payload in bytes. For example, <number of bytes>.

messaging.operation

A string that identifies the kind of message consumption. For example, receive.

messaging.kafka.partition

The partition from which the Kafka record is received. For example, <2>.

messaging.kafka.tombstone

An optional flag that indicates whether the Kafka record is a tombstone, if detected. For example, true or false.

messaging.hivemq.kafka-to-mqtt.id

The ID of the mapping from the kafka-configuration.xml.
For example, <kafka-to-mqtt-mapping-01>.

messaging.hivemq.kafka-to-mqtt.type

The type of the mapping from the kafka-configuration.xml. For example, mapping; transformer.

Kafka Send Span

The Kafka send span captures tracing data for incoming Kafka records.
The OpenTelemetry SpanKind of Kafka send spans is PRODUCER.

Table 10. Available Kafka send span attributes
Span Attribute Description

messaging.system

A string that identifies the messaging system. For example, kafka.

messaging.destination

The topic of the Kafka record. For example, <kafka-topic>.

messaging.destination_kind

The kind of message destination. For example, topic.

messaging.message_payload_size_bytes

The size of the Kafka record payload in bytes. For example, <number of bytes>.

messaging.operation

A string that identifies the kind of message consumption. For example, receive.

messaging.kafka.partition

The partition from which the Kafka record is received. For example, <2>.

messaging.kafka.tombstone

An optional flag that indicates whether the Kafka record is a tombstone, if detected. For example, true or false.

messaging.hivemq.mqtt-to-kafka.id

The ID of the mapping from the kafka-configuration.xml.
For example, <mqtt-to-kafka-transformer-01>.

messaging.hivemq.mqtt-to-kafka.type

The type of the mapping from the kafka-configuration.xml. For example, mapping; transformer.

MQTT to Kafka Transformer Process Span

The MQTT to Kafka Transformer process span captures tracing data for each MqttToKafkaTransformer.transformMqttToKafka() invocation.
The OpenTelemetry SpanKind of MQTT to Kafka Transformer process spans is INTERNAL.

Table 11. Available MQTT to Kafka Transformer process span attributes
Span Attribute Description

messaging.hivemq.mqtt-to-kafka.transformer

The fully qualified name of the transformer as defined in the kafka-configuration.xml.
For example, <com.example.CustomMqttToKafkaTransformer>.

Kafka to MQTT Transformer Process Span

The Kafka to MQTT Transformer process span captures tracing data for each KafkaToMqttTransformer.transformKafkaToMqtt() invocation.
The OpenTelemetry SpanKind of Kafka to MQTT Transformer process spans is INTERNAL.

Table 12. Available Kafka to MQTT Transformer process span attributes
Span Attribute Description

messaging.hivemq.kafka-to-mqtt.transformer

The fully qualified name of the transformer as defined in the kafka-configuration.xml file.
For example, <com.example..CustomKafkaToMqttTransformer>.