Merge pull request #265716 from cijothomas/cijothomas/otel-distro-fixes1

Minor fixes to OTel distro docs

Author: prmerger-automator[bot]

articles/azure-monitor/app/opentelemetry-add-modify.md

@@ -27,15 +27,15 @@ The distros automatically collect data by bundling OpenTelemetry instrumentation
 
 Requests
 - [ASP.NET
-  Core](https://github.com/open-telemetry/opentelemetry-dotnet/blob/1.0.0-rc9.14/src/OpenTelemetry.Instrumentation.AspNetCore/README.md) ¹
+  Core](https://github.com/open-telemetry/opentelemetry-dotnet/blob/1.0.0-rc9.14/src/OpenTelemetry.Instrumentation.AspNetCore/README.md) ¹²
 
 Dependencies
-- [HttpClient](https://github.com/open-telemetry/opentelemetry-dotnet/blob/1.0.0-rc9.14/src/OpenTelemetry.Instrumentation.Http/README.md) ¹
+- [HttpClient](https://github.com/open-telemetry/opentelemetry-dotnet/blob/1.0.0-rc9.14/src/OpenTelemetry.Instrumentation.Http/README.md) ¹²
 - [SqlClient](https://github.com/open-telemetry/opentelemetry-dotnet/blob/1.0.0-rc9.14/src/OpenTelemetry.Instrumentation.SqlClient/README.md) ¹
 
 Logging
 - `ILogger`
- 
+
 For more information about `ILogger`, see [Logging in C# and .NET](/dotnet/core/extensions/logging) and [code examples](https://github.com/open-telemetry/opentelemetry-dotnet/tree/main/docs/logs).
 
 #### [.NET](#tab/net)
@@ -188,7 +188,6 @@ Instrumentations can be configured using AzureMonitorOpenTelemetryOptions
 
 ```
 
-
 #### [Python](#tab/python)
 
 Requests

articles/azure-monitor/app/opentelemetry-configuration.md

@@ -13,7 +13,6 @@ ms.reviewer: mmcc
 
 This article covers configuration settings for the Azure Monitor OpenTelemetry distro.
 
-
 ## Connection string
 
 A connection string in Application Insights defines the target location for sending telemetry data, ensuring it reaches the appropriate resource for monitoring and analysis.
@@ -22,7 +21,8 @@ A connection string in Application Insights defines the target location for send
 
 Use one of the following three ways to configure the connection string:
 
-- Add `UseAzureMonitor()` to your application startup. Depending on your version of .NET, it is in either your `startup.cs` or `program.cs` class.
+- Add `UseAzureMonitor()` to your application startup. This is in your `program.cs` class.
+
     ```csharp
     // Create a new ASP.NET Core web application builder.    
     var builder = WebApplication.CreateBuilder(args);
@@ -39,11 +39,15 @@ Use one of the following three ways to configure the connection string:
     // Start the ASP.NET Core web application.    
     app.Run();
     ```
+
 - Set an environment variable:
+
    ```console
    APPLICATIONINSIGHTS_CONNECTION_STRING=<Your Connection String>
    ```
+
 - Add the following section to your `appsettings.json` config file:
+
   ```json
   {
     "AzureMonitor": {
@@ -63,6 +67,7 @@ Use one of the following three ways to configure the connection string:
 Use one of the following two ways to configure the connection string:
 
 - Add the Azure Monitor Exporter to each OpenTelemetry signal in application startup.
+
     ```csharp
     // Create a new OpenTelemetry tracer provider.
     // It is important to keep the TracerProvider instance active throughout the process lifetime.
@@ -93,6 +98,7 @@ Use one of the following two ways to configure the connection string:
         });
     });
     ```
+
 - Set an environment variable:
    ```console
    APPLICATIONINSIGHTS_CONNECTION_STRING=<Your Connection String>
@@ -112,7 +118,7 @@ To set the connection string, see [Connection string](java-standalone-config.md#
 Use one of the following two ways to configure the connection string:
 
 - Set an environment variable:
-        
+
    ```console
    APPLICATIONINSIGHTS_CONNECTION_STRING=<Your Connection String>
    ```
@@ -139,7 +145,7 @@ Use one of the following two ways to configure the connection string:
 Use one of the following two ways to configure the connection string:
 
 - Set an environment variable:
-        
+
    ```console
    APPLICATIONINSIGHTS_CONNECTION_STRING=<Your Connection String>
    ```
@@ -279,12 +285,14 @@ useAzureMonitor(options);
 Set the Cloud Role Name and the Cloud Role Instance via [Resource](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/resource/sdk.md#resource-sdk) attributes. Cloud Role Name uses `service.namespace` and `service.name` attributes, although it falls back to `service.name` if `service.namespace` isn't set. Cloud Role Instance uses the `service.instance.id` attribute value. For information on standard attributes for resources, see [OpenTelemetry Semantic Conventions](https://github.com/open-telemetry/semantic-conventions/blob/main/docs/README.md).
 
 Set Resource attributes using the `OTEL_RESOURCE_ATTRIBUTES` and/or `OTEL_SERVICE_NAME` environment variables. `OTEL_RESOURCE_ATTRIBUTES` takes series of comma-separated key-value pairs. For example, to set the Cloud Role Name to `my-namespace.my-helloworld-service` and set Cloud Role Instance to `my-instance`, you can set `OTEL_RESOURCE_ATTRIBUTES` and `OTEL_SERVICE_NAME` as such:
+
 ```
 export OTEL_RESOURCE_ATTRIBUTES="service.namespace=my-namespace,service.instance.id=my-instance"
 export OTEL_SERVICE_NAME="my-helloworld-service"
 ```
 
 If you don't set the `service.namespace` Resource attribute, you can alternatively set the Cloud Role Name with only the OTEL_SERVICE_NAME environment variable or the `service.name` Resource attribute. For example, to set the Cloud Role Name to `my-helloworld-service` and set Cloud Role Instance to `my-instance`, you can set `OTEL_RESOURCE_ATTRIBUTES` and `OTEL_SERVICE_NAME` as such:
+
 ```
 export OTEL_RESOURCE_ATTRIBUTES="service.instance.id=my-instance"
 export OTEL_SERVICE_NAME="my-helloworld-service"
@@ -296,7 +304,7 @@ export OTEL_SERVICE_NAME="my-helloworld-service"
 
 You might want to enable sampling to reduce your data ingestion volume, which reduces your cost. Azure Monitor provides a custom *fixed-rate* sampler that populates events with a sampling ratio, which Application Insights converts to `ItemCount`. The *fixed-rate* sampler ensures accurate experiences and event counts. The sampler is designed to preserve your traces across services, and it's interoperable with older Application Insights SDKs. For more information, see [Learn More about sampling](sampling.md#brief-summary).
 
-> [!NOTE] 
+> [!NOTE]
 > Metrics and Logs are unaffected by sampling.
 
 #### [ASP.NET Core](#tab/aspnetcore)
@@ -393,11 +401,13 @@ We support the credential classes provided by [Azure Identity](https://github.co
   - Provide the tenant ID, client ID, and client secret to the constructor.
 
 1. Install the latest [Azure.Identity](https://www.nuget.org/packages/Azure.Identity) package:
+
     ```dotnetcli
     dotnet add package Azure.Identity
     ```
-    
+
 1. Provide the desired credential class:
+
     ```csharp
     // Create a new ASP.NET Core web application builder.    
     var builder = WebApplication.CreateBuilder(args);
@@ -431,11 +441,13 @@ We support the credential classes provided by [Azure Identity](https://github.co
   - Provide the tenant ID, client ID, and client secret to the constructor.
 
 1. Install the latest [Azure.Identity](https://www.nuget.org/packages/Azure.Identity) package:
+
     ```dotnetcli
     dotnet add package Azure.Identity
     ```
 
-1. Provide the desired credential class:    
+1. Provide the desired credential class:
+
     ```csharp
     // Create a DefaultAzureCredential.
     var credential = new DefaultAzureCredential();
@@ -469,7 +481,7 @@ We support the credential classes provided by [Azure Identity](https://github.co
         });
     });
     ```
-    
+
 #### [Java](#tab/java)
 
 For more information about Java, see the [Java supplemental documentation](java-standalone-config.md).
@@ -498,7 +510,7 @@ useAzureMonitor(options);
 ```
 
 #### [Python](#tab/python)
-    
+
 ```python
 # Import the `ManagedIdentityCredential` class from the `azure.identity` package.
 from azure.identity import ManagedIdentityCredential
@@ -514,7 +526,6 @@ configure_azure_monitor(
 
 ---
 
-
 ## Offline Storage and Automatic Retries
 
 To improve reliability and resiliency, Azure Monitor OpenTelemetry-based offerings write to offline/local storage by default when an application loses its connection with Application Insights. It saves the application telemetry to disk and periodically tries to send it again for up to 48 hours. In high-load applications, telemetry is occasionally dropped for two reasons. First, when the allowable time is exceeded, and second, when the maximum file size is exceeded or the SDK doesn't have an opportunity to clear out the file. If we need to choose, the product saves more recent events over old ones. [Learn More](/previous-versions/azure/azure-monitor/app/data-retention-privacy#does-the-sdk-create-temporary-local-storage)
@@ -737,7 +748,7 @@ You might want to enable the OpenTelemetry Protocol (OTLP) Exporter alongside th
     ```
 
 1. Add the following code snippet. This example assumes you have an OpenTelemetry Collector with an OTLP receiver running. For details, see the [example on GitHub](https://github.com/open-telemetry/opentelemetry-dotnet/blob/main/examples/Console/TestOtlpExporter.cs).
-    
+
     ```csharp
     // Create a new OpenTelemetry tracer provider and add the Azure Monitor trace exporter and the OTLP trace exporter.
     // It is important to keep the TracerProvider instance active throughout the process lifetime.
@@ -795,7 +806,7 @@ For more information about Java, see the [Java supplemental documentation](java-
 1. Install the [opentelemetry-exporter-otlp](https://pypi.org/project/opentelemetry-exporter-otlp/) package.
 
 1. Add the following code snippet. This example assumes you have an OpenTelemetry Collector with an OTLP receiver running. For details, see this [README](https://github.com/Azure/azure-sdk-for-python/tree/main/sdk/monitor/azure-monitor-opentelemetry-exporter/samples/traces#collector).
-    
+
     ```python
     # Import the `configure_azure_monitor()`, `trace`, `OTLPSpanExporter`, and `BatchSpanProcessor` classes from the appropriate packages.    
     from azure.monitor.opentelemetry import configure_azure_monitor
@@ -832,6 +843,7 @@ For more information about Java, see the [Java supplemental documentation](java-
 ## OpenTelemetry configurations
 
 The following OpenTelemetry configurations can be accessed through environment variables while using the Azure Monitor OpenTelemetry Distros.
+
 ### [ASP.NET Core](#tab/aspnetcore)
 
 | Environment variable       | Description                                        |
@@ -841,7 +853,6 @@ The following OpenTelemetry configurations can be accessed through environment v
 | `OTEL_RESOURCE_ATTRIBUTES` | Key-value pairs to be used as resource attributes. For more information about resource attributes, see the [Resource SDK specification](https://github.com/open-telemetry/opentelemetry-specification/blob/v1.5.0/specification/resource/sdk.md#specifying-resource-information-via-an-environment-variable). |
 | `OTEL_SERVICE_NAME`        | Sets the value of the `service.name` resource attribute. If `service.name` is also provided in `OTEL_RESOURCE_ATTRIBUTES`, then `OTEL_SERVICE_NAME` takes precedence. |
 
-
 ### [.NET](#tab/net)
 
 | Environment variable       | Description                                        |

articles/azure-monitor/app/opentelemetry-enable.md

@@ -33,7 +33,7 @@ Follow the steps in this section to instrument your application with OpenTelemet
 
 ### [ASP.NET Core](#tab/aspnetcore)
 
-- [ASP.NET Core Application](/aspnet/core/introduction-to-aspnet-core) using an officially supported version of [.NET Core](https://dotnet.microsoft.com/download/dotnet)
+- [ASP.NET Core Application](/aspnet/core/introduction-to-aspnet-core) using an officially supported version of [.NET](https://dotnet.microsoft.com/download/dotnet)
 
 ### [.NET](#tab/net)
 
@@ -128,13 +128,14 @@ pip install azure-monitor-opentelemetry
 ---
 
 ### Enable Azure Monitor Application Insights
+
 To enable Azure Monitor Application Insights, you make a minor modification to your application and set your "Connection String." The Connection String tells your application where to send the telemetry the Distro collects, and it's unique to you.
 
 #### Modify your Application
 
 ##### [ASP.NET Core](#tab/aspnetcore)
 
-Add `UseAzureMonitor()` to your application startup. Depending on your version of .NET, it is in either your `startup.cs` or `program.cs` class.
+Add `UseAzureMonitor()` to your application startup. This is in your `program.cs` class.
 
 ```csharp
 // Import the Azure.Monitor.OpenTelemetry.AspNetCore namespace.
@@ -143,7 +144,7 @@ using Azure.Monitor.OpenTelemetry.AspNetCore;
 // Create a new WebApplicationBuilder instance.
 var builder = WebApplication.CreateBuilder(args);
 
-// Add the OpenTelemetry NuGet package to the application's services and configure OpenTelemetry to use Azure Monitor.
+// Add OpenTelemetry and configure it to use Azure Monitor.
 builder.Services.AddOpenTelemetry().UseAzureMonitor();
 
 // Build the application.
@@ -156,19 +157,23 @@ app.Run();
 ##### [.NET](#tab/net)
 
 Add the Azure Monitor Exporter to each OpenTelemetry signal in application startup. Depending on your version of .NET, it is in either your `startup.cs` or `program.cs` class.
+
 ```csharp
 // Create a new tracer provider builder and add an Azure Monitor trace exporter to the tracer provider builder.
 // It is important to keep the TracerProvider instance active throughout the process lifetime.
+// See https://github.com/open-telemetry/opentelemetry-dotnet/tree/main/docs/trace#tracerprovider-management
 var tracerProvider = Sdk.CreateTracerProviderBuilder()
     .AddAzureMonitorTraceExporter();
 
 // Add an Azure Monitor metric exporter to the metrics provider builder.
 // It is important to keep the MetricsProvider instance active throughout the process lifetime.
+// See https://github.com/open-telemetry/opentelemetry-dotnet/tree/main/docs/metrics#meterprovider-management
 var metricsProvider = Sdk.CreateMeterProviderBuilder()
     .AddAzureMonitorMetricExporter();
 
 // Create a new logger factory.
 // It is important to keep the LoggerFactory instance active throughout the process lifetime.
+// See https://github.com/open-telemetry/opentelemetry-dotnet/tree/main/docs/logs#logger-management
 var loggerFactory = LoggerFactory.Create(builder =>
 {
     builder.AddOpenTelemetry(options =>
@@ -237,6 +242,7 @@ input()
 ---
 
 #### Copy the Connection String from your Application Insights Resource
+
 > [!TIP]
 > If you don't already have one, now is a great time to [Create an Application Insights Resource](create-workspace-resource.md#create-a-workspace-based-resource). Here's when we recommend you [create a new Application Insights Resource versus use an existing one](create-workspace-resource.md#when-to-use-a-single-application-insights-resource).
 
@@ -263,20 +269,22 @@ To paste your Connection String, select from the following options:
   B. Set via Configuration File - Java Only (Recommended)
 
   Create a configuration file named `applicationinsights.json`, and place it in the same directory as `applicationinsights-agent-3.4.19.jar` with the following content:
-    
+
    ```json
    {
      "connectionString": "<Your Connection String>"
    }
    ```
+
   Replace `<Your Connection String>` in the preceding JSON with *your* unique connection string.
 
   C. Set via Code - ASP.NET Core, Node.js, and Python Only (Not recommended)
 
   See [Connection String Configuration](opentelemetry-configuration.md#connection-string) for an example of setting Connection String via code.
 
   > [!NOTE]
-  > If you set the connection string in more than one place, we adhere to the following precendence:
+  > If you set the connection string in more than one place, we adhere to the following precedence:
+  >
   > 1. Code
   > 2. Environment Variable
   > 3. Configuration File

articles/azure-monitor/includes/azure-monitor-app-insights-opentelemetry-faqs.md

@@ -17,24 +17,25 @@ It's a new open-source standard for observability. Learn more at [OpenTelemetry]
 ### Why is Microsoft Azure Monitor investing in OpenTelemetry?
 
 Microsoft is among the largest contributors to OpenTelemetry.
-          
+
 The key value propositions of OpenTelemetry are that it's vendor-neutral and provides consistent APIs/SDKs across languages.
-          
+
 Over time, we believe OpenTelemetry will enable Azure Monitor customers to observe applications written in languages beyond our [supported languages](../app/app-insights-overview.md#supported-languages). It also expands the types of data you can collect through a rich set of [instrumentation libraries](https://opentelemetry.io/docs/concepts/components/#instrumentation-libraries). Furthermore, OpenTelemetry SDKs tend to be more performant at scale than their predecessors, the Application Insights SDKs.
 
 Finally, OpenTelemetry aligns with Microsoft's strategy to [embrace open source](https://opensource.microsoft.com/).
 
 ### What's the status of OpenTelemetry?
 
-See the [OpenTelemetry Spec Compliance Matrix](https://github.com/open-telemetry/opentelemetry-specification/blob/main/spec-compliance-matrix.md).
+See [OpenTelemetry Status](https://opentelemetry.io/status/).
 
 ### What is the "Azure Monitor OpenTelemetry Distro"?
 
-You can think of it as a thin wrapper that bundles together all the OpenTelemetry components for a first class experience on Azure.
+You can think of it as a thin wrapper that bundles together all the OpenTelemetry components for a first class experience on Azure. This is also called [Distribution](https://opentelemetry.io/docs/concepts/distributions/) in OpenTelemetry.
 
 ### Why should I use the "Azure Monitor OpenTelemetry Distro"?
 
 There are several advantages to using the Azure Monitor OpenTelemetry Distro over native OpenTelemetry from the community:
+
 - Reduces enablement effort
 - Supported by Microsoft
 - Brings in Azure Specific features such as:
@@ -45,8 +46,9 @@ There are several advantages to using the Azure Monitor OpenTelemetry Distro ove
    - [Application Insights Standard Metrics](../app/standard-metrics.md)
    - Detect resource metadata to autopopulate [Cloud Role Name](../app/app-map.md#understand-the-cloud-role-name-within-the-context-of-an-application-map) on Azure
    - [Live Metrics](../app/live-stream.md) (future)
-          
+
 In the spirit of OpenTelemetry, we designed the distro to be open and extensible. For example, you can add:
+
 - An OTLP exporter and send to a second destination simultaneously
 - Other instrumentation libraries not included in the distro
 
@@ -62,9 +64,9 @@ Adopting OpenTelemetry now prevents having to migrate at a later date.
 
 ### When should I use the Azure Monitor OpenTelemetry exporter?
 
-For ASP..NET Core, Java, Node.js, and Python, we recommend using the OpenTelemetry distro. It's one line of code to get started.
+For ASP.NET Core, Java, Node.js, and Python, we recommend using the OpenTelemetry distro. It's one line of code to get started.
 
-For all other .NET scenarios, we recommend using our exporter: `Azure.Monitor.OpenTelemetry.Exporter`.
+For all other .NET scenarios (like classic ASP.NET, Console apps etc.), we recommend using our exporter: `Azure.Monitor.OpenTelemetry.Exporter`.
 
 ### What's the current release state of features within the Azure Monitor OpenTelemetry Distro?