Document that ZoneContextManager doesn't work with async/await code that targets ES2017+

[ajbouh]

ZoneContextManager is based on zone.js, which is a part of the Angular project.

Unfortunately, zone.js can't track context within an AsyncFunction in the web browser: angular/angular#31730

If my understanding of the OpenTelemetry APIs and documentation is correct, then this fact is probably very surprising to many OpenTelemetry users.

As an OpenTelemetry user, my choices seem to be:

1. be ok with incorrectly nested spans
   (I'm not ok with this)
2. build my entire application without async/await
   (I don't love .then and }) staircases enough to do this)
3. ensure my entire application is transpiled back to ES2015
   (makes debugging very challenging)
4. use explicit context propagation in all asynchronous code paths
   (feels wrong since it makes it very expensive to switch a codepath from sync to async)
5. use explicit context propagation everywhere
   (winner winner chicken dinner)

Based on my reading of the associated issue threads, it seems unlikely that zone.js will ever be able to support ES2017+ async/await. I can add these as links if they'd be helpful to others.

Assuming I'm not missing anything, I think the OpenTelemetry documentation should be updated to highlight this (major) shortcoming of ZoneContextManager. This project might even consider advocating for users to just start using explicit context propagation in the first place.

In the medium term it might make sense to drop implicit context propagation altogether.

[dyladan]

Hmm. I think at the very least we need some docs updates here, but I don't think this is actually a bug as there are no behavior changes requested.

Regarding the suggested docs, I think we should suggest that if users are using the Zone context manager, they should transpile to ES2015. If that is not an option, explicit context propagation is the fallback choice. The main reason for this is that transpiling doesn't require code changes to the user application in order to make tracing work.

[ajbouh]

Ah you're right I did not specify a change in behavior beyond updating the documentation.

I can rectify this. First, I don't know whether or not opentelemetry-js should be targeting ES2017. This seems like it might be wrong?

Second, I don't think these APIs should be reliant on implicit global context to generate properly nested traces. Many of the functions seem to use a default parameter of context.active() or something along these lines.

[ajbouh]

It's also (imo) clearly a bug that tracing in the browser is broken by default in modern browsers when using modern JavaScript.

Since wrong nesting for traces can mean missing or faulty propagation values, this bug can affect server side traces that use values from the browser implementation.

[dyladan]

We are going to document that an end user application using the Zone context manager should target ES2015. If that is not possible, we will recommend users manually propagate context. Dropping implicit context management is not feasible as it would possibly violate spec, and much of the code is shared with node.js which propagates context without problems.

See related Zone.js/angular issue angular/angular#31730