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

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.destination.name`	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.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> `.
`network.protocol.name`	The name of the transport protocol. For example, `MQTT`.
`network.protocol.version`	The version of the transport protocol. For example, `MQTTv5` ,`MQTTv3_1_1`, or `MQTTv3_1`.
`client.socket.address`	The IP address of the MQTT client that publishes the message. For example, `<127.0.0.1>`.
`client.socket.port`	The port of the MQTT client that publishes the message. For example, `<16456>`.
`server.socket.address`	The IP address of the HiveMQ broker. For example, `<127.0.0.1>`.
`server.socket.port`	The port of the HiveMQ broker. For example, `<1883>`.

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`. For example, `MQTTv5` ,`MQTTv3_1_1`, or `MQTTv3_1`.
`messaging.destination.name`	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.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>`.
`network.protocol.name`	The name of the transport protocol. For example, `MQTT`.
`network.protocol.version`	The version of the transport protocol.
`client.socket.address`	The IP address of the MQTT client that publishes the message. For example, `<127.0.0.1>`.
`client.socket.port`	The port of the MQTT client that publishes the message. For example, `<16456>`.
`server.socket.address`	The IP address of the HiveMQ broker. For example, `<127.0.0.1>`.
`server.socket.port`	The port of the HiveMQ broker. For example, `<1883>`.

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.destination.name`	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>`.
`network.protocol.name`	The name of the transport protocol. For example, `MQTT`.

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.name`	The topic of the Kafka record. For example, `<kafka-topic>`.
`messaging.client_id`	A unique identifier for the Kafka consumer client. Contains the ID of the mapping from the `extensions/hivemq-kafka-extension/conf/config.xml`. For example, `<kafka-to-mqtt-mapping-01>`.
`messaging.operation`	A string that identifies the kind of message consumption. For example, `receive`.
`messaging.message.payload_size_bytes`	The size of the Kafka record payload in bytes. For example, `<number of bytes>`.
`messaging.kafka.destination.partition`	The partition of the Kafka record. For example, `<2>`.
`messaging.kafka.message.offset`	The offset of the Kafka record in the corresponding partition. For example, `<10>`.
`messaging.kafka.message.key`	An optional attribute that contains the key of the Kafka record, if the key is serializable. For example, `key`.
`messaging.kafka.message.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.type`	The type of the mapping from the `extensions/hivemq-kafka-extension/conf/config.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.name`	The topic of the Kafka record. For example, `<kafka-topic>`.
`messaging.client_id`	A unique identifier for the Kafka producer client. Contains the ID of the mapping from the `extensions/hivemq-kafka-extension/conf/config.xml`. For example, `<mqtt-to-kafka-transformer-01>`.
`messaging.message.payload_size_bytes`	The size of the Kafka record payload in bytes. For example, `<number of bytes>`.
`messaging.kafka.destination.partition`	The partition of the Kafka record. For example, `<2>`.
`messaging.kafka.message.offset`	The offset of the Kafka record in the corresponding partition. For example, `<10>`.
`messaging.kafka.message.key`	An optional attribute that contains the key of the Kafka record, if the key is serializable. For example, `key`.
`messaging.kafka.message.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.type`	The type of the mapping from the `extensions/hivemq-kafka-extension/conf/config.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 `extensions/hivemq-kafka-extension/conf/config.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 `extensions/hivemq-kafka-extension/conf/config.xml` file. For example, `com.example.CustomKafkaToMqttTransformer`.