elastic / elastic/apm-agent-nodejs
add `withSpan` and `withTransaction` API
- Dominant language
- JavaScript
- Stars
- 594
- Forks
- 244
- Avg merge
- 1d 8h
- Merged PRs (30d)
- 16
Description
This issue is to add a `apm.withSpan(options, fn)` API (and similar for `withTransaction`) that critically takes a function to which the new RunContext is bound. This would avoid the https://github.com/elastic/apm-agent-nodejs/issues/2611 footgun that `startSpan` and `startTransaction` apply. A possible result of that footgun is shown and discussed at https://github.com/elastic/apm-agent-nodejs/pull/2929.
Adding this API has been [considered](https://gist.github.com/trentm/f39be34078872f6536a97c27ac485457) since the [RunContext work](https://github.com/elastic/apm-agent-nodejs/pull/2181).
A good test of this functionality would be whether it could fully or significantly replace the `withApmSpan` helper in Kibana (see https://github.com/elastic/kibana/blob/main/x-pack/plugins/apm/server/utils/with_apm_span.ts and https://github.com/elastic/kibana/blob/main/packages/kbn-apm-utils/index.ts).
This `apm.withSpan()` would be the equivalent of OTel JS's `tracer.startActiveSpan()`. The OTel `tracer.startSpan()` is already roughly equivalent to our *internal* `createSpan()` -- which was added in the RunContext work to cope with the `apm.startSpan()` footgun.
Eventually I think these APIs should be preferred and `startSpan()` and `startTransaction()` APIs should be deprecated.
Contributor guide
Assessment
This issue has not been assessed yet.