Add x-ms-correlation-request-id, x-ms-client-request-id header guidance

[pakrym]

Add explicit guidance in the design guidelines on how a caller of the SDK should be able to specify a client-generated request-id and how to return server-generated correlation ids.

There is a bit of guidance around request-id header but it would be nice to solidify exactly what scenarios around these headers we want to support in client SDKs.

cc @johanste

[johanste]

Some additional information. Semantically, we have (in theory and at least) three different concepts:

1. client generated correlation ids. Used by the client application to group multiple requests together. A limited variation of traces/spans.
2. client generated request ids. Used to detect/avoid processing the same request more than once on the server. Most often used to allow non-idempotent methods to be safely retried by clients.
3. server generated correlation ids. Generated by the service and returned in responses.

Unfortunately, exactly the same header is used for 1 and 2 across the set of services that Microsoft exposes (Azure + others). And the most common header name is x-ms-request-id. And for Azure services, it usually represents the client generated correlation id. I have not seen Azure services intentionally use 2 and not cause problems/confusion.

[adrianhall]

Should probably be discussed in arch board, with an eye to updating the Azure Core guidance for request IDs.

[mikekistler]

We have updated the Azure Guidelines to recommend using the OASIS Repeatable Requests headers to achieve idempotency. So x-ms-request-id should be treated as a client-generated correlation id (#1 above).

[cataggar]

I think this can be closed as the guidance has been provided at:
https://github.com/Azure/azure-resource-manager-rpc/blob/master/v1.0/common-api-details.md#client-request-headers

[abatishchev]

Add explicit guidance in the design guidelines on how a caller of the SDK should be able to specify

It's still unclear to me how can I do this, namely to specify x-ms-correlation-request-id.