diff --git a/microprofile/WFLY-19835_microprofile_reactive_messaging_otel_with_kafka.adoc b/microprofile/WFLY-19835_microprofile_reactive_messaging_otel_with_kafka.adoc index 102b834e..99bf14df 100644 --- a/microprofile/WFLY-19835_microprofile_reactive_messaging_otel_with_kafka.adoc +++ b/microprofile/WFLY-19835_microprofile_reactive_messaging_otel_with_kafka.adoc @@ -50,8 +50,18 @@ promoted-by: 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`). +In SmallRye Reactive Messaging, a set of MicroProfile Config properties are used to control whether tracing happens on a reactive messaging channel. These are: +* `mp.messaging.connector.smallrye-{connector-lower}.tracing-enabled` - This is a connector level property. 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`). +* The above property may in turn be overridden by the following channel level properties. +** `mp.messaging.outgoing..tracing-enabled` - Channel level property, controlling the OpenTelemetry tracing integration for an outgoing channel. +** `mp.messaging.incoming..tracing-enabled` - Channel level property, controlling the OpenTelenetry integration for an incoming channel. + +The way the SmallRye Reactive Messaging configuration system works is that it will first check for relevant channel level properties. If those are not present, it will look for the related connector level property, and if that is not available it will use a default. + +Internally in SmallRye Reactive Messaging, the default value for the tracing integration is that it is always enabled for a channel if not specified with above properties. + +This RFE is about allowing users to enable tracing via OpenTelemetry in WildFly, and also to be able to continue to ban it. === User Stories @@ -77,27 +87,29 @@ None to my knowledge === Relevant Installation Types * Traditional standalone server (unzipped or provisioned by Galleon) +* Managed domain * 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. +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 adds a capability requirement on the MicroProfile Telemetry subsystem, which in turn requires the OpenTelemetry subsystem. The OpenTelemetry subsystem configures how tracing happens. 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` +* `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. the MicroProfile Config properties mentioned in the link:#overview[Overview] will not have any effect, and tracing will be disabled. +* `OFF` - By default tracing will be disabled, but a user can use the MicroProfile Config properties from the link:#overview[Overview] to turn on tracing for a connector or individual channel in an application. +* `ON` - Similar to `OFF` but the default is to enable tracing for all channels, unless overridden for the application with the MicroProfile Config properties from the link:#overview[Overview]. +* `ALWAYS` - Tracing is enabled for all channels, and can not be turned off with the MicroProfile Config properties from the link:#overview[Overview]. -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: +The MicroProfile Config properties in the link:#Overview[Overview], are all booleans, and the values have these meanings: -* `false` - OpenTelemetry tracing is not enabled for the {connector} connector -* `true` - OpenTelemetry tracing is enabled for the {connector} connector +* `false` - OpenTelemetry tracing is not enabled +* `true` - OpenTelemetry tracing is enabled 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 @@ -116,7 +128,7 @@ If not configured, the default is the same as the existing behaviour, which is t === Default Configuration -No change +No change, and the behaviour is the same as before, which is to not enable tracing. === Importing Existing Configuration @@ -143,18 +155,21 @@ None, beyond the consideration that the collector of the traces will receive a l [[test_plan]] == Test Plan + +A unit test will be added in WildFly's `wildfly-microprofile-reactive-messaging-config` to make sure that the combinations of the new `{connector-lower}-connector` attribute and the MicroProfile Config properties controlling tracing yield the expected final value (e.g. if `{connector-lower}-connector=NEVER`, we check that the resulting value is always `false` no matter what we specify for the MicroProfile Config properties). + 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. + `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 resulting value specified in the link:#Requirements[Requirements] section. We only do this for the connector level attribute since the same code is used to handle the value of `{connector-lower}-connector` at runtime. The mentioned unit test has more coverage. +2. Testing tracing. The aim here is to test some combinations, and not all. +a. Ensure that tracing does not happen when tracing is disabled by setting `{connector-lower}-connector=NEVER` +b. Ensure that tracing happens when `{connector-lower}-connector=OFF` but is turned on for the deployment by specifying `mp.messaging.connector.smallrye-{connector-lower}.tracing-enabled=true`. Both sent and received messages will be traced. +c. When `{connector-lower}-connector=ON`, and `mp.messaging.incoming..tracing-enabled=false`, tracing will onlyt happen on the outgoing channel == 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. +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 its attributes, and how those values combine with the relevant MicroProfile Config Properties to control whether OpenTelemetry tracing happens. == Release Note Content