Add messaging wrappers to support lightweight manual instrumentation

[Cirilla-zmh]

Description:

This PR introduces a complete implementation of a generic messaging process wrapper API, designed to facilitate the creation of process spans and the propagation of trace context in a standardized and lightweight manner. It builds upon the initial draft presented in PR #1803, which provides additional context for this work.

Key features and contributions include:

• Generic Process Wrapper API: A flexible and reusable API that supports the creation of process spans and ensures trace context propagation across different libraries and frameworks.
• Library Implementations:
  • Added support for kafka-clients.
  • Added support for aliyun-mns-sdk (Alibaba Cloud Simple Message Queue).

Existing Issue(s):

• Proposal: Adding messaging publish(send) and process wrapper API and matched instrumentation. opentelemetry-java-instrumentation#13340
• Proposal: Adding messaging publish(send) and process wrapper API and matched instrumentation. opentelemetry-specification#4426

Testing:

• Base API integration tests.
• Integration tests for kafka-clients.
• Integration tests for aliyun-mns-sdk (pending for building mocked server).

Documentation:

For detailed usage instructions and API documentation, please refer to the updated README.md

[trask]

Can define separate extractors for each implementation instead of implementing this interface for each implementation? that would seem more similar to the existing instrumentation extractor design

[Cirilla-zmh]

separate extractors for each implementation instead of implementing this interface for each implementation

Sorry, I don't think so.

If we do that, users have got to create an AttributesExtractor for each manual implementation, rather than reuse the DefaultMessagingAttributesGetter. Therefore, users should associate the attributes keys defined in semconv with the fields of messages - it's normally hard (semconv attributes are not such stable, and users may always ignore documents...), and that's one of reasons why we give the process wrapper today.

Conversely, if we give this interface. We can take advantage of the self-explanatory nature of the method names and add java comments to tell users what this value should point to. This process seems more natural, especially for those users who are not such familiar to OTel.

[trask]

I don't disagree with your reasoning, but doesn't that same reasoning apply to all of the existing instrumentation api semconv attribute extractor design?

[Cirilla-zmh]

Maybe I didn't get your point. Are you suggesting a design like this:

Drop the interface of MessagingProcessRequest and create a interface of MessagingAttribute (or reuse that in instrumentations)

If we do so, the complexity for manual users may increase slightly—they will need to implement the MyMessagingGetter and define a request in cases where the framework's provided message structure is insufficient to retrieve all attributes (similar to KafkaProcessRequest). This is also why I didn't reuse the design of MessagingAttributesGetter—I believe it might introduce additional cognitive overhead.

However, if you prefer to maintain consistency in the design to make it easier for developers to manage, that makes sense as well. I can adjust my implementation to align with the instrumentation as much as possible.

[trask]

If we do so, the complexity for manual users may increase slightly—they will need to implement the MyMessagingGetter and define a request in cases where the framework's provided message structure is insufficient to retrieve all attributes (similar to KafkaProcessRequest). This is also why I didn't reuse the design of MessagingAttributesGetter—I believe it might introduce additional cognitive overhead.

yeah, it's a good point, but I'd prefer to stay consistent with existing instrumentation.

ideally most users of this will be using our pre-built implementations (e.g. for kafka and mns) and so hopefully won't even be aware of which design we use

[Cirilla-zmh]

It makes sense to me. I'll adjust this implementation.

[linux-foundation-easycla]

The committers listed above are authorized under a signed CLA.

• ✅ login: Cirilla-zmh / name: Minghui Zhang (b6ed6c6, 5686199, 8a6dc8c, 7ae2731, 8ef16f8, eddb143, 6f3587b, e588d1e, 77e3001, 78da0f9, 7b39cd5, 2180b1a, 8194500, c73a7ec, b40d6c4, 811d197, 719057f, 1a914b0)
• ✅ login: otelbot[bot] (b273786, c84ab3d)

[otelbot-java-contrib]

❌ The result from spotlessApply could not be committed to the PR branch, see logs: https://github.com/open-telemetry/opentelemetry-java-contrib/actions/runs/15303539997.

[Cirilla-zmh]

Update:

• Refactored the README by moving the given implementation instructions ahead of the manual setup ones.
• Regarding the generic parameters in AttributesGetter: I believe we have to keep them this way because we're reusing the definition of AttributesExtractor from the instrumentation. If we restrict the type to a specific interface, users wouldn't be able to define their own AttributesExtractor without resorting to explicit type casting. At this point, I think it's reasonable to provide an extensible and generic type here.
• Added tests for aliyun-mns-sdk ;)

cc @steverao @trask

[Cirilla-zmh]

Some feedback: reducing the complexity of AttributesGetter

[otelbot-java-contrib]

🔧 The result from spotlessApply was committed to the PR branch.

[otelbot-java-contrib]

🔧 The result from spotlessApply was committed to the PR branch.

[otelbot-java-contrib]

🔧 The result from spotlessApply was committed to the PR branch.

[Cirilla-zmh]

@trask Hey Trask, I've refactored the design, and we now have an implementation that's very similar to the one in
instrumentation. Could you please take a look at it?