Proposal: Separate Layer for Context Propagation #66

tedsuo · 2019-11-15T09:45:10Z

This proposal provides a high level description of OpenTelemetry, which shows how context propagation, observability, and baggage could be cleanly decoupled.

This is a second draft of the OTEP originally submitted in #42. It is resubmitted as a new PR, as much has changed. Link to a readable version of the latest draft can be found here.

Changes from the first draft:

Use language from aspect-oriented programming to describe cross-cutting concerns (the term "distributed application" was too confusing).
Removed detailed descriptions of the observability APIs, they were too distracting.
Focused less on correlations, as this OTEP does not intent to define the details of that API.
Added links to prototypes in four languages: Go, Java, Python, and Ruby.
Added examples in pseudocode.
General cleanup in response to feedback.

A couple of notes on terminology:

In this doc, I refer to TagMap as Correlations, and Tags as Labels. There can be a separate discussion for what to name this, but since Tag has repeatedly come up as a contentious name for this feature, I tried to use something "similar but different" to avoid this debate. I actually feel that the term correlation contains a more accurate meaning than tag, so it may be an improvement.

The goal with this spec proposal is to find a way to describe these public APIs as simple as possible, but no simpler. This description is meant to be high level, but not inaccurate. If a detail appears to be missing, it is intentional - presumably handled at the SDK layer. Possibly, it should be present. Please review this document with this in mind.

Co-Authored-By: Christian Neumüller <christian+github@neumueller.me>

Co-Authored-By: Reiley Yang <reyang@microsoft.com>

* Remove registry concept * Add explicit chaining

text/0066-separate-context-propagation.md

kbrockhoff · 2020-01-16T23:01:59Z

I think the overall concept of this proposal is great. Providing a universal, reliable mechanism for transmitting context throughout a system could make OpenTelemetry attractive to development teams currently not using an observability framework.

text/0066-separate-context-propagation.md

Co-Authored-By: Mauricio Vásquez <mauricio@kinvolk.io>

tedsuo · 2020-01-17T23:20:01Z

@bogdandrutu @SergeyKanzhelev since this has approval, and is primarily meant to describe the high-level goals, I would like to go ahead and merge it. We can continue discussion about the API details in spec PRs, based on the prototypes.

c24t

LGTM to move this forward to specs.

