Skip to the content.

Telemetry Handler

Objectives

Provide a mandatory middleware component that attaches metadata to a Graph request in order help the SDK team improve the developer experience.

Requirements

Multiple key/value pairs included in the comment should be delimited by a semi-colon.

Ideal Metadata Capture

SdkVersion: graph-dotnet-beta/0.6.0-preview, graph-dotnet-core/1.16.0 (featureUsage=0f; hostOS=Microsoft Windows 10.0.18362; runtimeEnvironment=.NETFramework/4.7.2)
client-request-id: fdae6861-5916-486d-93d9-9129160b2d79

Remarks

Ideally we would use the User-Agent header to identify the libraries that were involved in making the request. Unfortunately, this does not work for Javascript because despite allowing User-Agent to be changed in fetch() there is a bug in Chromium that remains unfixed for more than 3 years.

The SdkVersion borrows much of the syntax from user-agent but instead uses a comma delimited list.

ABNF Syntax for SdkVersion:

SdkVersion = 1#( product [ RWS comment ] )
product         = token ["/" product-version]

where product, product-version, comment and token are defined in RFC 7230 and RFC 7231.

Currently, many SDKs embed the version number into the product using a hypen as a separator. Over time we should migrate these to use the / to make parsing the version easier. / should not be used for any other purpose in the SdkVersion header.

The order of SdkVersion values is significant. Core library SdkVersion header values MUST be specified as the last value in the SdkVersion header. Service library header values MUST precede the Core library value in the SdkVersion header. Microsoft applications header values MUST precede the Service library header value. Another way to look at this is to list products/components in dependency order where the left most token represents the highest level in the dependency chain.

Note: The SdkVersion header is intended for Microsoft telemetry purposes. It is used to capture information about Microsoft SDKs and products that use the Microsoft Graph APIs. Non-Microsoft applications that use this header, or alter the value of this header, will gain no benefit from using this header. Use of this header by non-Microsoft applications reduces the telemetry value of this header and reduces the data quality associated with header which reduces the insights that we can gain from this header. In turn, this means fewer data-driven improvements to our SDKs. Users of the SDK or the SDK repository should not alter the value of the SdkVersion header.

Performance

The SdkVersion header is not used for any performance purposes by Microsoft Graph.

Security

The SdkVersion header MUST not be used for any security related features unless the security feature use is captured by the featureUsage value.

Privacy

The SdkVersion header MUST not contain information that identifies users or organizations.