[WFLY-19836] Integrate OpenTracing with MicroProfile Reactive Messagi…

…ng AMQP Connector

microprofile/WFLY-19836_microprofile_reactive_messaging_otel_with_amqp.adoc

@@ -0,0 +1,179 @@
+---
+// Add any category for this proposal as a yaml list, e.g.
+// - core
+// - management
+// if missing, add it to _data/wildfly-categories and use its id
+categories:
+- microprofile
+// Specify the stability level of the feature.
+// Values can be one of: experimental preview community default
+stability-level: default
+// Specify the Feature Development tracker issue for the feature.
+// This must be an issue tracked in https://github.com/orgs/wildfly/projects/7/views/1.
+// To create a Feature Development tracker issue, go to  https://github.com/wildfly/wildfly-proposals/issues/new/choose
+// and select 'Feature Development'
+issue: https://github.com/wildfly/wildfly-proposals/issues/637
+// Provide the github ids of the members of the feature team, organized by role.
+// Provide a single id for the 'assignee' role. Use a yaml list for the 'sme' and
+// 'outside-perspective' roles, even if there is only one person in a role.
+feature-team:
+ developer: kabir
+ sme:
+  -
+ outside-perspective:
+  -
+// If this issue tracks the promotion to a higher stability level of a previously
+// completed feature, provide the URL of the https://github.com/wildfly/wildfly-proposals/issues
+// issue that was used to track the previous feature.
+promotes:
+// This should be blank during initial development of a feature. It may be used
+// after the feature is completed if a subsequent issue is field to track promotion
+// of this feature to a higher stability level
+promoted-by:
+---
+// Other properties
+:connector: AMQP
+:connector-lower: amqp
+:issue-id: WFLY-19836
+
+= Integrate OpenTelemetry with the MP Reactive Messaging {connector} connector
+:author:            Kabir Khan
+:email:             [email protected]
+:toc:               left
+:icons:             font
+:idprefix:
+:idseparator:       -
+
+
+
+== Overview
+
+SmallRye Reactive Messaging's {connector} connector allows for integration with OpenTelemetry tracing so that we can track messages sent to and received from {connector} via this connector.
+
+This is controlled via the MicroProfile Config property `mp.messaging.connector.smallrye-{connector-lower}.tracing-enabled`. At present this is set to `false` in a `ConfigSource` set up by the integration with an `ordinal` value set to the maximum value. The result of this is that the user can never enable tracing to happen (since any attempt to set this property to `true` would be overridden by the mentioned `ConfigSource`).
+
+
+
+=== User Stories
+
+Users wish to be able to trace messages sent to/from {connector} via reactive messaging using MicroProfile Telemetry.
+
+== Issue Metadata
+
+* https://issues.redhat.com/browse/{issue-id}[{issue-id}] - Integrate OpenTelemetry with the MP Reactive Messaging {connector} connector
+
+=== Related Issues
+
+* https://issues.redhat.com/browse/WFLY-19846[WFLY-19846] - Promote MicroProfile Telemetry 2.0 to WildFly Standard
+
+
+=== Affected Projects or Components
+* https://github.com/wildfly/wildfly/ - All integration work is done here
+* https://github.com/smallrye/smallrye-reactive-messaging - contains the implementation of the Reactive Messaging connectors. No work is expected to be needed here, unless bugs are found.
+
+=== Other Interested Projects
+None to my knowledge
+
+=== Relevant Installation Types
+
+* Traditional standalone server (unzipped or provisioned by Galleon)
+* OpenShift Source-to-Image (S2I)
+* Bootable jar
+
+== Requirements
+
+It must be possible to turn the tracing on. To do this a resource called `subsystem=microprofile-reactive-messaging-smallrye/opentelemetry-tracing=config` is introduced.
+
+This resource contains an attribute called `{connector-lower}-connector`, which allows us to control if and how tracing is enabled. It is an enumeration with the following values:
+* `NEVER` - This is the default value of the attribute, and also the value that will be used if the `opentelemetry-tracing=config` child resource is not present in the subsystem. This is the same behaviour that has been available today, i.e. `mp.messaging.connector.smallrye-{connector-lower}.tracing-enabled` is forced to be `false` in such a way that user's MicroProfile Config properties can never set it to `true`.
+* `OFF` - `mp.messaging.connector.smallrye-{connector-lower}.tracing-enabled` is set to `false`, but a user can override it to set it to `true`.
+* `ON` - `mp.messaging.connector.smallrye-{connector-lower}.tracing-enabled` is set to `true`, but a user can override it to set it to `false`.
+* `ALWAYS` - `mp.messaging.connector.smallrye-{connector-lower}.tracing-enabled` is forced to be `true` in such a way that user's MicroProfile Config properties can never set it to `false`
+
+As mentioned in the link:#Overview[Overview], `mp.messaging.connector.smallrye-{connector-lower}.tracing-enabled` controls whether tracing happens. It is a boolean, and its values have these meanings:
+
+* `false` - OpenTelemetry tracing is not enabled for the {connector} connector
+* `true` - OpenTelemetry tracing is enabled for the {connector} connector
+
+When tracing is enabled, and the OpenTelemetry subsystem is configured to connect to a tracing collector, the traces should be available from there.
+
+=== Changed requirements
+
+N/A
+
+=== Non-Requirements
+
+N/A
+
+=== Future Work
+
+N/A
+
+== Backwards Compatibility
+
+If not configured, the default is the same as the existing behaviour, which is to not enable tracing, and to not allow users to enable it.
+
+=== Default Configuration
+
+No change
+
+=== Importing Existing Configuration
+
+Existing configurations will have the same behaviour as today. i.e. tracing is not enabled, and can not be turned on.
+
+=== Deployments
+
+No change.
+
+=== Interoperability
+
+N/A
+
+== Implementation Plan
+
+A single pull request to WildFLy will be created containing everything.
+
+== Admin Clients
+It is a simple resource with an attribute, so no work is needed in JBoss CLI/HAL
+
+== Security Considerations
+
+None, beyond the consideration that the collector of the traces will receive a lot of the data, and so must be secured as well.
+
+[[test_plan]]
+== Test Plan
+
+__<Depending on the selected stability level, the appropriate section below should be completed, including a brief description of how testing is to be performed in accordance with the selected stability level. The non-relevant sections may be removed as needed.>__
+////
+Depending on the stability level, the test plan required may vary. see below:
+////
+
+** Experimental - No test plan is required. Basic unit / integration tests should be added during development.
+
+** Preview - a brief high-level description of the testing approach should be added here, including types of tests added (unit, integration, smoke, component, subsystem, etc.) Note that not all test types are required for a particular feature, so include a description of what is being tested and the approach chosen to perform the testing.
+
+** Community - this level should include everything in the 'Preview' stability level, plus the following additional testing as relevant:
+*** Manual tests: briefly describe checks to be performed during one-time exploratory testing. The purpose of this testing is to check corner cases and other cases that are not worth implementing as automated tests. Typical checks are: bad configurations are easy to reveal, attribute descriptions and error messages are clear, names are descriptive and consistent with similar resources, default values are reasonable.
+*** Miscellaneous checks: Manual checks for significant changes in server performance, memory and disk footprint should be described here. These checks are not always relevant, but consideration of these impacts, and others, are strongly encouraged and should be described here. Fully qualified test case names should be provided along with a brief description of what the test is doing.
+*** Integration tests - at the 'Community' stability level, complete integration tests should be provided.
+*** Compatibility tests - if backwards compatibility is relevant to the feature, then describe how the testing is performed.
+
+** Default - This stability level is reserved and requires approval by a professional Quality Engineer with subject matter expertise.
+
+Two main tests will be created in WildFly's https://github.com/wildfly/wildfly/tree/main/testsuite/integration/microprofile[testsuite/integration/microprofile] module:
+
+1. We test all the combinations of the `{connector-lower}-connector` in the new
+ `subsystem=microprofile-reactive-messaging-smallrye/opentelemetry-tracing=config` resource, and values of `mp.messaging.connector.smallrye-{connector-lower}.tracing-enabled` set via the user's MicroProfile Config, and make sure that the resulting value of `mp.messaging.connector.smallrye-{connector-lower}.tracing-enabled` in the final MicroProfile Config used for the deployment has the value specified in the link:#Requirements[Requirements] section.
+2. Tesing tracing
+a. Ensure that tracing does not happen when tracing is disabled
+// This is currently a little bit vague, since I still have no idea how OpenTracing actually works, and have not been able to get my POC to work yet!
+b. Ensure that tracing happens when tracing is enabled, and that the traces contain the expected values.
+
+== Community Documentation
+
+The current https://github.com/wildfly/wildfly/blob/main/docs/src/main/asciidoc/_admin-guide/subsystem-configuration/MicroProfile_Reactive_Messsaging_SmallRye.adoc[MicroProfile Reactive Messaging Document] will be enhanced to cover the new resource and properties, and what this means.
+
+
+== Release Note Content
+
+You can now enable OpenTelemetry tracing for the MicroProfile Reactive Messaging {connector} connector.