* Proposal to separate context propagation from observability * cleanup description for Extract * commas Co-Authored-By: Christian Neumüller <christian+github@neumueller.me> * Update text/0000-separate-context-propagation.md Co-Authored-By: Christian Neumüller <christian+github@neumueller.me> * RFC proposal: A layered approach to data formats * whitespace Co-Authored-By: Reiley Yang <reyang@microsoft.com> * Capitalization Co-Authored-By: Reiley Yang <reyang@microsoft.com> * whitespace Co-Authored-By: Reiley Yang <reyang@microsoft.com> * CleanBaggage -> ClearBaggage * move function descriptions to new line * Add Optional subheader * cleanup rough edits * clean up advice on pre-existing context implementations * Better context descriptions * remove data format file * remove git diff message * improved code sytnax * stop stuttering * Update text/0000-separate-context-propagation.md Co-Authored-By: Reiley Yang <reyang@microsoft.com> * spacing * Refine propagation * Remove registry concept * Add explicit chaining * Add RFC ID number from PR * remove RFC status line * slight calrification for GetHTTPExtractor * add global propagators * Clean up motivation * Clean up explanbation intro * Clarify context types * Fix ChainHTTPInjector and ChainHTTPExtractor * typo * Reference Trace-Context, not just traceparent * Bagge context cleanup * stronger language around context access * Update text/0042-separate-context-propagation.md Co-Authored-By: Christian Neumüller <christian+github@neumueller.me> * clean up tradeoffs * v2.0 of this OTEP * Update OTEP number for new submission * remove image file for unused diagram * Update text/0066-separate-context-propagation.md Co-Authored-By: alrex <alrex.boten@gmail.com> * Link to Erlang prototype * whitespace * ToC * Update text/0066-separate-context-propagation.md Co-Authored-By: Tristan Sloughter <t@crashfast.com> * more context examples * typo * Update text/0066-separate-context-propagation.md Co-Authored-By: Yusuke Tsutsumi <tsutsumi.yusuke@gmail.com> * Apply suggestions from code review Co-Authored-By: Yuri Shkuro <yurishkuro@users.noreply.github.com> * Renamed aspects to "cross-cutting concerns" * injectors are a list instead of chained * clean up API representation * cleanup examples * typo * remove correlations from proposal * Update text/0066-separate-context-propagation.md Co-Authored-By: Yuri Shkuro <yurishkuro@users.noreply.github.com> * remove the term "chaining" * remove the terms upstream and downstream * improved architecturural explanation * whitespace * update link to Go prototype * Removed the Baggage API; replaced it with Correlations. * Fix the intro paragraph for Correlations * git merges ate my homework * some sentences were out of order * Clarify that correltions must be propagated * Clarify risks * removed extra header * Clarify definition of aspect-oriented programming * Fix RemoveCorrelation * Spelling * Update text/0066-separate-context-propagation.md Co-Authored-By: Sergey Kanzhelev <S.Kanzhelev@live.com> * Clarifying details * Update python prototype * Update text/0066-separate-context-propagation.md Co-Authored-By: Tyler Yahn <MrAlias@users.noreply.github.com> * Update text/0066-separate-context-propagation.md Co-Authored-By: Tyler Yahn <MrAlias@users.noreply.github.com> * Update text/0066-separate-context-propagation.md Co-Authored-By: Tyler Yahn <MrAlias@users.noreply.github.com> * Clarify that the APIs and example code are not meant as final. Add C# prototype * Inject returns headers, not context * Update text/0066-separate-context-propagation.md Co-Authored-By: Mauricio Vásquez <mauricio@kinvolk.io> * spelling * remove spurious go comment Co-authored-by: Christian Neumüller <christian+github@neumueller.me> Co-authored-by: Reiley Yang <reyang@microsoft.com> Co-authored-by: alrex <alrex.boten@gmail.com> Co-authored-by: Tristan Sloughter <t@crashfast.com> Co-authored-by: Yusuke Tsutsumi <tsutsumi.yusuke@gmail.com> Co-authored-by: Yuri Shkuro <yurishkuro@users.noreply.github.com> Co-authored-by: Sergey Kanzhelev <S.Kanzhelev@live.com> Co-authored-by: Tyler Yahn <MrAlias@users.noreply.github.com> Co-authored-by: Mauricio Vásquez <mauricio@kinvolk.io>

