Merge pull request #314 from microsoft/client-request-id

Adding descriptions for x-ms-*-request-id headers

Author: markweitzel

azure/Guidelines.md

@@ -176,6 +176,7 @@ Array      | One of a) a comma-separated list of values (preferred), or b) separ
 
 The table below lists the headers most used by Azure services:
 
+
 Header Key          | Applies to | Example
 ------------------- | ---------- | -------------
 _authorization_     | Request    | Bearer eyJ0...Xd6j (Support Azure Active Directory)
@@ -197,6 +198,7 @@ _x-ms-error-code_   | Response   | (see [Handling Errors](#Handling-Errors))
 _azure-deprecating_ | Response   | (see [Deprecating Behavior](#Deprecating-Behavior))
 retry-after         | Response   | 180 (see [RFC 7231, Section 7.1.3](https://datatracker.ietf.org/doc/html/rfc7231#section-7.1.3))
 
+
 :white_check_mark: **DO** support all headers shown in _italics_
 
 :white_check_mark: **DO** specify headers using kebab-casing
@@ -1051,6 +1053,13 @@ Client libraries are required to send telemetry and distributed tracing informat
 - [Azure SDK Distributed tracing policy](https://azure.github.io/azure-sdk/general_azurecore.html#distributed-tracing-policy)
 - [Open Telemetry](https://opentelemetry.io/)
 
+In addition to distributed tracing, Azure also uses a set of common correlation headers:
+
+|Name                         |Applies to|Description|
+|-----------------------------|----------|-----------|
+|x-ms-client-request-id       |Both      |Optional. Caller-specified value identifying the request, in the form of a GUID with no decoration such as curly braces (e.g. `x-ms-client-request-id: 9C4D50EE-2D56-4CD3-8152-34347DC9F2B0`). If the caller provides this header the service **must** include this in their log entries to facilitate correlation of log entries for a single request. Because this header can be client-generated, it should not be assumed to be unique by the service implementation.
+|x-ms-request-id              |Response  |Required. Service generated correlation id identifying the request, in the form of a GUID with no decoration such as curly braces. In contrast to the the `x-ms-client-request-id`, the service **must** ensure that this value is globally unique. Services should log this value with their traces to facilitate correlation of log entries for a single request.
+
 ## Final thoughts
 These guidelines describe the upfront design considerations, technology building blocks, and common patterns that Azure teams encounter when building an API for their service. There is a great deal of information in them that can be difficult to follow. Fortunately, at Microsoft, there is a team committed to ensuring your success.