Skip to content

Commit 96b519f

Browse files
azure-sdkazure-sdk
committed
Update docs metadata
1 parent e4dea84 commit 96b519f

File tree

2 files changed

+180
-0
lines changed

2 files changed

+180
-0
lines changed

‎api/overview/azure/latest/monitor.opentelemetry.exporter-readme.md

Lines changed: 163 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,163 @@
1+
---
2+
title: Azure Monitor Exporter client library for .NET
3+
keywords: Azure, dotnet, SDK, API, Azure.Monitor.OpenTelemetry.Exporter, monitor
4+
author: SameergMS
5+
ms.author: sameerg
6+
ms.date: 09/20/2023
7+
ms.topic: reference
8+
ms.devlang: dotnet
9+
ms.service: monitor
10+
---
11+
# Azure Monitor Exporter client library for .NET - version 1.0.0
12+
13+
14+
15+
16+
The [OpenTelemetry .NET](https://github.com/open-telemetry/opentelemetry-dotnet) exporters which send [telemetry data](/azure/azure-monitor/app/data-model) to [Azure Monitor](/azure/azure-monitor/app/app-insights-overview) following the [OpenTelemetry Specification](https://github.com/open-telemetry/opentelemetry-specification).
17+
18+
## Getting started
19+
20+
### Prerequisites
21+
22+
- **Azure Subscription:** To use Azure services, including Azure Monitor Exporter for [OpenTelemetry .NET](https://github.com/open-telemetry/opentelemetry-dotnet), you'll need a subscription. If you do not have an existing Azure account, you may sign up for a [free trial](https://azure.microsoft.com/free/dotnet/) or use your [Visual Studio Subscription](https://visualstudio.microsoft.com/subscriptions/) benefits when you [create an account](https://azure.microsoft.com/account).
23+
- **Azure Application Insights Connection String:** To send telemetry data to the monitoring service you'll need connection string from Azure Application Insights. If you are not familiar with creating Azure resources, you may wish to follow the step-by-step guide for [Create an Application Insights resource](/azure/azure-monitor/app/create-new-resource) and [copy the connection string](/azure/azure-monitor/app/sdk-connection-string?tabs=net#find-your-connection-string).
24+
25+
### Install the package
26+
27+
#### Latest Version: [![Nuget](https://img.shields.io/nuget/vpre/Azure.Monitor.OpenTelemetry.Exporter.svg)](https://www.nuget.org/packages/Azure.Monitor.OpenTelemetry.Exporter/)
28+
29+
Install the Azure Monitor Exporter for OpenTelemetry .NET with [NuGet](https://www.nuget.org/):
30+
```dotnetcli
31+
dotnet add package Azure.Monitor.OpenTelemetry.Exporter
32+
```
33+
34+
#### Nightly builds
35+
36+
Nightly builds are available from this repo's [dev feed](https://github.com/Azure/azure-sdk-for-net/blob/Azure.Monitor.OpenTelemetry.Exporter_1.0.0/CONTRIBUTING.md#nuget-package-dev-feed).
37+
These are provided without support and are not intended for production workloads.
38+
39+
### Add the Exporter
40+
41+
The following examples demonstrate how to add the `AzureMonitorExporter` to your OpenTelemetry configuration.
42+
43+
- Traces
44+
```csharp
45+
Sdk.CreateTracerProviderBuilder()
46+
.AddAzureMonitorTraceExporter(o => o.ConnectionString = "InstrumentationKey=00000000-0000-0000-0000-000000000000")
47+
.Build();
48+
```
49+
50+
For a complete example see [TraceDemo.cs](https://github.com/Azure/azure-sdk-for-net/blob/Azure.Monitor.OpenTelemetry.Exporter_1.0.0/sdk/monitor/Azure.Monitor.OpenTelemetry.Exporter/tests/Azure.Monitor.OpenTelemetry.Exporter.Demo/Traces/TraceDemo.cs).
51+
52+
- Metrics
53+
```csharp
54+
Sdk.CreateMeterProviderBuilder()
55+
.AddAzureMonitorMetricExporter(o => o.ConnectionString = "InstrumentationKey=00000000-0000-0000-0000-000000000000")
56+
.Build();
57+
```
58+
59+
For a complete example see [MetricDemo.cs](https://github.com/Azure/azure-sdk-for-net/blob/Azure.Monitor.OpenTelemetry.Exporter_1.0.0/sdk/monitor/Azure.Monitor.OpenTelemetry.Exporter/tests/Azure.Monitor.OpenTelemetry.Exporter.Demo/Metrics/MetricDemo.cs).
60+
61+
- Logs
62+
```csharp
63+
LoggerFactory.Create(builder =>
64+
{
65+
builder.AddOpenTelemetry(options =>
66+
{
67+
options.AddAzureMonitorLogExporter(o => o.ConnectionString = "InstrumentationKey=00000000-0000-0000-0000-000000000000");
68+
});
69+
});
70+
```
71+
72+
For a complete example see [LogDemo.cs](https://github.com/Azure/azure-sdk-for-net/blob/Azure.Monitor.OpenTelemetry.Exporter_1.0.0/sdk/monitor/Azure.Monitor.OpenTelemetry.Exporter/tests/Azure.Monitor.OpenTelemetry.Exporter.Demo/Logs/LogDemo.cs).
73+
74+
### Authenticate the client
75+
76+
Azure Active Directory (AAD) authentication is an optional feature that can be used with the Azure Monitor Exporter.
77+
This is made easy with the [Azure Identity library](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Monitor.OpenTelemetry.Exporter_1.0.0/sdk/identity/Azure.Identity/README.md), which provides support for authenticating Azure SDK clients with their corresponding Azure services.
78+
79+
There are two options to enable AAD authentication. Note that if both have been set AzureMonitorExporterOptions will take precedence.
80+
81+
1. Set your `Credential` to the `AzureMonitorExporterOptions`.
82+
83+
```csharp
84+
var credential = new DefaultAzureCredential();
85+
86+
Sdk.CreateTracerProviderBuilder()
87+
.AddAzureMonitorTraceExporter(o =>
88+
{
89+
o.ConnectionString = "InstrumentationKey=00000000-0000-0000-0000-000000000000";
90+
o.Credential = credential;
91+
})
92+
.Build();
93+
```
94+
95+
2. Provide your `Credential` to the AddAzureMonitorExporter method.
96+
97+
```csharp
98+
var credential = new DefaultAzureCredential();
99+
100+
Sdk.CreateTracerProviderBuilder()
101+
.AddAzureMonitorTraceExporter(o => o.ConnectionString = "InstrumentationKey=00000000-0000-0000-0000-000000000000", credential)
102+
.Build();
103+
```
104+
105+
## Key concepts
106+
107+
Some key concepts for .NET include:
108+
109+
- [Overview of .NET distributed tracing](https://learn.microsoft.com/dotnet/core/diagnostics/distributed-tracing):
110+
Distributed tracing is a diagnostic technique that helps engineers localize failures and performance issues within applications, especially those that may be distributed across multiple machines or processes.
111+
112+
- [Overview of Logging in .NET](https://learn.microsoft.com/dotnet/core/extensions/logging):
113+
.NET supports a logging API that works with a variety of built-in and third-party logging providers.
114+
115+
Some key concepts for Azure Monitor include:
116+
117+
- [IP Addresses used by Azure Monitor](/azure/azure-monitor/app/ip-addresses#outgoing-ports):
118+
This exporter sends traces to the configured Azure Monitor Resource using HTTPS.
119+
You might need to know IP addresses if the app or infrastructure that you're monitoring is hosted behind a firewall.
120+
121+
Some key concepts for OpenTelemetry include:
122+
123+
- [OpenTelemetry](https://opentelemetry.io/):
124+
OpenTelemetry is a set of libraries used to collect and export telemetry data
125+
(metrics, logs, and traces) for analysis in order to understand your software's performance and behavior.
126+
127+
- [Instrumentation](https://github.com/open-telemetry/opentelemetry-specification/blob/master/specification/overview.md#instrumentation-libraries):
128+
The ability to call the OpenTelemetry API directly by any application is
129+
facilitated by instrumentation. A library that enables OpenTelemetry observability for another library is called an Instrumentation Library.
130+
131+
- [Tracing Signal](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/overview.md#tracing-signal):
132+
Trace refers to distributed tracing. It can be thought of as a directed acyclic graph (DAG) of Spans, where the edges between Spans are defined as parent/child relationship.
133+
134+
- [Sampling](https://github.com/open-telemetry/opentelemetry-specification/blob/master/specification/trace/sdk.md#sampling):
135+
Sampling is a mechanism to control the noise and overhead introduced by OpenTelemetry by reducing the number of samples of traces collected and sent to the backend.
136+
137+
- [Metric Signal](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/overview.md#metric-signal):
138+
OpenTelemetry allows to record raw measurements or metrics with predefined aggregation and a set of attributes (dimensions).
139+
140+
- [Log Signal](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/overview.md#log-signal):
141+
A recording of an event. Typically the record includes a timestamp indicating when the event happened as well as other data that describes what happened, where it happened, etc.
142+
143+
For more information on the OpenTelemetry project, please review the [OpenTelemetry Specifications](https://github.com/open-telemetry/opentelemetry-specification).
144+
145+
## Examples
146+
147+
Refer to [`Program.cs`](https://github.com/Azure/azure-sdk-for-net/blob/Azure.Monitor.OpenTelemetry.Exporter_1.0.0/sdk/monitor/Azure.Monitor.OpenTelemetry.Exporter/tests/Azure.Monitor.OpenTelemetry.Exporter.Demo/Program.cs) for a complete demo.
148+
149+
## Troubleshooting
150+
151+
The Azure Monitor exporter uses EventSource for its own internal logging. The exporter logs are available to any EventListener by opting into the source named "OpenTelemetry-AzureMonitor-Exporter".
152+
153+
OpenTelemetry also provides it's own [self-diagnostics feature](https://github.com/open-telemetry/opentelemetry-dotnet/blob/main/src/OpenTelemetry/README.md#troubleshooting) to collect internal logs.
154+
An example of this is available in our demo project [here](https://github.com/Azure/azure-sdk-for-net/blob/Azure.Monitor.OpenTelemetry.Exporter_1.0.0/sdk/monitor/Azure.Monitor.OpenTelemetry.Exporter/tests/Azure.Monitor.OpenTelemetry.Exporter.Demo/OTEL_DIAGNOSTICS.json).
155+
156+
## Next steps
157+
158+
For more information on Azure SDK, please refer to [this website](https://azure.github.io/azure-sdk/)
159+
160+
## Contributing
161+
162+
See [CONTRIBUTING.md](https://github.com/Azure/azure-sdk-for-net/blob/Azure.Monitor.OpenTelemetry.Exporter_1.0.0/CONTRIBUTING.md) for details on contribution process.
163+

‎metadata/latest/Azure.Monitor.OpenTelemetry.Exporter.json

Lines changed: 17 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,17 @@
1+
{
2+
"Name": "Azure.Monitor.OpenTelemetry.Exporter",
3+
"Version": "1.0.0",
4+
"DevVersion": null,
5+
"DirectoryPath": "sdk/monitor/Azure.Monitor.OpenTelemetry.Exporter",
6+
"ServiceDirectory": "monitor",
7+
"ReadMePath": "sdk/monitor/Azure.Monitor.OpenTelemetry.Exporter/README.md",
8+
"ChangeLogPath": "sdk/monitor/Azure.Monitor.OpenTelemetry.Exporter/CHANGELOG.md",
9+
"Group": null,
10+
"SdkType": "client",
11+
"IsNewSdk": true,
12+
"ArtifactName": "Azure.Monitor.OpenTelemetry.Exporter",
13+
"ReleaseStatus": "2023-09-20",
14+
"Namespaces": [
15+
"Azure.Monitor.OpenTelemetry.Exporter"
16+
]
17+
}

0 commit comments

Comments
 (0)