…s#66) * Proposal to separate context propagation from observability * cleanup description for Extract * commas Co-Authored-By: Christian Neumüller <christian+github@neumueller.me> * Update text/0000-separate-context-propagation.md Co-Authored-By: Christian Neumüller <christian+github@neumueller.me> * RFC proposal: A layered approach to data formats * whitespace Co-Authored-By: Reiley Yang <reyang@microsoft.com> * Capitalization Co-Authored-By: Reiley Yang <reyang@microsoft.com> * whitespace Co-Authored-By: Reiley Yang <reyang@microsoft.com> * CleanBaggage -> ClearBaggage * move function descriptions to new line * Add Optional subheader * cleanup rough edits * clean up advice on pre-existing context implementations * Better context descriptions * remove data format file * remove git diff message * improved code sytnax * stop stuttering * Update text/0000-separate-context-propagation.md Co-Authored-By: Reiley Yang <reyang@microsoft.com> * spacing * Refine propagation * Remove registry concept * Add explicit chaining * Add RFC ID number from PR * remove RFC status line * slight calrification for GetHTTPExtractor * add global propagators * Clean up motivation * Clean up explanbation intro * Clarify context types * Fix ChainHTTPInjector and ChainHTTPExtractor * typo * Reference Trace-Context, not just traceparent * Bagge context cleanup * stronger language around context access * Update text/0042-separate-context-propagation.md Co-Authored-By: Christian Neumüller <christian+github@neumueller.me> * clean up tradeoffs * v2.0 of this OTEP * Update OTEP number for new submission * remove image file for unused diagram * Update text/0066-separate-context-propagation.md Co-Authored-By: alrex <alrex.boten@gmail.com> * Link to Erlang prototype * whitespace * ToC * Update text/0066-separate-context-propagation.md Co-Authored-By: Tristan Sloughter <t@crashfast.com> * more context examples * typo * Update text/0066-separate-context-propagation.md Co-Authored-By: Yusuke Tsutsumi <tsutsumi.yusuke@gmail.com> * Apply suggestions from code review Co-Authored-By: Yuri Shkuro <yurishkuro@users.noreply.github.com> * Renamed aspects to "cross-cutting concerns" * injectors are a list instead of chained * clean up API representation * cleanup examples * typo * remove correlations from proposal * Update text/0066-separate-context-propagation.md Co-Authored-By: Yuri Shkuro <yurishkuro@users.noreply.github.com> * remove the term "chaining" * remove the terms upstream and downstream * improved architecturural explanation * whitespace * update link to Go prototype * Removed the Baggage API; replaced it with Correlations. * Fix the intro paragraph for Correlations * git merges ate my homework * some sentences were out of order * Clarify that correltions must be propagated * Clarify risks * removed extra header * Clarify definition of aspect-oriented programming * Fix RemoveCorrelation * Spelling * Update text/0066-separate-context-propagation.md Co-Authored-By: Sergey Kanzhelev <S.Kanzhelev@live.com> * Clarifying details * Update python prototype * Update text/0066-separate-context-propagation.md Co-Authored-By: Tyler Yahn <MrAlias@users.noreply.github.com> * Update text/0066-separate-context-propagation.md Co-Authored-By: Tyler Yahn <MrAlias@users.noreply.github.com> * Update text/0066-separate-context-propagation.md Co-Authored-By: Tyler Yahn <MrAlias@users.noreply.github.com> * Clarify that the APIs and example code are not meant as final. Add C# prototype * Inject returns headers, not context * Update text/0066-separate-context-propagation.md Co-Authored-By: Mauricio Vásquez <mauricio@kinvolk.io> * spelling * remove spurious go comment Co-authored-by: Christian Neumüller <christian+github@neumueller.me> Co-authored-by: Reiley Yang <reyang@microsoft.com> Co-authored-by: alrex <alrex.boten@gmail.com> Co-authored-by: Tristan Sloughter <t@crashfast.com> Co-authored-by: Yusuke Tsutsumi <tsutsumi.yusuke@gmail.com> Co-authored-by: Yuri Shkuro <yurishkuro@users.noreply.github.com> Co-authored-by: Sergey Kanzhelev <S.Kanzhelev@live.com> Co-authored-by: Tyler Yahn <MrAlias@users.noreply.github.com> Co-authored-by: Mauricio Vásquez <mauricio@kinvolk.io>

tedsuo and others added 30 commits September 9, 2019 18:04

Proposal to separate context propagation from observability

dff8df9

cleanup description for Extract

5ad7d1c

commas

1dc3c7b

Co-Authored-By: Christian Neumüller <christian+github@neumueller.me>

Update text/0000-separate-context-propagation.md

58248e6

Co-Authored-By: Christian Neumüller <christian+github@neumueller.me>

RFC proposal: A layered approach to data formats

68cb0ba

whitespace

3dc6a76

Co-Authored-By: Reiley Yang <reyang@microsoft.com>

Capitalization

459435e

Co-Authored-By: Reiley Yang <reyang@microsoft.com>

whitespace

c9c64f4

Co-Authored-By: Reiley Yang <reyang@microsoft.com>

CleanBaggage -> ClearBaggage

c3c7c24

move function descriptions to new line

4588096

Add Optional subheader

2d80dae

cleanup rough edits

7a73210

clean up advice on pre-existing context implementations

0d8e41b

Better context descriptions

aad5605

remove data format file

4a930eb

remove git diff message

e1ef61f

improved code sytnax

f949435

