Text edits fixing missing words, spaces, etc (#323)

Author: mwear

spec/10-overview.md

@@ -18,10 +18,10 @@ This transformation of modern applications calls for a distributed tracing conte
 The trace context specification defines a universally agreed-upon format for the exchange of trace context propagation data - referred to as *trace context*. Trace context solves the problems described above by
 
 - providing an unique identifier for individual traces and requests, allowing trace data of multiple providers to be linked together.
-- providing an agreed-upon mechanism to forward vendor-specific trace data and avoid broken traces when multiple trace tools participate in a single transaction.
+- providing an agreed-upon mechanism to forward vendor-specific trace data and avoid broken traces when multiple tracing tools participate in a single transaction.
 - providing an industry standard that intermediaries, platforms, and hardware providers can support.
 
-A unified approach for propagating trace data improves visibility into the behavior of distributed applications, facilitating problem and performance analysis. The interoperability provided by trace-context is a prerequisite to manage modern micro-service based applications.
+A unified approach for propagating trace data improves visibility into the behavior of distributed applications, facilitating problem and performance analysis. The interoperability provided by trace context is a prerequisite to manage modern micro-service based applications.
 
 ## Design Overview
 
@@ -32,7 +32,7 @@ Trace context is split into two individual propagation fields supporting interop
 
 Tracing tools can provide two levels of compliant behavior interacting with trace context:
 
-- At a minimum they MUST propagate the `traceparent` and `tracestate` headers and guarantee traces are not broken. this behavior is also referred to as forwarding a trace.
+- At a minimum they MUST propagate the `traceparent` and `tracestate` headers and guarantee traces are not broken. This behavior is also referred to as forwarding a trace.
 - In addition they CAN also choose to participate in a trace by modifying the `traceparent` header and relevant parts of the `tracestate` header containing their proprietary information. This is also referred to as participating in a trace.
 
 A tracing tool can choose to change this behavior for each individual request to a component it is monitoring.

spec/20-http_header_format.md

@@ -32,7 +32,7 @@ traceparent: 00-0af7651916cd43dd8448eb211c80319c-00f067aa0ba902b7-01
 tracestate: rojo=00f067aa0ba902b7,congo=t61rcWkgMzE
 ```
 
-You'll notice that the Rojo system reuses the value of it’s `traceparent` for its entry in `tracestate`. This means it is a generic tracing system (no proprietary information is being passed). Otherwise, `tracestate` entries are opaque and can be vendor-specific.
+You'll notice that the Rojo system reuses the value of its `traceparent` for its entry in `tracestate`. This means it is a generic tracing system (no proprietary information is being passed). Otherwise, `tracestate` entries are opaque and can be vendor-specific.
 
 If the next receiving server uses Congo, it carries over the `tracestate` from Rojo and adds a new entry for the parent to the left of the previous entry.
 
@@ -68,7 +68,7 @@ Vendors MUST expect the header name in any case (upper, lower, mixed), and SHOUL
 
 ### traceparent Header Field Values
 
-This section uses the Augmented Backus-Naur Form (ABNF) notation of [[RFC5234](https://w3c.github.io/trace-context/#bib-rfc5234)], including the DIGIT rule from that document. `DIGIT` rule defines a single number character `0`-`9`.
+This section uses the Augmented Backus-Naur Form (ABNF) notation of [[RFC5234](https://w3c.github.io/trace-context/#bib-rfc5234)], including the DIGIT rule from that document. The `DIGIT` rule defines a single number character `0`-`9`.
 
 ``` abnf
 HEXDIGLC = DIGIT / "a" / "b" / "c" / "d" / "e" / "f" ; lowercase hex character
@@ -85,7 +85,7 @@ version         = 2HEXDIGLC   ; this document assumes version 00. Version 255 is
 
 The value is US-ASCII encoded (which is UTF-8 compliant).
 
-Version (`version`) is a 1 byte representing an 8-bit unsigned integer. Version `255` is invalid. The current specification assumes the `version` is set to `00`.
+Version (`version`) is 1 byte representing an 8-bit unsigned integer. Version `255` is invalid. The current specification assumes the `version` is set to `00`.
 
 #### version-format
 
@@ -103,10 +103,10 @@ trace-flags      = 2HEXDIGLC   ; 8 bit flags. Currently, only one bit is used. S
 This is the ID of the whole trace forest and is used to uniquely identify a [distributed trace](https://w3c.github.io/trace-context/#dfn-distributed-traces) through a system. It is represented as a 16-byte array, for example, `4bf92f3577b34da6a3ce929d0e0e4736`. All bytes as zero (`00000000000000000000000000000000`) is considered an invalid value.
 
 
-A vendor SHOULD generate globally unique values for `trace-id`. Many unique identification generation algorithms create IDs where one part of the value is constant (often time- or host-based), and the other part is a randomly generated value. Because tracing systems may make sampling decisions based on the value of `trace-id`, for increased interoperability vendors MUST  keep the random part of `trace-id` ID on the left side.
+A vendor SHOULD generate globally unique values for `trace-id`. Many unique identification generation algorithms create IDs where one part of the value is constant (often time- or host-based), and the other part is a randomly generated value. Because tracing systems may make sampling decisions based on the value of `trace-id`, for increased interoperability vendors MUST keep the random part of `trace-id` ID on the left side.
 
 
-When a system operates with a `trace-id` that is shorter than 16 bytes, it SHOULD fill-in the extra bytes with random values rather than zeroes. Let's say the system works with an 8-byte `trace-id` like `3ce929d0e0e4736`. Instead of setting `trace-id` value to `0000000000000003ce929d0e0e4736` it SHOULD generate a value like `4bf92f3577b34da6a3ce929d0e0e4736` where`4bf92f3577b34da6a` is a random value or a function of time and host value.
+When a system operates with a `trace-id` that is shorter than 16 bytes, it SHOULD fill-in the extra bytes with random values rather than zeroes. Let's say the system works with an 8-byte `trace-id` like `3ce929d0e0e4736`. Instead of setting `trace-id` value to `0000000000000003ce929d0e0e4736` it SHOULD generate a value like `4bf92f3577b34da6a3ce929d0e0e4736` where `4bf92f3577b34da6a` is a random value or a function of time and host value.
 
 
 **Note**: Even though a system may operate with a shorter `trace-id` for [distributed trace](https://w3c.github.io/trace-context/#dfn-distributed-traces) reporting, the full `trace-id` MUST be propagated to conform to the specification.
@@ -157,7 +157,7 @@ Various techniques include:
 
 - Probability sampling (sample 1 out of 100 <a>distributed traces</a> by flipping a coin)
 - Delayed decision (make collection decision based on duration or a result of a request)
-- Deferred sampling (let callee decide whether information about this request need to be collected)
+- Deferred sampling (let the callee decide whether information about this request needs to be collected)
 
 How these techniques are implemented can be tracing vendor-specific or application-defined.
 
@@ -207,12 +207,12 @@ base16(trace-flags) = 00  // not sampled
 
 ### Versioning of traceparent
 
-This specification is opinionated about future version of the trace context. The current version of this specification assumes that future versions of `traceparent` header will be additive to the current one.
+This specification is opinionated about future versions of trace context. The current version of this specification assumes that future versions of the `traceparent` header will be additive to the current one.
 
 Vendors MUST follow these rules when parsing headers with an unexpected format:
 
 - Pass-through services should not analyze the version. They should expect that headers may have larger size limits in the future and only disallow prohibitively large headers.
-- When the version prefix cannot be parsed (it's not 2 hex characters followed by a dash (`-`), the implementation should restart the trace.
+- When the version prefix cannot be parsed (it's not 2 hex characters followed by a dash (`-`)), the implementation should restart the trace.
 - If a higher version is detected, the implementation SHOULD try to parse it by trying the following:
     - If the size of the header is shorter than 55 characters, the vendor should not parse the header and should restart the trace.
     - Parse `trace-id` (from the first dash through the next 32 characters). Vendors MUST check that the 32 characters are hex, and that they are followed by a dash (`-`).
@@ -244,15 +244,15 @@ The `tracestate` field may contain any opaque value in any of the keys. Multiple
 
 This section uses the Augmented Backus-Naur Form (ABNF) notation of [[RFC5234](https://w3c.github.io/trace-context/#bib-rfc5234)], including the DIGIT rule in [appendix B.1 for RFC5234](https://tools.ietf.org/html/rfc5234#appendix-B.1). It also includes the `OWS` rule from [RFC7230 section 3.2.3](https://httpwg.org/specs/rfc7230.html#section-3.2.3).
 
-`DIGIT` rule defines number `0`-`9`.
+The `DIGIT` rule defines numbers `0`-`9`.
 
 The `OWS` rule defines an optional whitespace character. To improve readability, it is used where zero or more whitespace characters might appear.
 
 The caller SHOULD generate the optional whitespace as a single space; otherwise, a caller SHOULD NOT generate optional whitespace. See details in the [corresponding RFC](https://httpwg.org/specs/rfc7230.html#section-3.2.3).
 
 The `tracestate` field value is a `list` of `list-members` separated by commas (`,`). A `list-member` is a key/value pair separated by an equals sign (`=`). Spaces and horizontal tabs surrounding `list-member`s are ignored. There can be a maximum of 32 `list-member`s in a `list`.
 
-Empty and whitespace-only list members are allowed. Vendors MUST accept empty `tracestate `headers but SHOULD avoid sending them. Empty list members are allowed in `tracestate` because it is difficult for a vendor to recognize the empty value when multiple `tracestate` headers are sent. Whitespace characters are allowed for a similar reason, as some vendors automatically inject whitespace after a comma separator, even in the case of an empty header.
+Empty and whitespace-only list members are allowed. Vendors MUST accept empty `tracestate` headers but SHOULD avoid sending them. Empty list members are allowed in `tracestate` because it is difficult for a vendor to recognize the empty value when multiple `tracestate` headers are sent. Whitespace characters are allowed for a similar reason, as some vendors automatically inject whitespace after a comma separator, even in the case of an empty header.
 
 #### list
 
@@ -269,7 +269,7 @@ Identifiers for a `list` are short (up to 256 characters) textual identifiers.
 
 #### list-members
 
-A` list-member` contains a key/value pair.
+A `list-member` contains a key/value pair.
 
 ##### Key
 
@@ -288,7 +288,7 @@ For multi-tenant vendors scenarios, an at sign (`@`) sign can be used to prefix
 
 ##### Value
 
-The value is opaque string up to 256 characters printable ASCII [[RFC0020](https://w3c.github.io/trace-context/#bib-rfc0020)] characters (i.e., the range 0x20 to 0x7E) except comma (`,`) and (`=`). Note that this also excludes tabs, newlines, carriage returns, etc.
+The value is an opaque string up to 256 characters printable ASCII [[RFC0020](https://w3c.github.io/trace-context/#bib-rfc0020)] characters (i.e., the range 0x20 to 0x7E) except comma (`,`) and (`=`). Note that this also excludes tabs, newlines, carriage returns, etc.
 
 ``` abnf
 value    = 0*255(chr) nblk-chr
@@ -344,7 +344,7 @@ The version of `tracestate` is defined by the version prefix of `traceparent` he
 
 A vendor receiving a `traceparent` request header MUST send it to outgoing requests. It MAY mutate the value of this header before passing it to outgoing requests.
 
-If the value of the `traceparent` field wasn't changed before propagation, `tracestate` MUST NOT be modified as well. Unmodified headers propagation is typically implemented in pass-through services like proxies. This behavior may also be implemented in a service which currently does not collect distributed tracing information.
+If the value of the `traceparent` field wasn't changed before propagation, `tracestate` MUST NOT be modified as well. Unmodified header propagation is typically implemented in pass-through services like proxies. This behavior may also be implemented in a service which currently does not collect distributed tracing information.
 
 Following is the list of allowed mutations:
 
@@ -363,4 +363,4 @@ Following are allowed mutations:
 
 - **Update key value**. The value of any key can be updated. Modified keys MUST be moved to the beginning (left) of the list. This is the most common mutation resuming the trace.
 - **Add a new key/value pair**. The new key-value pair SHOULD be added to the beginning of the list.
-- **Delete a key/value pair**. Any key/value pair MAY be deleted. Vendors SHOULD NOT delete keys that were not generated by them. The deletion of an unknown key/value pair will break correlation in other systems. This mutation enables two scenarios. The first is that proxies can block certain `tracestate` keys for privacy and security concerns. The second scenario is a truncation of long `tracestate`'s.
+- **Delete a key/value pair**. Any key/value pair MAY be deleted. Vendors SHOULD NOT delete keys that were not generated by them. The deletion of an unknown key/value pair will break correlation in other systems. This mutation enables two scenarios. The first is that proxies can block certain `tracestate` keys for privacy and security concerns. The second scenario is a truncation of long `tracestate`s.

spec/21-http_header_format_rationale.md

@@ -114,7 +114,7 @@ Url encoding is low-overhead way to encode unicode characters for non-latin char
 
 ## Vendor name in a key
 
-Sign `@` is allowed in a key for easy parsing of vendor name out of the tracestate key. The idea is that with the registry of trace vendors one can easily understand the vendor name and how to parse it's trace state. Without `@` sign parsing will be more complicated. Also `@` sign has known semantics in addressing for protocols like ftp and e-mails.
+Sign `@` is allowed in a key for easy parsing of vendor name out of the tracestate key. The idea is that with the registry of tracing vendors one can easily understand the vendor name and how to parse it's trace state. Without `@` sign parsing will be more complicated. Also `@` sign has known semantics in addressing for protocols like ftp and e-mails.
 
 ## Versioning
 

spec/30-processing-model.md

@@ -25,7 +25,7 @@ If a `traceparent` header is received:
     * If the _version cannot be parsed_, the vendor creates a new `traceparent` header and deletes `tracestate`.
     * If the _version number is higher_ than supported by the tracer, the vendor uses the format defined in this specification (`00`) to parse `trace-id` and `parent-id`.
 The vendor will only parse the `trace-flags` values supported by this version of this specification and ignore all other values. If parsing fails, the vendor creates a new `traceparent` header and deletes the `tracestate`.
-    * If the vendor _supports the version number_, it validates `trace-id` and `parent-id`. If either `trace-id`, `parent-id` or `trace-flags` are invalid, the vendor creates a new `traceparent `header and deletes `tracestate`.
+    * If the vendor _supports the version number_, it validates `trace-id` and `parent-id`. If either `trace-id`, `parent-id` or `trace-flags` are invalid, the vendor creates a new `traceparent` header and deletes `tracestate`.
 3. The vendor MAY validate the `tracestate` header. If the `tracestate` header cannot be parsed the vendor MAY discard the entire header. Invalid `tracestate` entries MAY also be discarded.
 4. For each outgoing request the vendor performs the following steps:
     - The vendor MUST modify the `traceparent` header:
@@ -41,4 +41,4 @@ The vendor will only parse the `trace-flags` values supported by this version of
 
 ## Alternative Processing
 
-The processing model above describes the complete set of steps for processing trace context headers. There are, however, situations when a vendor might only support a subset of the steps described above. Proxies or messaging middleware MAY decide to not modify the `traceparent` headers but remove invalid headers or add additional information to `tracestate`.
+The processing model above describes the complete set of steps for processing trace context headers. There are, however, situations when a vendor might only support a subset of the steps described above. Proxies or messaging middleware MAY decide not to modify the `traceparent` headers but remove invalid headers or add additional information to `tracestate`.

spec/50-privacy.md

@@ -1,6 +1,6 @@
 # Privacy Considerations
 
-Requirements to propagate headers to downstream services, as well as storing values of these headers, open up potential privacy concerns. Trace vendors MUST NOT use `traceparent` and `tracestate` fields for any personally identifiable or otherwise sensitive information. The only purpose of these fields is to enable trace correlation.
+Requirements to propagate headers to downstream services, as well as storing values of these headers, open up potential privacy concerns. Tracing vendors MUST NOT use `traceparent` and `tracestate` fields for any personally identifiable or otherwise sensitive information. The only purpose of these fields is to enable trace correlation.
 
 Vendors MUST assess the risk of header abuse. This section provides some considerations and initial assessment of the risk associated with storing and propagating these headers. Tracing vendors may choose to inspect and remove sensitive information from the fields before allowing the tracing system to execute code that can potentially propagate or store these fields. All mutations should, however, conform to the list of mutations defined in this specification.