package solace.messaging.proto.broker.trace.receive.v1

Get desktop application:
View/edit binary Protocol Buffers messages

A message will be compatible with this specification if its topic matches: _telemetry/broker/trace/receive/v1[/additional/topic/levels] Note that the topic above allows for additional topic levels to be added in the future. Receiving clients must not assume there are no additional topic levels. This message describes telemetry data that a Solace PubSub+ broker captures when a received message is identified as a message to be traced. Fields with names that end in "time_unix_nano" are 64-bit timestamps, in nanoseconds, since midnight, Jan. 1, 1970 UTC. Notes on the field numbers used: - Field numbers 1-15 are used for attributes that are expected to be present on the wire with every single message not containing an error_description. Special priority is given to fields that can be repeated. - Field numbers 16+ are used for other attributes. Next available field ID: 40

• bytes trace_id = 1

  16-byte globally unique trace ID. Any two spans with the same trace ID are part of the same trace.

• bytes span_id = 2

  8-byte span ID, unique within the scope of a trace.

• optional bytes parent_span_id = 16

  If not present, this is a root span. If present, this is an 8-byte span ID of the parent span.

• optional string trace_state = 17

  tracestate string value, as per <https://www.w3.org/TR/trace-context/#tracestate-header>

• optional string baggage = 39

  A baggage string formatted as described here: https://www.w3.org/TR/baggage/#x3-2-1-1-baggage-string This string may be truncated if the complete string, as received, would cause the broker's limit for application message properties to be exceeded. See dropped_application_message_properties for more details.

• sfixed64 start_time_unix_nano = 3

  The start and end timestamps of the receive span. The start of the span is when Guaranteed Messaging processing begins in the broker.

• sfixed64 end_time_unix_nano = 4

• sfixed64 broker_receive_time_unix_nano = 12

  The broker receive timestamp is when the broker first identified the message as a message that is to be traced. This is always before the start of the span (the span starts when Guaranteed Message processing beings on the message later in the processing pipeline). However, in some broker implementations this timestamp is generated from a different clock and therefore not guaranteed to be numerically smaller than start_time_unix_nano, even though it represents an earlier time.

• string topic = 5

  The topic of the received message, used to determine where to enqueue the message.

• optional string reply_to_topic = 18

  The reply-to topic of the received message, if present.

• SpanData.DeliveryMode delivery_mode = 19

  The delivery mode of the message, when it was received by the broker. Note that if the delivery mode is DIRECT, the message will be promoted to NON_PERSISTENT when it is enqueued.

• string router_name = 20

  The receiving broker's router-name at the time the message was received.

• optional string message_vpn_name = 21

  The receiving broker's message-vpn name. This field may be removed in the future without a major version change since the field is specified as optional. Rather than rely on this field, receiving clients should obtain the VPN by using an SMF API to extract the VPN_NAME_IN_USE from the API's Session object. The message_vpn_name of all messages received from via an SMF API's session will match the session's VPN_NAME_IN_USE.

• string solos_version = 38

  The receiving broker's SolOS version when the message was initially received. It is possible for a consumer to determine the SolOS version of the broker it is receiving messages from by extracting the PEER_SOFTWARE_VERSION from an SMF API Session object. However, it may not match this attribute since the message may have been received when the version was different from the broker's current SolOS version.

• string client_name = 6

  The client name of the publishing client, as well as the client-username they are bound to on the broker.

• string client_username = 7

• bytes host_ip = 8

  The IP and port the broker received the message on. Note: host_ip can be either an IPv4 address, an IPv6 address, or no address at all. If it is IPv4, the length is 4; an IPv6 address is 16 bytes; no address is indicated with a 0-length value. When the IP address is not included, the host_port should not be read.

• uint32 host_port = 9

• bytes peer_ip = 10

  The IP and port of the publishing client, from the broker's point of view. This may not be the client's local IP and port if there is network address translation involved between the client and the broker. Note: peer_ip can be either an IPv4 address, an IPv6 address, or no address at all. If it is IPv4, the length is 4; an IPv6 address is 16 bytes; no address is indicated with a 0-length value. When the IP address is not included, the peer_port should not be read.