stop stuttering

1cb155e

Update text/0000-separate-context-propagation.md

7b9e861

Co-Authored-By: Reiley Yang <reyang@microsoft.com>

spacing

07eb397

Refine propagation

0ebeb6c

* Remove registry concept * Add explicit chaining

Add RFC ID number from PR

147d6b0

remove RFC status line

72d4651

slight calrification for GetHTTPExtractor

1472197

add global propagators

18a37d4

Clean up motivation

7ea1834

Clean up explanbation intro

7317747

Clarify context types

43ba8fd

Fix ChainHTTPInjector and ChainHTTPExtractor

d7d6f1c

typo

3a817a2

mauriciovasquezbernal reviewed Jan 16, 2020

View reviewed changes

text/0066-separate-context-propagation.md Outdated Show resolved Hide resolved

tsloughter approved these changes Jan 16, 2020

View reviewed changes

MrAlias approved these changes Jan 16, 2020

View reviewed changes

mwear approved these changes Jan 16, 2020

View reviewed changes

yurishkuro approved these changes Jan 16, 2020

View reviewed changes

Inject returns headers, not context

f306810

mauriciovasquezbernal reviewed Jan 17, 2020

View reviewed changes

text/0066-separate-context-propagation.md Outdated Show resolved Hide resolved

tedsuo and others added 3 commits January 16, 2020 23:02

Merge branch 'master' into context-prop-2

4c605c9

Update text/0066-separate-context-propagation.md

b7efba5

Co-Authored-By: Mauricio Vásquez <mauricio@kinvolk.io>

spelling

630d954

iredelmeier approved these changes Jan 17, 2020

View reviewed changes

remove spurious go comment

a43b5d7

c24t approved these changes Jan 17, 2020

View reviewed changes

tedsuo merged commit 322da45 into open-telemetry:master Jan 18, 2020

tedsuo deleted the context-prop-2 branch January 18, 2020 00:10

Oberon00 mentioned this pull request Jan 28, 2020

Allow resources as span attributes open-telemetry/opentelemetry-specification#274

Open

dyladan mentioned this pull request Jan 29, 2020

Separate layer for context propagation open-telemetry/opentelemetry-js#741

Closed

jtescher mentioned this pull request Jan 30, 2020

Add Layer for Context Propagation open-telemetry/opentelemetry-rust#62

Closed

c24t mentioned this pull request Feb 4, 2020

Combined Metrics API updates for v0.3 (Add Observer instrument, remove Gauge instrument, etc.) open-telemetry/opentelemetry-specification#430

Merged

Oberon00 mentioned this pull request Mar 29, 2020

How should other forms of trace/span ids be handled? open-telemetry/opentelemetry-specification#525

Open

mwear mentioned this pull request Apr 28, 2020

Allow injectors and extractors to be separate interfaces open-telemetry/opentelemetry-specification#578

Merged

dyladan mentioned this pull request Apr 30, 2020

Spec Change: Allow injectors and extractors to be separate interfaces open-telemetry/opentelemetry-js#1006

Closed

Oberon00 mentioned this pull request Jun 7, 2020

grpc-trace-bin support for gRPC trace? open-telemetry/opentelemetry-specification#639

Closed

Oberon00 mentioned this pull request Aug 26, 2020

Update Sampler.ShouldSample parent parameter to be Context open-telemetry/opentelemetry-specification#881

Merged

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Proposal: Separate Layer for Context Propagation #66

Proposal: Separate Layer for Context Propagation #66

tedsuo commented Nov 15, 2019 •

edited

Loading

kbrockhoff commented Jan 16, 2020

tedsuo commented Jan 17, 2020

c24t left a comment

Proposal: Separate Layer for Context Propagation #66

Proposal: Separate Layer for Context Propagation #66

Conversation

tedsuo commented Nov 15, 2019 • edited Loading

kbrockhoff commented Jan 16, 2020

tedsuo commented Jan 17, 2020

c24t left a comment

Choose a reason for hiding this comment

tedsuo commented Nov 15, 2019 •

edited

Loading