Change Details

//Current state// Service-utils contains experimental support for [[ https://gitlab.wikimedia.org/repos/data-engineering/service-utils#trace-propagation | x-request-id context propagation ]] that integrates with the OpenTelemetry Node SDK, which is already used by some adopter teams - e.g., Abstract Wikipedia. Based on some initial investigation and functional testing, as well as discussion with that team, we believe this functionality already works as expected. However, there are three areas where we could provide improved documentation, or batteries-included helpers: 1. **Production-appropriate NodeSDK initialization** - This was a pain-point during integration by Abstract Wikipedia, where it was challenging to adapt their container-image entrypoint to use the typical `--require` technique to inject instrumentation setup, and they instead settled on an approach that modifies their main application script (i.e., setting up instrumentation, and then loading the application code via a dynamic import). 2. **Production configuration** - While it's relatively easy to initialize the NodeSDK in a way that provides trace propagation, additional configuration is necessary to actually collect spans from autointrumentation or application-level spans (e.g., setting `OTEL_EXPORTER_OTLP_ENDPOINT`). 3. **Mental model** - A clearer mental model of how this all fits together and what to expect. This would make it a lot easier to understand subtle differences between development and production, and more generally debug issues when traces are found to be incomplete. //Definition of done// (DRAFT) * Documentation improvements that cover all three of these. * Moving the `XRequestPropagator` out of `@experimental` stability (//after// moving it to a subpath export - T416756#11609350). * [maybe] Some sort of batteries-included NodeSDK initialization helper, analogous to that used in, e.g., [[ https://gitlab.wikimedia.org/repos/abstract-wiki/wikifunctions/function-orchestrator/-/blob/main/instrumentTelemetry.js | function-orchestrator ]].

//Current state// Service-utils contains experimental support for [[ https://gitlab.wikimedia.org/repos/data-engineering/service-utils#trace-propagation | x-request-id context propagation ]] that integrates with the OpenTelemetry Node SDK, which is already used by some adopter teams - e.g., Abstract Wikipedia. Based on some initial investigation and functional testing, as well as discussion with that team, we believe this functionality already works as expected. However, there are three areas where we could provide improved documentation, or batteries-included helpers: 1. **Production-appropriate NodeSDK initialization** - This was a pain-point during integration by Abstract Wikipedia, where it was challenging to adapt their container-image entrypoint to use the typical `--require` technique to inject instrumentation setup, and they instead settled on an approach that modifies their main application script (i.e., setting up instrumentation, and then loading the application code via a dynamic import). 2. **Production configuration** - While it's relatively easy to initialize the NodeSDK in a way that provides trace propagation, additional configuration is necessary to actually collect spans from autointrumentation or application-level spans (e.g., setting `OTEL_EXPORTER_OTLP_ENDPOINT`). 3. **Mental model** - A clearer mental model of how this all fits together and what to expect. This would make it a lot easier to understand subtle differences between development and production, and more generally debug issues when traces are found to be incomplete. //Definition of done// * [done] Fix lingering issues around instrumentation initialization identified during testing and update existing adopters. - T416756#11657003 * [done] Documentation improvements that cover all three of these. - T416756#11630598 * Moving the `XRequestPropagator` out of `@experimental` stability (//after// moving it to a subpath export - T416756#11609350). * [declined] ~~Some sort of batteries-included NodeSDK initialization helper, analogous to that used in, e.g., [[ https://gitlab.wikimedia.org/repos/abstract-wiki/wikifunctions/function-orchestrator/-/blob/main/instrumentTelemetry.js | function-orchestrator ]].~~ - T416756#11683524

//Current state// Service-utils contains experimental support for [[ https://gitlab.wikimedia.org/repos/data-engineering/service-utils#trace-propagation | x-request-id context propagation ]] that integrates with the OpenTelemetry Node SDK, which is already used by some adopter teams - e.g., Abstract Wikipedia. Based on some initial investigation and functional testing, as well as discussion with that team, we believe this functionality already works as expected. However, there are three areas where we could provide improved documentation, or batteries-included helpers: 1. **Production-appropriate NodeSDK initialization** - This was a pain-point during integration by Abstract Wikipedia, where it was challenging to adapt their container-image entrypoint to use the typical `--require` technique to inject instrumentation setup, and they instead settled on an approach that modifies their main application script (i.e., setting up instrumentation, and then loading the application code via a dynamic import). 2. **Production configuration** - While it's relatively easy to initialize the NodeSDK in a way that provides trace propagation, additional configuration is necessary to actually collect spans from autointrumentation or application-level spans (e.g., setting `OTEL_EXPORTER_OTLP_ENDPOINT`). 3. **Mental model** - A clearer mental model of how this all fits together and what to expect. This would make it a lot easier to understand subtle differences between development and production, and more generally debug issues when traces are found to be incomplete. //Definition of done// (DRAFT) * [done] Fix lingering issues around instrumentation initialization identified during testing and update existing adopters. - T416756#11657003 * [done] Documentation improvements that cover all three of these. - T416756#11630598 * Moving the `XRequestPropagator` out of `@experimental` stability (//after// moving it to a subpath export - T416756#11609350). * [maybe] * [declined] ~~Some sort of batteries-included NodeSDK initialization helper, analogous to that used in, e.g., [[ https://gitlab.wikimedia.org/repos/abstract-wiki/wikifunctions/function-orchestrator/-/blob/main/instrumentTelemetry.js | function-orchestrator ]].~~ - T416756#11683524