Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Use more generic AMQP trace-context propagation format #3597

Closed
calohmn opened this issue Dec 18, 2023 · 0 comments · Fixed by #3599
Closed

Use more generic AMQP trace-context propagation format #3597

calohmn opened this issue Dec 18, 2023 · 0 comments · Fixed by #3599
Assignees
Labels
Milestone

Comments

@calohmn
Copy link
Contributor

calohmn commented Dec 18, 2023

This relates to #1012 and #1046 and is about where to write/read trace-context information in AMQP messages sent/received by Hono.

Currently, when sending AMQP messages, Hono puts trace-context information in the message annotations of the message, inside a x-opt-trace-context map. This x-opt-trace-context map name is purely arbitrary and not specified in any standard. This means that when using AMQP messaging in connection with Eclipse Ditto for example (e.g. via the iot-packages cloud2edge chart with the AMQP messaging and tracing profiles), there are no combined traces between Hono and Ditto, as Ditto reads/writes trace-context information differently (Ditto uses the AMQP message application properties).

As for a standard format in this regard, there is a W3C First Public Working Draft of an AMQP trace context protocol specification (see https://w3c.github.io/trace-context-amqp/).
The "2.1 Trace context fields placement in a message" chapter there basically states:

  • Message publishers write tracing context values in the message application-properties (which are immutable)
  • Intermediaries cannot edit the message-annotations, instead they use the message-annotations to include their trace context

To note here is that the message annotations must only contain registered keys or keys that start with x-.
The traceparent and tracestate keys have not been registered yet - there's an open issue for that.

For context: Definition of AMQP Application properties

The application-properties section is a part of the bare message used for structured application data. Intermediaries can use the data within this structure for the purposes of filtering or routing.

The keys of this map are restricted to be of type string (which excludes the possibility of a null key) and the values are restricted to be of simple types only, that is, excluding map, list, and array types.

For context: Definition of AMQP message annotations

The message-annotations section is used for properties of the message which are aimed at the infrastructure and SHOULD be propagated across every delivery step. Message annotations convey information about the message. Intermediaries MUST propagate the annotations unless the annotations are explicitly augmented or modified (e.g., by the use of the modified outcome).

The capabilities negotiated on link attach and on the source and target can be used to establish which annotations a peer understands; however, in a network of AMQP intermediaries it might not be possible to know if every intermediary will understand the annotation. Note that for some annotations it might not be necessary for the intermediary to understand their purpose, i.e., they could be used purely as an attribute which can be filtered on.

A registry of defined annotations and their meanings is maintained [AMQPMESSANN].

If the message-annotations section is omitted, it is equivalent to a message-annotations section containing an empty map of annotations.

I think the most straightforward way to allow integration of Hono traces with other applications would be to let Hono write the trace-context to the message application properties.
On a purely technical level, Hono is anyway the publisher, not an intermediary, of the AMQP messages. This is the case even for AMQP telemetry/event messages received by the AMQP adapter - their properties/message annotations are not adopted for the corresponding messages that the AMQP adapter sends downstream.

calohmn added a commit to calohmn/hono that referenced this issue Dec 20, 2023
…ormat.

Writing trace-context information in the AMQP message
application-properties now.
calohmn added a commit to calohmn/hono that referenced this issue Jan 14, 2024
…ormat.

Writing trace-context information in the AMQP message
application-properties instead of the message-annotations, if
isUseLegacyTraceContextFormat has been set to false.
@calohmn calohmn self-assigned this Jan 14, 2024
@sophokles73 sophokles73 added this to the 2.5.0 milestone Jan 15, 2024
calohmn added a commit to calohmn/hono that referenced this issue Jan 15, 2024
…ormat.

Writing trace-context information in the AMQP message
application-properties instead of the message-annotations, if
isUseLegacyTraceContextFormat has been set to false.
calohmn added a commit that referenced this issue Jan 15, 2024
Writing trace-context information in the AMQP message
application-properties instead of the message-annotations, if
isUseLegacyTraceContextFormat has been set to false.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
Projects
None yet
Development

Successfully merging a pull request may close this issue.

2 participants