Skip to content

Commit 2a9d428

Browse files
toumorokoshiOberon00
authored andcommitted
Clarifying DistributedContext purpose (#240)
* Clarifying DistributedContext The DistributedContext section in the overview did not include examples, and started by describing the data structure rather than the purpose. Describing the purpose and use cases first will help better understand the use cases. * Fix grammar and simplify wording Co-Authored-By: Christian Neumüller <christian+github@neumueller.me>
1 parent d363231 commit 2a9d428

1 file changed

Lines changed: 7 additions & 8 deletions

File tree

specification/overview.md

Lines changed: 7 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -183,19 +183,18 @@ document.
183183

184184
## DistributedContext
185185

186-
**DistributedContext** is an abstract data type that represents collection of entries.
187-
Each key of **DistributedContext** is associated with exactly one value. **DistributedContext** is serializable,
188-
to facilitate propagating it not only inside the process but also across process boundaries.
186+
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.
187+
188+
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.
189189

190-
**DistributedContext** is used to annotate telemetry with the name:value pair **Entry**.
191-
Those values can be used to add dimension to the metric or additional contest properties to logs and traces.
190+
**DistributedContext** is a collection of key-value `Entry` pairs, with each key of associated with exactly one value. **DistributedContext** is serializable,
191+
to facilitate propagating it not only inside the process but also across process boundaries.
192192

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

195195
### Entry
196196

197-
An **Entry** is used to label anything that is associated with a specific operation,
198-
such as an HTTP request. It consists of **EntryKey**, **EntryValue** and **EntryMetadata**.
197+
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**.
199198

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

211210
## Resources

0 commit comments

Comments
 (0)