{"id":1603,"date":"2021-10-08T09:00:05","date_gmt":"2021-10-08T16:00:05","guid":{"rendered":"https:\/\/devblogs.microsoft.com\/azure-sdk\/?p=1603"},"modified":"2021-10-07T19:25:14","modified_gmt":"2021-10-08T02:25:14","slug":"introducing-experimental-opentelemetry-support-in-the-azure-sdk-for-net","status":"publish","type":"post","link":"https:\/\/devblogs.microsoft.com\/azure-sdk\/introducing-experimental-opentelemetry-support-in-the-azure-sdk-for-net\/","title":{"rendered":"Introducing experimental OpenTelemetry support in the Azure SDK for .NET"},"content":{"rendered":"<p>Cloud-hosted apps are often composed of many services that are integrated together in some fashion. For example, processing a single request might involve:<\/p>\n<ul>\n<li>Calling an Azure Storage service.<\/li>\n<li>Posting an event to Azure Event Hubs.<\/li>\n<li>Calling a custom authentication backend.<\/li>\n<\/ul>\n<p>With an increasing number of moving pieces comes an increasing number of distributed failure points. Distributed tracing helps collect and correlate diagnostics for complex, multi-service apps. It allows you to follow a customer&#8217;s request from the browser to all the components of the system.<\/p>\n<h2>How OpenTelemetry helps<\/h2>\n<p><a href=\"https:\/\/opentelemetry.io\/docs\/concepts\/what-is-opentelemetry\/\">OpenTelemetry<\/a> unifies instrumentation, collection, and export of distributed tracing data across languages, clouds, and libraries. Before OpenTelemetry, changing the hosting platform (running locally, self-hosted, Azure, AWS) or tracing solution (Zipkin, Jaeger, Azure Monitor) required switching the distributed tracing library as well.\nSwitching the tracing library involves changing your app&#8217;s code. Also, different tracing libraries vary in their supported integrations (instrumentations). For example, one library might support tracing Redis calls but not Azure Table. Another library might support Azure Table but not Redis, and so on.<\/p>\n<p>OpenTelemetry helps by defining common abstractions for instrumentation, collection, and exporting. When switching your tracing solution to OpenTelemetry, only the exporter plugin needs to change. Your app&#8217;s code and third-party library integrations are unaffected.<\/p>\n<h2>OpenTelemetry support in the Azure SDK for .NET<\/h2>\n<p>OpenTelemetry support means that calls made using Azure SDK libraries would appear in your distributed traces. Azure SDK libraries produce the following kinds of telemetry spans:<\/p>\n<ul>\n<li><strong>HTTP calls<\/strong>: Every HTTP call that originates from an Azure SDK library.<\/li>\n<li><strong>Client method calls<\/strong>: For example, <code>BlobClient.DownloadTo<\/code> or <code>SecretClient.StartDeleteSecret<\/code>.<\/li>\n<li><strong>Messaging events<\/strong>: Event Hubs and Service Bus message creation is traced and correlated with its sending, receiving, and processing.<\/li>\n<\/ul>\n<p>For more detailed distributed tracing conventions, see the <a href=\"https:\/\/github.com\/Azure\/azure-sdk\/blob\/main\/docs\/tracing\/distributed-tracing-conventions.yml\">specification<\/a>.<\/p>\n<p>At the time of writing, OpenTelemetry support in the Azure SDK for .NET is experimental. For information on when OpenTelemetry support will be officially released, see the <a href=\"https:\/\/aka.ms\/azsdk\/releases\">Azure SDK releases page<\/a>. While the OpenTelemetry SDK for .NET is stable, many tracing conventions that describe the shape of telemetry spans are still experimental. Because OpenTelemetry support is experimental, the shape of spans may change in the future. You can follow changes at the <a href=\"https:\/\/github.com\/Azure\/azure-sdk-for-net\/blob\/main\/sdk\/core\/Azure.Core\/CHANGELOG.md\">Azure.Core changelog<\/a>. These changes might impact:<\/p>\n<ul>\n<li>The kinds of operations that are tracked.<\/li>\n<li>Relationships between telemetry spans.<\/li>\n<li>Attributes attached to telemetry spans.<\/li>\n<\/ul>\n<h2>Get started<\/h2>\n<p>To start collecting telemetry, complete the following steps:<\/p>\n<ol>\n<li>\n<p>Enable OpenTelemetry support via one of the following ways:<\/p>\n<ul>\n<li>\n<p>Set the <code>AZURE_EXPERIMENTAL_ENABLE_ACTIVITY_SOURCE<\/code> environment variable to <code>true<\/code>.<\/p>\n<\/li>\n<li>\n<p>Set the <code>Azure.Experimental.EnableActivitySource<\/code> context switch to <code>true<\/code> in your app&#8217;s code:<\/p>\n<pre><code class=\"language-csharp\">AppContext.SetSwitch(\"Azure.Experimental.EnableActivitySource\", true);<\/code><\/pre>\n<\/li>\n<li>\n<p>Add the <code>RuntimeHostConfigurationOption<\/code> setting to your project file:<\/p>\n<pre><code class=\"language-xml\">&lt;ItemGroup&gt;\r\n    &lt;RuntimeHostConfigurationOption Include=\"Azure.Experimental.EnableActivitySource\" Value=\"true\" \/&gt;\r\n&lt;\/ItemGroup&gt; <\/code><\/pre>\n<\/li>\n<\/ul>\n<\/li>\n<li>\n<p>Install the <a href=\"https:\/\/www.nuget.org\/packages\/OpenTelemetry\">OpenTelemetry package<\/a> with the following .NET CLI command:<\/p>\n<pre><code class=\"language-dotnetcli\">dotnet package OpenTelemetry<\/code><\/pre>\n<\/li>\n<li>\n<p>Install one of the exporter packages. To use the <a href=\"https:\/\/techcommunity.microsoft.com\/t5\/azure-monitor\/opentelemetry-azure-monitor\/ba-p\/2737823\">preview<\/a> <a href=\"https:\/\/www.nuget.org\/packages\/Azure.Monitor.OpenTelemetry.Exporter\">Azure Monitor\/Application Insights<\/a> exporter, run the following .NET CLI command:<\/p>\n<pre><code class=\"language-dotnetcli\">dotnet add package Azure.Monitor.OpenTelemetry.Exporter --version 1.0.0-beta.2<\/code><\/pre>\n<\/li>\n<li>\n<p>Create an Application Insights resource to store the data. Follow the <a href=\"https:\/\/docs.microsoft.com\/azure\/azure-monitor\/app\/create-new-resource\">create new resource<\/a> tutorial and copy the connection string.<\/p>\n<\/li>\n<li>\n<p>Configure OpenTelemetry to collect traces and export them to Application Insights:<\/p>\n<pre><code class=\"language-csharp\">using var openTelemetry = Sdk.CreateTracerProviderBuilder()\r\n    .AddSource(\"Azure.*\") \/\/ Collect all traces from Azure SDKs\r\n    .AddAzureMonitorTraceExporter(options =&gt; options.ConnectionString = \r\n        \"&lt;Application Insights connection string&gt;\") \/\/ Export traces to Azure Monitor\r\n    .Build(); \/\/ Start listening<\/code><\/pre>\n<\/li>\n<li>\n<p>Add some code making an Azure SDK call. When put together, your code should look something like this:<\/p>\n<pre><code class=\"language-csharp\">AppContext.SetSwitch(\"Azure.Experimental.EnableActivitySource\", true);\r\n\r\nusing var openTelemetry = Sdk.CreateTracerProviderBuilder()\r\n    .AddSource(\"Azure.*\")\r\n    .AddAzureMonitorTraceExporter(options =&gt; options.ConnectionString = \r\n        \"&lt;Application Insights connection string&gt;\")\r\n    .Build();\r\n\r\nnew BlobClient(new Uri(\"https:\/\/aka.ms\/bloburl\")).DownloadTo(\"hello.jpg\");<\/code><\/pre>\n<\/li>\n<li>\n<p>Run your app. It takes up to 5 minutes for data to propagate and become accessible through the Azure portal.<\/p>\n<\/li>\n<li>\n<p>View your traces in the Azure portal by navigating to <strong>Transaction search<\/strong> on the left for your Application Insights resource. Select <strong>See all data in the last 24 hours<\/strong>.<\/p>\n<\/li>\n<\/ol>\n<p>The following screenshot shows a sample trace collected using OpenTelemetry and displayed in the Azure portal:<\/p>\n<p><img decoding=\"async\" src=\"https:\/\/devblogs.microsoft.com\/azure-sdk\/wp-content\/uploads\/sites\/58\/2021\/10\/2021-10-07-opentelemetry-experemental-trace.png\" alt=\"Azure portal screenshot showing Azure SDK trace collected using OpenTelemetry\" \/><\/p>\n<p>Only packages prefixed with <code>Azure.<\/code> and released <strong>after October 1, 2021<\/strong> have OpenTelemetry support. Earlier packages support only the <a href=\"https:\/\/docs.microsoft.com\/azure\/azure-monitor\/app\/app-insights-overview\">ApplicationInsights SDK<\/a>.<\/p>\n<p>We hope you&#8217;ll try the new tracing integration and are eager to hear your feedback.<\/p>\n","protected":false},"excerpt":{"rendered":"<p>In this article, we look at our current effort to integrate OpenTelemetry with the new Azure SDK client libraries for .NET.<\/p>\n","protected":false},"author":31981,"featured_media":1608,"comment_status":"open","ping_status":"closed","sticky":false,"template":"","format":"standard","meta":{"_acf_changed":false,"footnotes":""},"categories":[1],"tags":[701,804,833],"class_list":["post-1603","post","type-post","status-publish","format-standard","has-post-thumbnail","hentry","category-azure-sdk","tag-net","tag-azure-monitor","tag-opentelemetry"],"acf":[],"blog_post_summary":"<p>In this article, we look at our current effort to integrate OpenTelemetry with the new Azure SDK client libraries for .NET.<\/p>\n","_links":{"self":[{"href":"https:\/\/devblogs.microsoft.com\/azure-sdk\/wp-json\/wp\/v2\/posts\/1603","targetHints":{"allow":["GET"]}}],"collection":[{"href":"https:\/\/devblogs.microsoft.com\/azure-sdk\/wp-json\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/devblogs.microsoft.com\/azure-sdk\/wp-json\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/azure-sdk\/wp-json\/wp\/v2\/users\/31981"}],"replies":[{"embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/azure-sdk\/wp-json\/wp\/v2\/comments?post=1603"}],"version-history":[{"count":0,"href":"https:\/\/devblogs.microsoft.com\/azure-sdk\/wp-json\/wp\/v2\/posts\/1603\/revisions"}],"wp:featuredmedia":[{"embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/azure-sdk\/wp-json\/wp\/v2\/media\/1608"}],"wp:attachment":[{"href":"https:\/\/devblogs.microsoft.com\/azure-sdk\/wp-json\/wp\/v2\/media?parent=1603"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/azure-sdk\/wp-json\/wp\/v2\/categories?post=1603"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/azure-sdk\/wp-json\/wp\/v2\/tags?post=1603"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}