Support to customize the client request id header when creating pipelines (Azure#26424)

### Packages impacted by this PR
@azure/core-rest-pipeline

### Issues associated with this PR

Azure/autorest.typescript#1906 (comment)

### Describe the problem that is addressed by this PR

Batch service has the requirement to custom their request id header to
`client-request-id` ([tsp
here](https://github.com/Azure/azure-rest-api-specs/blob/b37ad7f957f0c6f9dd149546e46399308f83b366/specification/batch/Batch/routes.tsp#L2719-L2727)).
Currently the header name is fixed as default value
`x-ms-client-request-id` in setClientRequestIdPolicy.

So I think we could open an option in PipelineOptions to allow
customizing this header.

### What are the possible designs available to address the problem? If
there are more than one possible design, why was the one in this PR
chosen?

Another option to support this is to add a customized policy from SDK
side, to achieve that we could:
- remove the default setClientRequestIdPolicy
- re-add a new setClientRequestIdPolicy policy and set the header with
customized name

Compared to the latter one I think the current implementation would be
more generic and elegant and can easily apply to more cases in future.
But I'm also open for better options.

### References

- Azure/azure-sdk-for-python#30771

---------

Co-authored-by: Jeff Fisher <[email protected]>

Author: MaryGao

sdk/core/core-rest-pipeline/CHANGELOG.md

@@ -4,6 +4,8 @@
 
 ### Features Added
 
+- Add CommonTelemetryOptions in PipelineOptions to allow customizing the client request id header name [PR #26424](https://github.com/Azure/azure-sdk-for-js/pull/26424)
+
 ### Breaking Changes
 
 ### Bugs Fixed

sdk/core/core-rest-pipeline/review/core-rest-pipeline.api.md

@@ -208,6 +208,7 @@ export interface PipelineOptions {
     proxyOptions?: ProxySettings;
     redirectOptions?: RedirectPolicyOptions;
     retryOptions?: PipelineRetryOptions;
+    telemetryOptions?: TelemetryOptions;
     tlsOptions?: TlsSettings;
     userAgentOptions?: UserAgentPolicyOptions;
 }
@@ -400,6 +401,11 @@ export interface SystemErrorRetryPolicyOptions {
     retryDelayInMs?: number;
 }
 
+// @public
+export interface TelemetryOptions {
+    clientRequestIdHeaderName?: string;
+}
+
 // @public
 export function throttlingRetryPolicy(options?: ThrottlingRetryPolicyOptions): PipelinePolicy;
 

sdk/core/core-rest-pipeline/src/createPipelineFromOptions.ts

@@ -44,6 +44,21 @@ export interface PipelineOptions {
    * Options for adding user agent details to outgoing requests.
    */
   userAgentOptions?: UserAgentPolicyOptions;
+
+  /**
+   * Options for setting common telemetry and tracing info to outgoing requests.
+   */
+  telemetryOptions?: TelemetryOptions;
+}
+
+/**
+ * Defines options that are used to configure common telemetry and tracing info
+ */
+export interface TelemetryOptions {
+  /**
+   * The name of the header to pass the request ID to.
+   */
+  clientRequestIdHeaderName?: string;
 }
 
 /**
@@ -74,7 +89,7 @@ export function createPipelineFromOptions(options: InternalPipelineOptions): Pip
 
   pipeline.addPolicy(formDataPolicy());
   pipeline.addPolicy(userAgentPolicy(options.userAgentOptions));
-  pipeline.addPolicy(setClientRequestIdPolicy());
+  pipeline.addPolicy(setClientRequestIdPolicy(options.telemetryOptions?.clientRequestIdHeaderName));
   pipeline.addPolicy(defaultRetryPolicy(options.retryOptions), { phase: "Retry" });
   pipeline.addPolicy(tracingPolicy(options.userAgentOptions), { afterPhase: "Retry" });
   if (isNode) {

sdk/core/core-rest-pipeline/src/index.ts

@@ -30,6 +30,7 @@ export {
 } from "./pipeline";
 export {
   createPipelineFromOptions,
+  TelemetryOptions,
   InternalPipelineOptions,
   PipelineOptions,
 } from "./createPipelineFromOptions";

sdk/core/core-rest-pipeline/test/setClientRequestIdPolicy.spec.ts

@@ -0,0 +1,85 @@
+// Copyright (c) Microsoft Corporation.
+// Licensed under the MIT license.
+
+import { assert } from "chai";
+import * as sinon from "sinon";
+import {
+  HttpClient,
+  PipelineResponse,
+  SendRequest,
+  createHttpHeaders,
+  createPipelineFromOptions,
+  createPipelineRequest,
+  setClientRequestIdPolicy,
+} from "../src";
+
+describe("setClientRequestIdPolicy", function () {
+  afterEach(function () {
+    sinon.restore();
+  });
+
+  it("should set the header name with `x-ms-client-request-id` if no header name is provided", async () => {
+    const request = createPipelineRequest({
+      url: "https://bing.com",
+    });
+    const policy = setClientRequestIdPolicy();
+    const successResponse: PipelineResponse = {
+      headers: createHttpHeaders(),
+      request,
+      status: 200,
+    };
+    const next = sinon.stub<Parameters<SendRequest>, ReturnType<SendRequest>>();
+    next.onFirstCall().resolves(successResponse);
+    assert.isFalse(request.headers.has("x-ms-client-request-id"));
+    await policy.sendRequest(request, next);
+    assert.isTrue(request.headers.has("x-ms-client-request-id"));
+  });
+
+  it("should set the header name with `x-ms-client-request-id` if commonTelemetryOptions is empty", async () => {
+    const pipeline = createPipelineFromOptions({
+      telemetryOptions: {},
+    });
+    const pipelineRequest = createPipelineRequest({
+      url: "https://bing.com",
+    });
+    const httpClient: HttpClient = {
+      sendRequest: async (request) => {
+        assert.isTrue(request.headers.has("x-ms-client-request-id"));
+        assert.equal(request.headers.get("x-ms-client-request-id"), request.requestId);
+        return {
+          request,
+          headers: createHttpHeaders(),
+          status: 200,
+        };
+      },
+    };
+    assert.isFalse(pipelineRequest.headers.has("x-ms-client-request-id"));
+    await pipeline.sendRequest(httpClient, pipelineRequest);
+  });
+
+  it("should set the header with custom header name if it is provided", async () => {
+    const customHeaderName = "custom-client-request-id";
+    const pipeline = createPipelineFromOptions({
+      telemetryOptions: {
+        clientRequestIdHeaderName: customHeaderName,
+      },
+    });
+    const pipelineRequest = createPipelineRequest({
+      url: "https://bing.com",
+    });
+    const httpClient: HttpClient = {
+      sendRequest: async (request) => {
+        assert.isTrue(request.headers.has(customHeaderName));
+        assert.equal(request.headers.get(customHeaderName), request.requestId);
+        return {
+          request,
+          headers: createHttpHeaders(),
+          status: 200,
+        };
+      },
+    };
+    assert.isFalse(pipelineRequest.headers.has("x-ms-client-request-id"));
+    assert.isFalse(pipelineRequest.headers.has(customHeaderName));
+    await pipeline.sendRequest(httpClient, pipelineRequest);
+  });
+});