diff --git a/README.md b/README.md index 5ac023b..fb59e95 100644 --- a/README.md +++ b/README.md @@ -1,8 +1,8 @@ [![Pull Request Validation](https://github.com/elastic/elastic-otel-dotnet/actions/workflows/ci.yml/badge.svg)](https://github.com/elastic/elastic-otel-dotnet/actions/workflows/ci.yml) -# Elastic OpenTelemetry .NET Distribution +# Elastic Distribution for OpenTelemetry .NET -The Elastic OpenTelemetry .NET Distribution provides a zero code change extension +The Elastic Distribution for OpenTelemetry .NET provides a zero code change extension to [OpenTelemetry SDK for .NET](https://opentelemetry.io/docs/languages/net). These extensions ensure a smooth and rich out of the box experience with [Elastic Observability](https://www.elastic.co/observability) through strictly OpenTelemetry native means. @@ -10,14 +10,14 @@ through strictly OpenTelemetry native means. This ensures there are no new concepts to learn with the full OpenTelemetry ecosystem remains at ones fingertips. Read more about the concept of [OpenTelemetry Distributions](https://opentelemetry.io/docs/concepts/distributions). -The Elastic distribution includes some Elastic-specific processors to ensure the best +The Elastic Distribution for OpenTelemetry .NET includes some Elastic-specific processors to ensure the best compatibility when exporting OpenTelemetry signal data [Elastic Observability](https://www.elastic.co/observability). The distribution also preconfigures the collection of tracing, metrics and logs signals, applying some opinionated defaults, such as which sources are collected by default. The distribution also ensures that the OTLP exporter is enabled by default. -> **_IMPORTANT:_** The Elastic distribution is currently in early alpha release status. It is not yet feature -complete and may contain bugs. We are actively working on improving the distribution and +> **_IMPORTANT:_** The Elastic Distribution for OpenTelemetry .NET is currently in early alpha release status. +> It is not yet feature complete and may contain bugs. We are actively working on improving the distribution and adding new features. > > If you would like to experience the alpha and help us improve the distribution by providing @@ -40,7 +40,7 @@ Before continuing, ensure that you have a supported ### Installation -To get started with the Elastic OpenTelemetry .NET Distribution, you must add the +To get started with the Elastic Distribution for OpenTelemetry .NET, you must add the [`Elastic.OpenTelemetry`](https://www.nuget.org/packages/Elastic.OpenTelemetry) NuGet package to your project. This can be achieved by adding the package reference to your project file. @@ -50,25 +50,25 @@ NuGet package to your project. This can be achieved by adding the package refere > **_NOTE:_** Replace the `` placeholder with the latest available package from [NuGet.org](https://www.nuget.org/packages/Elastic.OpenTelemetry). -After adding the package reference, you can start using the Elastic OpenTelemetry distribution +After adding the package reference, you can start using the Elastic Distribution for OpenTelemetry .NET in your application. The distribution includes a transitive dependency on the OpenTelemetry SDK, so you do not need to add the OpenTelemetry SDK package to your project, although doing so will -cause no harm and may be used to opt into newer SDK versions before the Elastic distribution +cause no harm and may be used to opt into newer SDK versions before the Elastic Distribution for OpenTelemetry .NET references them. -The Elastic OpenTelemetry distribution is designed to be easy to use and integrate into your +The Elastic Distribution for OpenTelemetry .NET is designed to be easy to use and integrate into your applications. This includes applications which have previously used the OpenTelemetry SDK directly. In situations where the OpenTelemetry SDK is already used, the only required change is to add the [`Elastic.OpenTelemetry`](https://www.nuget.org/packages/Elastic.OpenTelemetry) NuGet package to the project. Doing so will automatically switch to the opinionated configuration provided -by the Elastic distribution. +by the Elastic Distribution for OpenTelemetry .NET. ### ASP.NET Core usage A common requirement is to instrument ASP.NET Core applications based on the `Microsoft.Extensions.Hosting` libraries which provide dependency injection via an `IServiceProvider`. -The OpenTelemetry SDK and the Elastic distribution provide extension methods to enable observability +The OpenTelemetry SDK and the Elastic Distribution for OpenTelemetry .NET provide extension methods to enable observability features in your application by adding a few lines of code. In this section, we'll focus on instrumenting an ASP.NET Core minimal API application using the Elastic @@ -88,7 +88,7 @@ NuGet package to your project: This package includes instrumentation to collect traces for requests handled by ASP.NET Core endpoints. -> **_NOTE:_** The ASP.NET Core instrumentation is not included by default in the Elastic OpenTelemetry distribution. +> **_NOTE:_** The ASP.NET Core instrumentation is not included by default in the Elastic Distribution for OpenTelemetry .NET. As with all optional instrumentation libraries, you can choose to include them in your application by adding a suitable package reference. @@ -100,7 +100,7 @@ using OpenTelemetry.Trace; ``` The OpenTelemetry SDK provides extension methods on the `IServiceCollection` to support enabling the -providers and configuring the SDK. The Elastic distribution overrides the default SDK registration, +providers and configuring the SDK. The Elastic Distribution for OpenTelemetry .NET overrides the default SDK registration, adding several opinionated defaults. In the minimal API template, the `WebApplicationBuilder` exposes a `Services` property that can be used @@ -120,12 +120,12 @@ injection container. This is NOT required to enable OpenTelemetry, but the examp send an HTTP request. <2> The `AddOpenTelemetry` method registers the OpenTelemetry SDK with the dependency injection -container. When available, the Elastic distribution will override this to add opinionated defaults. +container. When available, the Elastic Distribution for OpenTelemetry .NET will override this to add opinionated defaults. <3> Configure tracing to instrument requests handled by ASP.NET Core. With these limited changes to the `Program.cs` file, the application is now configured to use the -OpenTelemetry SDK and the Elastic distribution to collect traces and metrics, which are exported via +OpenTelemetry SDK and the Elastic Distribution for OpenTelemetry .NET to collect traces and metrics, which are exported via OTLP. To demonstrate the tracing capabilities, add a simple endpoint to the application: @@ -144,7 +144,7 @@ app.MapGet("/", async (IHttpClientFactory httpClientFactory) => ``` <1> Using this URL will require two redirects, allowing us to see multiple spans in the trace. -The Elastic distribution will automatically enable the exporting of signals via the OTLP exporter. This +The Elastic Distribution for OpenTelemetry .NET will automatically enable the exporting of signals via the OTLP exporter. This exporter requires that endpoint(s) are configured. A common mechanism for configuring endpoints is via environment variables. diff --git a/docs/configure.mdx b/docs/configure.mdx index c1486d6..a9491bc 100644 --- a/docs/configure.mdx +++ b/docs/configure.mdx @@ -6,14 +6,14 @@ title: Configure Configuration of the OpenTelemetry SDK should be performed through the mechanisms [documented on the OpenTelemetry website](https://opentelemetry.io/docs/languages/net/automatic/configuration/). -The Elastic distribution can be further configured using advanced settings when +The Elastic Distribution for OpenTelemetry .NET can be further configured using advanced settings when you need complete control of its behaviour. Configuration can be achieved by setting environment variables, using the `IConfiguration` integration, or manually configuring the Elastic distribution. ## Environment variables -The Elastic distribution can be configured using environment variables. This is a cross-platform -way to configure the Elastic distribution and is especially useful in containerized environments. +The Elastic Distribution for OpenTelemetry .NET can be configured using environment variables. This is a cross-platform +way to configure the Elastic Distribution for OpenTelemetry .NET and is especially useful in containerized environments. Environment variables are read at startup and can be used to configure the Elastic distribution. For details of the various options available and their corresponding environment variable names, @@ -39,9 +39,9 @@ var currentConfig = builder.Configuration; [^1] By default, at this stage, the configuration will be populated from the default configuration sources, including the `appsettings.json` file(s) and command-line arguments. You may use these sources to define -the configuration for the Elastic distribution. +the configuration for the Elastic Distribution for OpenTelemetry .NET. -For example, you can define the configuration for the Elastic distribution in the `appsettings.json` file: +For example, you can define the configuration for the Elastic Distribution for OpenTelemetry .NET in the `appsettings.json` file: ```json { @@ -66,7 +66,7 @@ In all other scenarios, configuration can be achieved manually in code. This is an instance of `ElasticOpenTelemetryBuilderOptions` and passing it to the `ElasticOpenTelemetryBuilder` constructor or an overload of the `AddElasticOpenTelemetry` extension method on the `IServiceCollection`. -For example, in traditional console applications, you can configure the Elastic distribution like this: +For example, in traditional console applications, you can configure the Elastic Distribution for OpenTelemetry .NET like this: ```csharp using Elastic.OpenTelemetry; @@ -94,13 +94,13 @@ await using var session = new ElasticOpenTelemetryBuilder(builderOptions) [^4] setting the corresponding property. [^3]: This example sets the file log directory to `C:\Logs` which enables diagnostic file logging. [^4]: Pass the `ElasticOpenTelemetryBuilderOptions` instance to the `ElasticOpenTelemetryBuilder` constructor -to configure the Elastic distribution. +to configure the Elastic Distribution for OpenTelemetry .NET. ## Configuration options ### `FileLogDirectory` -A string specifying the directory where the Elastic distribution will write diagnostic log files. +A string specifying the directory where the Elastic Distribution for OpenTelemetry .NET will write diagnostic log files. When not provided, no file logging will occur. Each new .NET process will create a new log file in the specified directory. @@ -144,21 +144,21 @@ an OTLP endpoint. This can be useful when you want to test applications without ### `EnabledElasticDefaults` A comma-separated list of Elastic defaults to enable. This can be useful when you want to enable -only some of the Elastic distribution opinionated defaults. +only some of the Elastic Distribution for OpenTelemetry .NET opinionated defaults. Valid options: `None`, `Tracing`, `Metrics`, `Logging`. Except for the `None` option, all other options can be combined. -When this setting is not configured or the value is `string.Empty`, all Elastic distribution defaults will be enabled. +When this setting is not configured or the value is `string.Empty`, all Elastic Distribution for OpenTelemetry .NET defaults will be enabled. -When `None` is specified, no Elastic distribution defaults will be enabled, and you will need to manually +When `None` is specified, no Elastic Distribution for OpenTelemetry .NET defaults will be enabled, and you will need to manually configure the OpenTelemetry SDK to enable collection of telemetry signals. In this mode, the Elastic distribution does not provide any opinionated defaults, nor register any processors, allowing you to start with the "vanilla" OpenTelemetry SDK configuration. You may then choose to configure the various providers and register processors as required. -In all other cases, the Elastic distribution will enable the specified defaults. For example, to enable only +In all other cases, the Elastic Distribution for OpenTelemetry .NET will enable the specified defaults. For example, to enable only Elastic defaults only for tracing and metrics, set this value to `Tracing,Metrics`. | Environment variable name | IConfiguration key | diff --git a/docs/elastic-otel-dotnet.docnav.json b/docs/elastic-otel-dotnet.docnav.json index 8a15006..d6740bf 100644 --- a/docs/elastic-otel-dotnet.docnav.json +++ b/docs/elastic-otel-dotnet.docnav.json @@ -3,7 +3,7 @@ "id": "elastic-otel-dotnet", "landingPageSlug": "/otel-dotnet/intro", "icon": "logoObservability", - "description": "Elastic OpenTelemetry Distribution for .NET", + "description": "Elastic Distribution for OpenTelemetry .NET", "items": [ { "label": "Get started", diff --git a/docs/get-started.mdx b/docs/get-started.mdx index 260b1dd..a5da728 100644 --- a/docs/get-started.mdx +++ b/docs/get-started.mdx @@ -27,17 +27,17 @@ https://dotnet.microsoft.com/en-us/download/dotnet[.NET SDK version] installed l ## Installation -To get started with the Elastic OpenTelemetry distribution, you must add the Elastic OpenTelemetry +To get started with the Elastic OpenTelemetry Distribution for .NET, you must add the `Elastic.OpenTelemetry` NuGet package to your project. This can be achieved by adding the package reference to your project file. ```xml ``` -After adding the package reference, you can start using the Elastic OpenTelemetry distribution +After adding the package reference, you can start using the Elastic OpenTelemetry Distribution for .NET in your application. The distribution includes a transitive dependency on the OpenTelemetry SDK, so you do not need to add the OpenTelemetry SDK package to your project, although doing so will -cause no harm and may be used to opt into newer SDK versions before the Elastic distribution +cause no harm and may be used to opt into newer SDK versions before the Elastic OpenTelemetry Distribution for .NET references them. The Elastic OpenTelemetry distribution is designed to be easy to use and integrate into your @@ -51,7 +51,7 @@ switch to the opinionated configuration provided by the Elastic distribution. A common requirement is to instrument ASP.NET Core applications based on the `Microsoft.Extensions.Hosting` libraries which provide dependency injection via an `IServiceProvider`. -The OpenTelemetry SDK and the Elastic distribution provide extension methods to enable observability +The OpenTelemetry SDK and the Elastic Distribution for OpenTelemetry .NET provide extension methods to enable observability features in your application by adding a few lines of code. In this section, we'll focus on instrumenting an ASP.NET Core minimal API application using the Elastic @@ -73,7 +73,7 @@ NuGet package to your project: This package includes instrumentation to collect traces for requests handled by ASP.NET Core endpoints. - The ASP.NET Core instrumentation is not included by default in the Elastic OpenTelemetry distribution. + The ASP.NET Core instrumentation is not included by default in the Elastic Distribution for OpenTelemetry .NET. As with all optional instrumentation libraries, you can choose to include them in your application by adding a suitable package reference. @@ -86,7 +86,7 @@ using OpenTelemetry.Trace; ``` The OpenTelemetry SDK provides extension methods on the `IServiceCollection` to support enabling the -providers and configuring the SDK. The Elastic distribution overrides the default SDK registration, +providers and configuring the SDK. The Elastic Distribution for OpenTelemetry .NET overrides the default SDK registration, adding several opinionated defaults. In the minimal API template, the `WebApplicationBuilder` exposes a `Services` property that can be used @@ -105,11 +105,11 @@ builder.Services injection container. This is NOT required to enable OpenTelemetry, but the example endpoint will use it to send an HTTP request. [^2]: The `AddOpenTelemetry` method registers the OpenTelemetry SDK with the dependency injection -container. When available, the Elastic distribution will override this to add opinionated defaults. +container. When available, the Elastic Distribution for OpenTelemetry .NET will override this to add opinionated defaults. [^3]: Configure tracing to instrument requests handled by ASP.NET Core. With these limited changes to the `Program.cs` file, the application is now configured to use the -OpenTelemetry SDK and the Elastic distribution to collect traces and metrics, which are exported via +OpenTelemetry SDK and the Elastic Distribution for OpenTelemetry .NET to collect traces and metrics, which are exported via OTLP. To demonstrate the tracing capabilities, add a simple endpoint to the application: @@ -128,7 +128,7 @@ app.MapGet("/", async (IHttpClientFactory httpClientFactory) => ``` [^1]: Using this URL will require two redirects, allowing us to see multiple spans in the trace. -The Elastic distribution will automatically enable the exporting of signals via the OTLP exporter. This +The Elastic Distribution for OpenTelemetry .NET will automatically enable the exporting of signals via the OTLP exporter. This exporter requires that endpoint(s) are configured. A common mechanism for configuring endpoints is via environment variables. diff --git a/docs/intro.mdx b/docs/intro.mdx index bd120ae..2610dc4 100644 --- a/docs/intro.mdx +++ b/docs/intro.mdx @@ -12,13 +12,13 @@ title: Elastic OpenTelemetry Distribution for .NET early feedback, see [get started](get-started). -The `Elastic.OpenTelemetry` package contains an Elastic distribution of the +The `Elastic.OpenTelemetry` package contains an Elastic Distribution for OpenTelemetry .NET of the [OpenTelemetry SDK for .NET](https://opentelemetry.io/docs/languages/net). A distribution is a wrapper around an upstream OpenTelemetry repository with some customizations. For more details about distributions in general, visit the [OpenTelemetry documentation](https://opentelemetry.io/docs/concepts/distributions). -The Elastic distribution includes some Elastic-specific processors to ensure the best +The Elastic Distribution for OpenTelemtry .NET includes some Elastic-specific processors to ensure the best compatibility when exporting OpenTelemetry signal data to an Elastic backend such as Elastic APM server. The distribution also preconfigures the collection of tracing and metrics signals, applying some opinionated defaults, such as which sources are diff --git a/src/Elastic.OpenTelemetry/Configuration/ElasticOpenTelemetryOptions.cs b/src/Elastic.OpenTelemetry/Configuration/ElasticOpenTelemetryOptions.cs index 2db95c3..88cff96 100644 --- a/src/Elastic.OpenTelemetry/Configuration/ElasticOpenTelemetryOptions.cs +++ b/src/Elastic.OpenTelemetry/Configuration/ElasticOpenTelemetryOptions.cs @@ -148,7 +148,7 @@ private static string GetDefaultLogDirectory() public string LogDirectoryDefault => _defaultLogDirectory; /// - /// The output directory where the Elastic distribution of OpenTelemetry will write log files. + /// The output directory where the Elastic Distribution for OpenTelemetry .NET will write log files. /// /// /// When configured, a file log will be created in this directory with the name diff --git a/src/Elastic.OpenTelemetry/Diagnostics/LoggerMessages.cs b/src/Elastic.OpenTelemetry/Diagnostics/LoggerMessages.cs index 6bea4f5..a32ebe4 100644 --- a/src/Elastic.OpenTelemetry/Diagnostics/LoggerMessages.cs +++ b/src/Elastic.OpenTelemetry/Diagnostics/LoggerMessages.cs @@ -36,13 +36,13 @@ internal static partial class LoggerMessages public static void LogAgentPreamble(this ILogger logger) { var process = Process.GetCurrentProcess(); - logger.LogInformation("Elastic OpenTelemetry Distribution: {AgentInformationalVersion}", VersionHelper.InformationalVersion); + logger.LogInformation("Elastic Distribution for OpenTelemetry .NET: {AgentInformationalVersion}", VersionHelper.InformationalVersion); if (logger is CompositeLogger distributionLogger) { if (distributionLogger.LogFileEnabled) - logger.LogInformation("Elastic OpenTelemetry Distribution, log file: {LogFilePath}", distributionLogger.LogFilePath); + logger.LogInformation("Elastic Distribution for OpenTelemetry .NET, log file: {LogFilePath}", distributionLogger.LogFilePath); else - logger.LogInformation("Elastic OpenTelemetry Distribution, log file: "); + logger.LogInformation("Elastic Distribution for OpenTelemetry .NET, log file: "); } logger.LogInformation("Process ID: {ProcessId}", process.Id); diff --git a/src/Elastic.OpenTelemetry/Elastic.OpenTelemetry.csproj b/src/Elastic.OpenTelemetry/Elastic.OpenTelemetry.csproj index d0a6200..3c67815 100644 --- a/src/Elastic.OpenTelemetry/Elastic.OpenTelemetry.csproj +++ b/src/Elastic.OpenTelemetry/Elastic.OpenTelemetry.csproj @@ -3,7 +3,7 @@ Library netstandard2.0;netstandard2.1;net462;net6.0;net8.0 - Elastic OpenTelemetry .NET Distribution + Elastic Distribution for OpenTelemetry .NET OpenTelemetry extensions for Elastic Observability, fully native with zero code changes. elastic;opentelemetry;observabillity;apm;logs;metrics;traces;monitoring enable diff --git a/src/Elastic.OpenTelemetry/ElasticOpenTelemetryBuilder.cs b/src/Elastic.OpenTelemetry/ElasticOpenTelemetryBuilder.cs index 751a9ff..cd7ee7d 100644 --- a/src/Elastic.OpenTelemetry/ElasticOpenTelemetryBuilder.cs +++ b/src/Elastic.OpenTelemetry/ElasticOpenTelemetryBuilder.cs @@ -50,7 +50,7 @@ public class ElasticOpenTelemetryBuilder : IOpenTelemetryBuilder public IServiceCollection Services { get; } /// - /// Shared bootstrap routine for the Elastic OpenTelemetry Distribution. + /// Shared bootstrap routine for the Elastic Distribution for OpenTelemetry .NET. /// Used to ensure auto instrumentation and manual instrumentation bootstrap the same way. /// public static (EventListener, ILogger) Bootstrap(ElasticOpenTelemetryBuilderOptions options) diff --git a/src/Elastic.OpenTelemetry/Extensions/MeterProviderBuilderExtensions.cs b/src/Elastic.OpenTelemetry/Extensions/MeterProviderBuilderExtensions.cs index 4be5dd6..968ff5a 100644 --- a/src/Elastic.OpenTelemetry/Extensions/MeterProviderBuilderExtensions.cs +++ b/src/Elastic.OpenTelemetry/Extensions/MeterProviderBuilderExtensions.cs @@ -13,7 +13,7 @@ namespace Elastic.OpenTelemetry.Extensions; /// public static class MeterProviderBuilderExtensions { - /// Use Elastic distribution defaults for + /// Use Elastic Distribution for OpenTelemetry .NET defaults for public static MeterProviderBuilder UseElasticDefaults(this MeterProviderBuilder builder, ILogger? logger = null) { logger ??= NullLogger.Instance; diff --git a/src/Elastic.OpenTelemetry/Extensions/TracerProviderBuilderExtensions.cs b/src/Elastic.OpenTelemetry/Extensions/TracerProviderBuilderExtensions.cs index 6db8a08..d222dbc 100644 --- a/src/Elastic.OpenTelemetry/Extensions/TracerProviderBuilderExtensions.cs +++ b/src/Elastic.OpenTelemetry/Extensions/TracerProviderBuilderExtensions.cs @@ -33,7 +33,7 @@ private static TracerProviderBuilder LogAndAddProcessor(this TracerProviderBuild return builder.AddProcessor(processor); } - /// Use Elastic distribution defaults for + /// Use Elastic Distribution for OpenTelemetry .NET defaults for public static TracerProviderBuilder UseElasticDefaults(this TracerProviderBuilder builder, ILogger? logger = null) { logger ??= NullLogger.Instance; diff --git a/src/Elastic.OpenTelemetry/IInstrumentationLifetime.cs b/src/Elastic.OpenTelemetry/IInstrumentationLifetime.cs index 754da59..31f667b 100644 --- a/src/Elastic.OpenTelemetry/IInstrumentationLifetime.cs +++ b/src/Elastic.OpenTelemetry/IInstrumentationLifetime.cs @@ -4,6 +4,6 @@ namespace Elastic.OpenTelemetry; /// -/// A logical Elastic OpenTelemetry Distribution. +/// A logical Elastic Distribution for OpenTelemetry .NET instance. /// public interface IInstrumentationLifetime : IDisposable, IAsyncDisposable; diff --git a/tests/Elastic.OpenTelemetry.Tests/LoggingTests.cs b/tests/Elastic.OpenTelemetry.Tests/LoggingTests.cs index 69f0743..7d1a363 100644 --- a/tests/Elastic.OpenTelemetry.Tests/LoggingTests.cs +++ b/tests/Elastic.OpenTelemetry.Tests/LoggingTests.cs @@ -33,9 +33,9 @@ public async Task ObserveLogging() } //assert preamble information gets logged - logger.Messages.Should().ContainMatch("*Elastic OpenTelemetry Distribution:*"); + logger.Messages.Should().ContainMatch("*Elastic Distribution for OpenTelemetry .NET:*"); - var preambles = logger.Messages.Where(l => l.Contains("[Information] Elastic OpenTelemetry Distribution:")).ToList(); + var preambles = logger.Messages.Where(l => l.Contains("[Information] Elastic Distribution for OpenTelemetry .NET:")).ToList(); preambles.Should().NotBeNull().And.HaveCount(1); // assert instrumentation session logs initialized and stack trace gets dumped.