adonisjs / adonisjs/v7-docs

Incorrect explanation of propagating OTel context for queue jobs

Open
#43 1 comment 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

Dominant language
Edge
Stars
21
Forks
33
Avg merge
1d 11h
Merged PRs (30d)
1

Description

Hello,

The current section about propagating OTel context for queue jobs describes a mechanism to transmit the context from the producing context to the consuming context, but this is not the correct way to describe the relationship between the 2 otel traces.

injectTraceContext and extractTraceContext should be used to propagate context for synchronous, parent-child traces. For example, when a service A makes a request to a service B, then it makes sense for the trace in service B to a child of the trace in service A, since service A waits for the request to finish before continuing its execution.

But since the execution of a queued job could happen well after the end of the producing trace, Span Link are more appropriate for this use-case.

The Datadog doc describes the same mechanism: https://docs.datadoghq.com/tracing/trace_collection/span_links/#common-use-cases

If I get an approval from a maintainer, I can make a PR to change this section of the doc to use links instead

It might be a good idea to add a helper method in the adonisjs/otel package to make it easier to link 2 spans together. I'll see if I find the time to add this.

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Start with the linked “propagating to queue jobs” section and compare its explanation with the OpenTelemetry span links and Datadog references in the issue. Update the documentation so queued-job relationships are described accurately, then verify that the section consistently explains the intended propagation mechanism.

Written by the indexing model from the issue text.

Assessment

Domain
documentation, observability
Issue type
Documentation
Difficulty
2/5
Estimated time
1-3 hours
Activity status
Quiet
Clarity
Mostly clear
Newbie friendliness
55/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.