• uint32 peer_port = 11

• optional bytes replication_group_message_id = 22

  The message's globally unique Replication Group Message ID, in binary format. This will not be present if the message is being discarded. The format of these bytes are: byte[0]: Version. byte[1:len-1]: Binary representation of a replication group message ID in the specified version. This should only be treated as opaque data by applications. If comparing two ID's and the versions are the same, then the ID's are the same if the remaining bytes are the same. If the versions are different, no comparison can be made.

• string protocol = 23

  Indicates how the message was received by the broker.

• optional string protocol_version = 24

  The version of the protocol used. This is only present when the protocol is MQTT.

• bool dmq_eligible = 25

  Indicates properties of the published message, as set by the client.

• optional uint32 priority = 26

• optional int64 ttl = 27

• uint32 binary_attachment_size = 28

  The sizes of various types of message payload, which are not mutually exclusive.

• uint32 xml_attachment_size = 29

• uint32 metadata_size = 30

• optional string application_message_id = 31

  These properties may or may not have been set on a message by the application.

• optional string correlation_id = 32

• map<string, SpanData.UserPropertyValue> user_properties = 14

  If the applications set user properties on the message, they are captured here. See the UserPropertyValue for restrictions on which values will be captured.

• bool dropped_application_message_properties = 37

  Application message properties refers to the collection of: * trace_state * application_message_id * correlation_id * baggage * user_properties The broker supports up to a total of 8KiB of application message properties. If the total amount of application message properties in the message being traced exceeds this limit, this flag is used to indicate some properties were dropped.

• string error_description = 33

  If present, this indicates the message is being rejected to the publisher and matches the error string provided back to the publisher as an error. For transacted messages, the individual messages are not rejected to the publisher. However, a message with an error_description indicates that it is one of the messages that caused the operation on the transacted session to fail. See transaction_event for more information on the failed operation. This string is informational only and not intended to be parsed by applications.

• optional SpanData.TransactionEvent transaction_event = 34

  If the message is part of a transaction, transaction_event provides details on the transaction.

• repeated SpanData.EnqueueEvent enqueue_events = 15

  Each EnqueueEvent represents an attempt to enqueue the message to the described destination.

• uint32 dropped_enqueue_events_success = 35

  There is a limit to the number of enqueue events the broker will generate for a received message. The following two fields indicate the number of successful and failed enqueue events that were dropped.

• uint32 dropped_enqueue_events_failed = 36

Used in: SpanData

• PERSISTENT = 0

• NON_PERSISTENT = 1

• DIRECT = 2

An enqueue event represents the broker's decision to enqueue a message when processing a received message. If there is no error_description, the broker has successfully processed the message and the enqueue events indicate where the message has been enqueued. The presence of an error_description indicates the message will not be enqueued to dest even though the message matched the destination. If rejects_all_enqueues is set, it means the message is not enqueued to any destinations, regardless of what other enqueue events may indicate and the message is rejected.

Used in: SpanData

• sfixed64 time_unix_nano = 1

  The timestamp when the enqueue decision was made

• oneof dest

  Queues and Topic Endpoints with the same name can simultaneously co-exist on the broker, so there needs to be a way of disambiguating the type of the enqueue destination. The "oneof" construct here addresses this.

  • string queue_name = 2

  • string topic_endpoint_name = 3

• optional string error_description = 4

  The presence of an error_description indicates the message matched the destination, but it is not being enqueued due to the description.

• bool rejects_all_enqueues = 5

  This flag being set on one or more enqueue events for a message implies that the message is not enqueued to any destination, regardless of the presence of successful enqueue events in the span. This will never be set when there is not an error_description present. If this is set, it indicates that the error described by error_description is a cause for the message to be rejected. Rejected non-transacted messages cause the message to be nacked to the publisher and rejected transacted messages result in a change in transacted session state that will cause a future commit attempt to fail. The cause for message rejection indicated to the client in either a message nack or commit failure response is the error_description of the first enqueue event that has this flag set.

