Skip to content

Commit 0a8dd2c

Browse files
colleenmcginniscolleenmcginnis
committed
merge intro and README content, link to docs from README, adjust for github audience
1 parent 3a4dcda commit 0a8dd2c

File tree

5 files changed

+150
-145
lines changed

5 files changed

+150
-145
lines changed

‎README.md

Lines changed: 86 additions & 73 deletions
Original file line numberDiff line numberDiff line change
@@ -2,83 +2,96 @@
22

33
# Elastic Distribution for OpenTelemetry .NET
44

5-
The Elastic Distribution for OpenTelemetry .NET provides a zero code change extension
6-
to [OpenTelemetry SDK for .NET](https://opentelemetry.io/docs/languages/net). These extensions ensure
7-
a smooth and rich out of the box experience with [Elastic Observability](https://www.elastic.co/observability)
8-
through strictly OpenTelemetry native means.
9-
10-
This ensures there are no new concepts to learn with the full OpenTelemetry ecosystem remains at ones
11-
fingertips. Read more about the concept of [OpenTelemetry Distributions](https://opentelemetry.io/docs/concepts/distributions).
12-
13-
The Elastic Distribution for OpenTelemetry .NET includes some Elastic-specific processors to ensure the best
14-
compatibility when exporting OpenTelemetry signal data [Elastic Observability](https://www.elastic.co/observability).
15-
The distribution also preconfigures the collection of tracing, metrics and logs signals, applying
16-
some opinionated defaults, such as which sources are collected by default. The distribution also
17-
ensures that the OTLP exporter is enabled by default.
18-
19-
> **_IMPORTANT:_** The Elastic Distribution for OpenTelemetry .NET is currently in early alpha release status.
20-
> It is not yet feature complete and may contain bugs. We are actively working on improving the distribution and
21-
adding new features.
5+
> [!WARNING]
6+
> The Elastic Distribution for OpenTelemetry .NET is not yet recommended for production use. Functionality may be changed or removed in future releases. Alpha releases are not subject to the support SLA of official GA features.
227
>
23-
> If you would like to experience the alpha and help us improve the distribution by providing
24-
early feedback, you can follow the steps below to get started.
8+
> We welcome your feedback! You can reach us by [opening a GitHub issue](https://github.com/elastic/elastic-otel-dotnet/issues) or starting a discussion thread on the [Elastic Discuss forum](https://discuss.elastic.co/tags/c/observability/apm/58/dotnet).
259
26-
## Getting started
10+
The Elastic Distribution for OpenTelemetry .NET (the distro) provides a zero code change extension of the [OpenTelemetry SDK for .NET](https://opentelemetry.io/docs/languages/net). The distro makes it easier to get started using OpenTelemetry in your .NET applications through strictly OpenTelemetry native means, while also providing a smooth and rich out of the box experience with [Elastic Observability](https://www.elastic.co/observability). It's an explicit goal of this distribution to introduce **no new concepts** in addition to those defined by the wider OpenTelemetry community.
2711

28-
As the distribution is a lightweight extension of the OpenTelemetry SDK, you should be broadly
12+
> [!NOTE]
13+
> For more details about OpenTelemetry distributions in general, visit the [OpenTelemetry documentation](https://opentelemetry.io/docs/concepts/distributions).
14+
15+
With the distro you have access to all the features of the OpenTelemetry SDK for .NET plus:
16+
17+
* Access to SDK improvements and bug fixes contributed by the Elastic team _before_ the changes are available upstream in OpenTelemetry repositories.
18+
* Elastic-specific processors that ensure optimal compatibility when exporting OpenTelemetry signal data to an Elastic backend like an Elastic Observability deployment.
19+
* Preconfigured collection of tracing and metrics signals, applying some opinionated defaults, such as which sources are collected by default.
20+
* Ensuring that the OpenTelemetry protocol (OTLP) exporter is enabled by default.
21+
22+
**Ready to try out the distro?** Follow the step-by-step instructions in [Get started](./docs/get-started.md).
23+
24+
## Install
25+
26+
To get started with the Elastic Distribution for OpenTelemetry .NET, you must add the
27+
[`Elastic.OpenTelemetry`](https://www.nuget.org/packages/Elastic.OpenTelemetry)
28+
NuGet package to your project. This can be achieved by adding the package reference to your project file.
29+
30+
```xml
31+
<PackageReference Include="Elastic.OpenTelemetry" Version="<LATEST>" />
32+
```
33+
34+
> [!NOTE]
35+
> Replace the `<LATEST>` placeholder with the latest available package from [NuGet.org](https://www.nuget.org/packages/Elastic.OpenTelemetry).
36+
37+
## Read the docs
38+
39+
* [Get started](./get-started.md)
40+
* [Configuration](./configure.md)
41+
42+
<!-- ## Getting started
43+
44+
As the distribution is a lightweight extension of the OpenTelemetry SDK, you should be broadly
2945
familiar with the OpenTelemetry SDK concepts and instrumenting applications using the Microsoft
30-
diagnostic APIs. If you are not, we recommend you read the
46+
diagnostic APIs. If you are not, we recommend you read the
3147
[OpenTelemetry SDK documentation](https://opentelemetry.io/docs/languages/net) first.
3248
33-
It's an explicit goal of this distribution to introduce **no new concepts** as defined by the wider OpenTelemetry community.
49+
It's an explicit goal of this distribution to introduce **no new concepts** as defined by the wider OpenTelemetry community.
3450
3551
### Prerequisites
3652
37-
The current documentation and examples are written with .NET 6 and newer applications in mind.
38-
Before continuing, ensure that you have a supported
53+
The current documentation and examples are written with .NET 6 and newer applications in mind.
54+
Before continuing, ensure that you have a supported
3955
[.NET SDK version](https://dotnet.microsoft.com/en-us/download/dotnet) installed locally.
4056
4157
### Installation
4258
43-
To get started with the Elastic Distribution for OpenTelemetry .NET, you must add the
44-
[`Elastic.OpenTelemetry`](https://www.nuget.org/packages/Elastic.OpenTelemetry)
45-
NuGet package to your project. This can be achieved by adding the package reference to your project file.
46-
4759
```xml
4860
<PackageReference Include="Elastic.OpenTelemetry" Version="<LATEST>" />
4961
```
50-
> **_NOTE:_** Replace the `<LATEST>` placeholder with the latest available package from
62+
63+
> **_NOTE:_** Replace the `<LATEST>` placeholder with the latest available package from
5164
[NuGet.org](https://www.nuget.org/packages/Elastic.OpenTelemetry).
5265
53-
After adding the package reference, you can start using the Elastic Distribution for OpenTelemetry .NET
54-
in your application. The distribution includes a transitive dependency on the OpenTelemetry SDK,
55-
so you do not need to add the OpenTelemetry SDK package to your project, although doing so will
56-
cause no harm and may be used to opt into newer SDK versions before the Elastic Distribution for OpenTelemetry .NET
66+
After adding the package reference, you can start using the Elastic Distribution for OpenTelemetry .NET
67+
in your application. The distribution includes a transitive dependency on the OpenTelemetry SDK,
68+
so you do not need to add the OpenTelemetry SDK package to your project, although doing so will
69+
cause no harm and may be used to opt into newer SDK versions before the Elastic Distribution for OpenTelemetry .NET
5770
references them.
5871
59-
The Elastic Distribution for OpenTelemetry .NET is designed to be easy to use and integrate into your
60-
applications. This includes applications which have previously used the OpenTelemetry SDK directly.
61-
In situations where the OpenTelemetry SDK is already used, the only required change is
62-
to add the [`Elastic.OpenTelemetry`](https://www.nuget.org/packages/Elastic.OpenTelemetry) NuGet
63-
package to the project. Doing so will automatically switch to the opinionated configuration provided
72+
The Elastic Distribution for OpenTelemetry .NET is designed to be easy to use and integrate into your
73+
applications. This includes applications which have previously used the OpenTelemetry SDK directly.
74+
In situations where the OpenTelemetry SDK is already used, the only required change is
75+
to add the [`Elastic.OpenTelemetry`](https://www.nuget.org/packages/Elastic.OpenTelemetry) NuGet
76+
package to the project. Doing so will automatically switch to the opinionated configuration provided
6477
by the Elastic Distribution for OpenTelemetry .NET.
6578
6679
### ASP.NET Core usage
6780
68-
A common requirement is to instrument ASP.NET Core applications based on the `Microsoft.Extensions.Hosting`
81+
A common requirement is to instrument ASP.NET Core applications based on the `Microsoft.Extensions.Hosting`
6982
libraries which provide dependency injection via an `IServiceProvider`.
7083
71-
The OpenTelemetry SDK and the Elastic Distribution for OpenTelemetry .NET provide extension methods to enable observability
84+
The OpenTelemetry SDK and the Elastic Distribution for OpenTelemetry .NET provide extension methods to enable observability
7285
features in your application by adding a few lines of code.
7386
74-
In this section, we'll focus on instrumenting an ASP.NET Core minimal API application using the Elastic
75-
OpenTelemetry distribution. Similar steps can also be used to instrument other ASP.NET Core workloads
87+
In this section, we'll focus on instrumenting an ASP.NET Core minimal API application using the Elastic
88+
OpenTelemetry distribution. Similar steps can also be used to instrument other ASP.NET Core workloads
7689
and other host-based applications such as [worker services](https://learn.microsoft.com/en-us/dotnet/core/extensions/workers).
7790
78-
> **_NOTE:_** These examples assume the use of the top-level statements feature introduced in C# 9.0 and the
91+
> **_NOTE:_** These examples assume the use of the top-level statements feature introduced in C# 9.0 and the
7992
default choice for applications created using the latest templates.
8093
81-
To take advantage of the OpenTelemetry SDK instrumentation for ASP.NET Core, add the following
94+
To take advantage of the OpenTelemetry SDK instrumentation for ASP.NET Core, add the following
8295
NuGet package to your project:
8396
8497
```
@@ -88,8 +101,8 @@ NuGet package to your project:
88101
89102
This package includes instrumentation to collect traces for requests handled by ASP.NET Core endpoints.
90103
91-
> **_NOTE:_** The ASP.NET Core instrumentation is not included by default in the Elastic Distribution for OpenTelemetry .NET.
92-
As with all optional instrumentation libraries, you can choose to include them in your application by
104+
> **_NOTE:_** The ASP.NET Core instrumentation is not included by default in the Elastic Distribution for OpenTelemetry .NET.
105+
As with all optional instrumentation libraries, you can choose to include them in your application by
93106
adding a suitable package reference.
94107
95108
Inside the `Program.cs` file of the ASP.NET Core application, add the following two using directives:
@@ -99,12 +112,12 @@ using OpenTelemetry;
99112
using OpenTelemetry.Trace;
100113
```
101114
102-
The OpenTelemetry SDK provides extension methods on the `IServiceCollection` to support enabling the
103-
providers and configuring the SDK. The Elastic Distribution for OpenTelemetry .NET overrides the default SDK registration,
115+
The OpenTelemetry SDK provides extension methods on the `IServiceCollection` to support enabling the
116+
providers and configuring the SDK. The Elastic Distribution for OpenTelemetry .NET overrides the default SDK registration,
104117
adding several opinionated defaults.
105118
106-
In the minimal API template, the `WebApplicationBuilder` exposes a `Services` property that can be used
107-
to register services with the dependency injection container. To enable tracing and metrics collection,
119+
In the minimal API template, the `WebApplicationBuilder` exposes a `Services` property that can be used
120+
to register services with the dependency injection container. To enable tracing and metrics collection,
108121
ensure that the OpenTelemetry SDK is registered.
109122
110123
```csharp
@@ -115,17 +128,17 @@ builder.Services
115128
.AddOpenTelemetry() <2>
116129
.WithTracing(t => t.AddAspNetCoreInstrumentation()); <3>
117130
```
118-
<1> The `AddHttpClient` method registers the `IHttpClientFactory` service with the dependency
119-
injection container. This is NOT required to enable OpenTelemetry, but the example endpoint will use it to
131+
<1> The `AddHttpClient` method registers the `IHttpClientFactory` service with the dependency
132+
injection container. This is NOT required to enable OpenTelemetry, but the example endpoint will use it to
120133
send an HTTP request.
121134
122-
<2> The `AddOpenTelemetry` method registers the OpenTelemetry SDK with the dependency injection
135+
<2> The `AddOpenTelemetry` method registers the OpenTelemetry SDK with the dependency injection
123136
container. When available, the Elastic Distribution for OpenTelemetry .NET will override this to add opinionated defaults.
124137
125138
<3> Configure tracing to instrument requests handled by ASP.NET Core.
126139
127-
With these limited changes to the `Program.cs` file, the application is now configured to use the
128-
OpenTelemetry SDK and the Elastic Distribution for OpenTelemetry .NET to collect traces and metrics, which are exported via
140+
With these limited changes to the `Program.cs` file, the application is now configured to use the
141+
OpenTelemetry SDK and the Elastic Distribution for OpenTelemetry .NET to collect traces and metrics, which are exported via
129142
OTLP.
130143
131144
To demonstrate the tracing capabilities, add a simple endpoint to the application:
@@ -144,20 +157,20 @@ app.MapGet("/", async (IHttpClientFactory httpClientFactory) =>
144157
```
145158
<1> Using this URL will require two redirects, allowing us to see multiple spans in the trace.
146159
147-
The Elastic Distribution for OpenTelemetry .NET will automatically enable the exporting of signals via the OTLP exporter. This
148-
exporter requires that endpoint(s) are configured. A common mechanism for configuring endpoints is
149-
via environment variables.
160+
The Elastic Distribution for OpenTelemetry .NET will automatically enable the exporting of signals via the OTLP exporter. This
161+
exporter requires that endpoint(s) are configured. A common mechanism for configuring endpoints is
162+
via environment variables.
150163
151-
This demo uses an Elastic Cloud deployment as the destination for our observability data. From Kibana
152-
running in Elastic Cloud, navigate to the observability set up guides. Select the OpenTelemetry option
164+
This demo uses an Elastic Cloud deployment as the destination for our observability data. From Kibana
165+
running in Elastic Cloud, navigate to the observability set up guides. Select the OpenTelemetry option
153166
to view the configuration details that should be supplied to the application.
154167
155168
![Elastic Cloud OpenTelemetry configuration](https://raw.githubusercontent.com/elastic/elastic-otel-dotnet/main/docs/images/elastic-cloud-opentelemetry-configuration.png)
156169
157-
Configure environment variables for the application either in `launchSettings.json` or in the environment
158-
where the application is running.
170+
Configure environment variables for the application either in `launchSettings.json` or in the environment
171+
where the application is running.
159172
160-
Once configured, run the application and make a request to the root endpoint. A trace will be generated
173+
Once configured, run the application and make a request to the root endpoint. A trace will be generated
161174
and exported to the OTLP endpoint.
162175
163176
To view the traces, you can use the Elastic APM UI.
@@ -172,10 +185,10 @@ you can install this package:
172185
```xml
173186
<PackageReference Include="Elastic.OpenTelemetry" Version="<LATEST>" />
174187
```
175-
> **_NOTE:_** Replace the `<LATEST>` placeholder with the latest available package from
188+
> **_NOTE:_** Replace the `<LATEST>` placeholder with the latest available package from
176189
[NuGet.org](https://www.nuget.org/packages/Elastic.OpenTelemetry).
177190
178-
Ensure you call `AddOpenTelemetry` to enable OpenTelemetry just as you would when using OpenTelemetry directly.
191+
Ensure you call `AddOpenTelemetry` to enable OpenTelemetry just as you would when using OpenTelemetry directly.
179192
Our package intercepts this call to set up our defaults, but can be further build upon as per usual:
180193
181194
```csharp
@@ -189,20 +202,20 @@ builder.Services.AddOpenTelemetry()
189202
190203
### Manual Instrumentation usage
191204
192-
In environments where an `IServiceCollection` is unavailable you may manually start instrumenting by creating
193-
an instance of `ElasticOpenTelemetryBuilder`.
205+
In environments where an `IServiceCollection` is unavailable you may manually start instrumenting by creating
206+
an instance of `ElasticOpenTelemetryBuilder`.
194207
195208
```csharp
196209
await using var session = new ElasticOpenTelemetryBuilder()
197210
.WithTracing(b => b.AddSource(ActivitySourceName))
198211
.Build();
199212
```
200213
201-
This will setup instrumentation for as long as `session` is not disposed. We would generally expect the `session`
214+
This will setup instrumentation for as long as `session` is not disposed. We would generally expect the `session`
202215
to live for the life of the application.
203216
204-
`ElasticOpenTelemetryBuilder` is an implementation of [`IOpenTelemetryBuilder`](https://github.com/open-telemetry/opentelemetry-dotnet/blob/70657395b82ba00b8a1e848e8832b77dff94b6d2/src/OpenTelemetry.Api.ProviderBuilderExtensions/IOpenTelemetryBuilder.cs#L12).
217+
`ElasticOpenTelemetryBuilder` is an implementation of [`IOpenTelemetryBuilder`](https://github.com/open-telemetry/opentelemetry-dotnet/blob/70657395b82ba00b8a1e848e8832b77dff94b6d2/src/OpenTelemetry.Api.ProviderBuilderExtensions/IOpenTelemetryBuilder.cs#L12).
205218
206-
This is important to know because any instrumentation configuration is automatically exposed by the base
207-
OpenTelemetry package as extension methods on `IOpenTelemetryBuilder`. You will not lose functionality by
208-
using our builder.
219+
This is important to know because any instrumentation configuration is automatically exposed by the base
220+
OpenTelemetry package as extension methods on `IOpenTelemetryBuilder`. You will not lose functionality by
221+
using our builder. -->

‎docs/configure.md

Lines changed: 5 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -9,11 +9,6 @@ Assumptions we're comfortable making about the reader:
99

1010
# Configure
1111

12-
> [!WARNING]
13-
> The Elastic Distribution for OpenTelemetry .NET is not yet recommended for production use. Functionality may be changed or removed in future releases. Alpha releases are not subject to the support SLA of official GA features.
14-
>
15-
> We welcome your feedback! You can reach us by [opening a GitHub issue](https://github.com/elastic/elastic-otel-dotnet/issues) or starting a discussion thread on the [Elastic Discuss forum](https://discuss.elastic.co/tags/c/observability/apm/58/dotnet).
16-
1712
<!-- ✅ How users set configuration options -->
1813
## Configuration methods
1914

@@ -218,9 +213,11 @@ When sending data to Elastic, there are two ways you can authenticate: using an
218213

219214
### Use an APM agent key (API key)
220215

221-
<!-- ✅ What is this? -->
222-
<!-- ✅ Why would someone use it? -->
223-
It is also possible to authenticate to an Elastic Observability endpoint using an [APM agent key](https://www.elastic.co/guide/en/observability/current/apm-api-key.html). APM agent keys are revocable, you can have more than one of them, and you can add or remove them without restarting APM Server.
216+
<!-- ✅ What and why -->
217+
[APM agent keys](https://www.elastic.co/guide/en/observability/current/apm-api-key.html) are
218+
used to authorize requests to an Elastic Observability endpoint.
219+
APM agent keys are revocable, you can have more than one of them, and
220+
you can add or remove them without restarting APM Server.
224221

225222
<!-- ✅ How do you authenticate using this method? -->
226223
To create and manage APM agent keys in Kibana:

0 commit comments

Comments
 (0)