You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
* 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>
Copy file name to clipboardExpand all lines: specification/overview.md
+7-8Lines changed: 7 additions & 8 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -183,19 +183,18 @@ document.
183
183
184
184
## DistributedContext
185
185
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.
189
189
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.
192
192
193
193
**DistributedContext** is a recommended name but languages can have more language-specific names like **dctx**.
194
194
195
195
### Entry
196
196
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**.
199
198
200
199
-**EntryKey** is the name of the **Entry**. **EntryKey** along with **EntryValue**
201
200
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.
205
204
-**EntryMetadata** contains properties associated with an **Entry**.
206
205
For now only the property **EntryTTL** is defined.
207
206
-**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
209
208
the entry then the entry is considered to have travelled one hop.
0 commit comments