• optional uint32 partition_number = 6

  If the message is enqueued to a partitioned queue, this field indicates the partition number the message is enqueued to.

• optional int64 ttl = 7

  If the message will have a TTL other than the value indicated by the receive span containing this event, it is indicated with this value.

When a message has a transaction event, it indicates the message is part of a transaction. The timestamp indicates when the *initial* decision was made for this particular message as part of the transaction operation. It doesn't indicate the final state of the transaction. This isn't known until all messages that are part of the transaction have been processed. Note it is possible that, for example, after deciding a message will be committed that a subsequent message in the transaction will cause the transaction to fail. This will result in a successful receive span with a COMMIT transaction event with no error. The fact that the message is not successfully processed will be indicated by a child span of this span. At the current time, these subsequent spans are not yet generated and will be added in a future release. In the meantime, the transaction_id can be used to find out if there were any errored messages in the transaction. A single errored message indicates the entire transaction failed. Also note that since the receive span is only generated either on commit or when the message is discarded, certain transaction operations are only observed in failed receive spans. For example, when XA End or XA Prepare operations succeed, the message is neither discarded nor committed. It is only if these operations fail that the transaction is rolled back and an errored receive span is generated.

Used in: SpanData

• sfixed64 time_unix_nano = 1

• TransactionEvent.Type type = 2

• TransactionEvent.Initiator initiator = 3

• oneof transaction_id

  • TransactionEvent.Xid xid = 4

  • TransactionEvent.LocalTransactionId local_id = 5

• optional string error_description = 6

Used in: TransactionEvent

• CLIENT = 0

• ADMIN = 1

• BROKER = 2

Used in: TransactionEvent

• uint32 transaction_id = 1

• uint32 session_id = 2

• string session_name = 3

Used in: TransactionEvent

• COMMIT = 0

  COMMIT and ROLLBACK are always initiated by either a CLIENT or ADMIN. The initiator is ADMIN when the management interface is used to to perform a heuristic commit or rollback.

• ROLLBACK = 1

• END = 2

  PREPARE and END can only occur with a CLIENT initiator, and spans for these operations are only generated if the operation fails. Therefore, the error_description of the TransactionEvent will always be present for END and PREPARE.

• PREPARE = 3

• SESSION_TIMEOUT = 4

  The initiator of a SESSION_TIMEOUT is always BROKER. All messages received as part of the transaction are discarded.

• ROLLBACK_ONLY = 5

  The initiator of ROLLBACK_ONLY is always BROKER. The first such event in a transaction always has an error_description in the span, indicating there was a problem processing the message when it was received, and the message is being discarded. This also transitions the transaction itself to a "rollback only" state, which causes all subsequent messages received as part of the transaction to also be discarded. Spans generated by these subsequent discards will not have the span's error_description set, but all ROLLBACK_ONLY transaction events will have an error_description set, which indicate the transaction's error. Since the only record of these messages in the context of the transaction has been discarded, no further span can be generated in the context of a client, admin, or session timeout operation. When a subsequent operation such as rollback or commit occurs on a transaction marked rollback only, only messages received prior to the error triggering the transition to rollback only will generate receive spans.

Used in: TransactionEvent

• int32 format_id = 1

• bytes branch_qualifier = 2

• bytes global_id = 3

Used in: SpanData

• oneof value

  This expresses a mapping from a Solace SDT type to a protobuf type. The Solace SDT Types Map, Stream, and SMF are not supported. Other SDT types from other protocols, such as AMQP symbol, timestamp, UUID, and decimal types are not supported.

  • bytes null_value = 1

  • bool bool_value = 2

  • uint32 uint8_value = 3

  • uint32 uint16_value = 4

  • uint32 uint32_value = 5

  • uint64 uint64_value = 6

  • sint32 int8_value = 7

  • sint32 int16_value = 8

  • sint32 int32_value = 9

  • sint64 int64_value = 10

  • uint32 character_value = 11

  • string string_value = 12

  • bytes byteArray_value = 13

  • float float_value = 14

  • double double_value = 15

  • string destination_value = 16