Skip to content

Commit c94f494

Browse files
ronniegeraghtymicrozchang
authored andcommitted
Add telemetry data collection and configuration instructions to README (#6623)
1 parent 10eb756 commit c94f494

File tree

1 file changed

+52
-0
lines changed

1 file changed

+52
-0
lines changed

README.md

Lines changed: 52 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -393,6 +393,58 @@ Many people all over the world have helped make this project better. You'll wan
393393

394394
Security issues and bugs should be reported privately, via email, to the Microsoft Security Response Center (MSRC) <secure@microsoft.com>. You should receive a response within 24 hours. If for some reason you do not, please follow up via email to ensure we received your original message. Further information, including the MSRC PGP key, can be found in the [Security TechCenter](https://www.microsoft.com/msrc/faqs-report-an-issue).
395395

396+
### Data Collection
397+
398+
The software may collect information about you and your use of the software and send it to Microsoft. Microsoft may use this information to provide services and improve our products and services. You may turn off the telemetry as described below. You can learn more about data collection and use in the help documentation and Microsoft's [privacy statement](https://go.microsoft.com/fwlink/?LinkID=824704). For more information on the data collected by the Azure SDK, please visit the [Telemetry Guidelines](https://azure.github.io/azure-sdk/general_azurecore.html#telemetry-policy) page.
399+
400+
### Telemetry Configuration
401+
402+
Telemetry collection is on by default.
403+
404+
To opt out, you can disable telemetry at client construction. Creating a custom HTTP policy in your application gives you access to the headers sent with each request, allowing you to remove the `User-Agent` header containing client telemetry. To use the policy, you will add it to the options for your specific client as part of client creation. This will disable Azure SDK telemetry for all methods in the client. You will need to register the policy with each client created.
405+
406+
An example policy implementation looks like:
407+
408+
```cpp
409+
class RemoveUserAgentPolicy : public HttpPolicy {
410+
private:
411+
std::unique_ptr<RawResponse> Send(
412+
Request& request,
413+
NextHttpPolicy nextPolicy,
414+
Context const& context) const override
415+
{
416+
// Set your own User-Agent header or set an empty one to suppress telemetry
417+
request.SetHeader("User-Agent", "");
418+
419+
return nextPolicy.Send(request, context);
420+
}
421+
422+
std::unique_ptr<HttpPolicy> Clone() const override { return std::make_unique<RemoveUserAgentPolicy>(*this); }
423+
};
424+
```
425+
426+
To use it with a client, you would register it to run for every operation as part of your client options:
427+
428+
```cpp
429+
Uri serviceEndpoint = "<https://example.storage.windows.net>";
430+
std::shared_ptr<Core::Credentials::TokenCredential> credential =
431+
std::make_shared<Identity::DefaultAzureCredential>();
432+
433+
BlobClientOptions clientOptions;
434+
clientOptions.PerOperationPolicies.emplace_back(std::make_unique<RemoveUserAgentPolicy>());
435+
436+
BlobServiceClient client(serviceEndpoint, credential, clientOptions);
437+
```
438+
439+
You can also customize the telemetry information by setting an application identifier, which will be prepended to the User-Agent header:
440+
441+
```cpp
442+
// Add application ID to client options for telemetry
443+
BlobClientOptions clientOptions;
444+
clientOptions.Telemetry.ApplicationId = "MyApplication/1.0.0";
445+
auto blobServiceClient = BlobServiceClient::CreateFromConnectionString(connectionString, clientOptions);
446+
```
447+
396448
### License
397449

398450
Azure SDK for C++ is licensed under the [MIT](https://github.com/Azure/azure-sdk-for-cpp/blob/main/LICENSE.txt) license.

0 commit comments

Comments
 (0)