Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Clarifying DistributedContext purpose #240

Merged
merged 4 commits into from
Oct 3, 2019
Merged

Clarifying DistributedContext purpose #240

Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
cac617c
Clarifying DistributedContext
toumorokoshi Sep 1, 2019
4536c90
Fix grammar and simplify wording
toumorokoshi Sep 3, 2019
1aab79e
Merge branch 'master' into feature/clarify-distributedcontext
SergeyKanzhelev Oct 1, 2019
47b6ae1
Merge branch 'master' into feature/clarify-distributedcontext
SergeyKanzhelev Oct 3, 2019
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
15 changes: 7 additions & 8 deletions specification/overview.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -183,19 +183,18 @@ document.

## DistributedContext

**DistributedContext** is an abstract data type that represents collection of entries.
Each key of **DistributedContext** is associated with exactly one value. **DistributedContext** is serializable,
to facilitate propagating it not only inside the process but also across process boundaries.
The **DistributedContext** exists to store labels that describe the context of an operation an application performs. It is intended to enable context that are custom to the application or integrations in contrast to other contexts, such as `SpanContext`. Only one **DistributedContext** should be associated with any particular operation.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
The **DistributedContext** exists to store labels that describe the context of an operation an application performs. It is intended to enable context that are custom to the application or integrations in contrast to other contexts, such as `SpanContext`. Only one **DistributedContext** should be associated with any particular operation.
The **DistributedContext** exists to store labels that describe the context of an operation an application performs. It is intended to enable context that is custom to the application or integrations in contrast to other contexts, such as `SpanContext`. Only one **DistributedContext** should be associated with any particular operation.

Assuming you want "context" to be singular here, I don't know about "integrations" though.


For example, a web service can benefit from including context around what service has sent the request. Or a SaaS provider can include context about the API user or token that is responsible for that request. These values can be consumed from **DistributedContext** and used as an additional dimension for a metric, or additional context for logs and traces.

**DistributedContext** is used to annotate telemetry with the name:value pair **Entry**.
Those values can be used to add dimension to the metric or additional contest properties to logs and traces.
**DistributedContext** is a collection of key-value `Entry` pairs, with each key of associated with exactly one value. **DistributedContext** is serializable,
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
**DistributedContext** is a collection of key-value `Entry` pairs, with each key of associated with exactly one value. **DistributedContext** is serializable,
**DistributedContext** is a collection of key-value `Entry` pairs, with each key associated with exactly one value. **DistributedContext** is serializable,

to facilitate propagating it not only inside the process but also across process boundaries.

**DistributedContext** is a recommended name but languages can have more language-specific names like **dctx**.

### Entry

An **Entry** is used to label anything that is associated with a specific operation,
such as an HTTP request. It consists of **EntryKey**, **EntryValue** and **EntryMetadata**.
An **Entry** is used to represent the labels that are contained inside the `DistributedContext`, representing values such as the service that originated the request, or vendor-specific data. It consists of an **EntryKey**, an **EntryValue** and an **EntryMetadata**.

- **EntryKey** is the name of the **Entry**. **EntryKey** along with **EntryValue**
can be used to aggregate and group stats, annotate traces and logs, etc. **EntryKey** is
Expand All @@ -205,7 +204,7 @@ a length greater than zero and less than 256.
- **EntryMetadata** contains properties associated with an **Entry**.
For now only the property **EntryTTL** is defined.
- **EntryTTL** is an integer that represents number of hops an entry can propagate.
Anytime a sender serializes an entry, sends it over the wire and receiver unserializes
Anytime a sender serializes an entry, sends it over the wire and a receiver deserializes
the entry then the entry is considered to have travelled one hop.

## Resources
Expand Down