Add initial documentation

.vscode/settings.json

@@ -0,0 +1 @@
+{}

Elastic.OpenTelemetry.sln

@@ -20,9 +20,9 @@ Project("{9A19103F-16F7-4668-BE54-9A1E7A4F7556}") = "docs", "docs\docs.csproj",
 EndProject
 Project("{2150E333-8FDC-42A3-9474-1A3956D46DE8}") = "tests", "tests", "{AAD39891-0B70-47FA-A212-43E1AAE5DF56}"
 	ProjectSection(SolutionItems) = preProject
+		tests\.runsettings = tests\.runsettings
 		tests\Directory.Build.props = tests\Directory.Build.props
 		tests\xunit.runner.json = tests\xunit.runner.json
-		tests\.runsettings = tests\.runsettings
 	EndProjectSection
 EndProject
 Project("{9A19103F-16F7-4668-BE54-9A1E7A4F7556}") = "Elastic.OpenTelemetry.Tests", "tests\Elastic.OpenTelemetry.Tests\Elastic.OpenTelemetry.Tests.csproj", "{22BF9223-3A6D-4197-8527-3E4E43A98A81}"
@@ -35,6 +35,10 @@ Project("{9A19103F-16F7-4668-BE54-9A1E7A4F7556}") = "Example.Elastic.OpenTelemet
 EndProject
 Project("{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}") = "Elastic.OpenTelemetry.EndToEndTests", "tests\Elastic.OpenTelemetry.EndToEndTests\Elastic.OpenTelemetry.EndToEndTests.csproj", "{B970DBE1-6A04-4014-A285-6A9F36421025}"
 EndProject
+Project("{9A19103F-16F7-4668-BE54-9A1E7A4F7556}") = "Elastic.OpenTelemetry.AspNetCore", "src\Elastic.OpenTelemetry.AspNetCore\Elastic.OpenTelemetry.AspNetCore.csproj", "{2139F902-B10D-475D-8A38-F78962CEBFD3}"
+EndProject
+Project("{9A19103F-16F7-4668-BE54-9A1E7A4F7556}") = "Example.MinimalApi", "examples\Example.MinimalApi\Example.MinimalApi.csproj", "{397D7E8D-39C2-41D6-9D4D-F1D35666926A}"
+EndProject
 Global
 	GlobalSection(SolutionConfigurationPlatforms) = preSolution
 		Debug|Any CPU = Debug|Any CPU
@@ -77,6 +81,10 @@ Global
 		{B970DBE1-6A04-4014-A285-6A9F36421025}.Debug|Any CPU.Build.0 = Debug|Any CPU
 		{B970DBE1-6A04-4014-A285-6A9F36421025}.Release|Any CPU.ActiveCfg = Release|Any CPU
 		{B970DBE1-6A04-4014-A285-6A9F36421025}.Release|Any CPU.Build.0 = Release|Any CPU
+		{397D7E8D-39C2-41D6-9D4D-F1D35666926A}.Debug|Any CPU.ActiveCfg = Debug|Any CPU
+		{397D7E8D-39C2-41D6-9D4D-F1D35666926A}.Debug|Any CPU.Build.0 = Debug|Any CPU
+		{397D7E8D-39C2-41D6-9D4D-F1D35666926A}.Release|Any CPU.ActiveCfg = Release|Any CPU
+		{397D7E8D-39C2-41D6-9D4D-F1D35666926A}.Release|Any CPU.Build.0 = Release|Any CPU
 	EndGlobalSection
 	GlobalSection(SolutionProperties) = preSolution
 		HideSolutionNode = FALSE
@@ -88,6 +96,7 @@ Global
 		{EC81FA30-C765-4F04-8679-86F16DA3CC65} = {4E95C87B-655B-4BC3-8F2A-DF06B7AAB7E9}
 		{4377A059-16E0-4D5D-AC03-44C09BCE5BC4} = {4E95C87B-655B-4BC3-8F2A-DF06B7AAB7E9}
 		{B970DBE1-6A04-4014-A285-6A9F36421025} = {AAD39891-0B70-47FA-A212-43E1AAE5DF56}
+		{397D7E8D-39C2-41D6-9D4D-F1D35666926A} = {4E95C87B-655B-4BC3-8F2A-DF06B7AAB7E9}
 	EndGlobalSection
 	GlobalSection(ExtensibilityGlobals) = postSolution
 		SolutionGuid = {573B2B5F-8CBB-4D52-A55A-4E65E282AAFB}

docs/docs.csproj

@@ -1,4 +1,5 @@
 <Project Sdk="Microsoft.NET.Sdk">
+
   <PropertyGroup>
     <TargetFramework>net8.0</TargetFramework>
     <IsPackable>False</IsPackable>

docs/getting-started.asciidoc

@@ -0,0 +1,155 @@
+[[getting-started]]
+== Getting started
+
+This page will show you how to get started with Elastic OpenTelemetry distribution for .NET. 
+
+As the distribution is a lightweight wrapper around the OpenTelemetry SDK, you should be broadly 
+familiar with the OpenTelemetry SDK concepts and instrumenting applications using the Microsoft
+diagnostic APIs. If you are not, we recommend you read the 
+https://opentelemetry.io/docs/languages/net[OpenTelemetry SDK documentation] first.
+
+[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 
+adding new features.
+
+If you would like to experience the alpha and help us improve the distribution by providing 
+early feedback, you can follow the steps below to get started.
+--
+
+=== Prerequisites
+
+The current documentation and examples are written with .NET 6 and newer applications in mind. 
+Before continuing, ensure that you have a supported 
+https://dotnet.microsoft.com/en-us/download/dotnet[.NET SDK version] installed locally.
+
+=== Installation
+
+To get started with the Elastic OpenTelemetry distribution, you must add the Elastic OpenTelemetry 
+NuGet package to your project. This can be achieved by adding the package reference to your project file.
+
+[source,xml]
+----
+<PackageReference Include="Elastic.OpenTelemetry" Version="0.1.0-alpha.1" />
+----
+
+After adding the package reference, you can start using the Elastic OpenTelemetry distribution 
+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 
+references them.
+
+The Elastic OpenTelemetry distribution 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` NuGet package to the project. Doing so will automatically 
+switch to the opinionated configuration provided by the Elastic distribution.
+
+=== 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 
+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 
+OpenTelemetry distribution. Similar steps can also be used to instrument other ASP.NET Core workloads 
+and other host-based applications such as https://learn.microsoft.com/en-us/dotnet/core/extensions/workers[worker services].
+
+[NOTE]
+--
+These examples assume the use of the top-level statements feature introduced in C# 9.0 and the 
+default choice for applications created using the latest templates.
+--
+
+To take advantage of the OpenTelemetry SDK instrumentation for ASP.NET Core, add the following 
+NuGet package to your project:
+
+[source,xml]
+----
+<PackageReference Include="OpenTelemetry.Instrumentation.AspNetCore" Version="1.7.0" />
+----
+
+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. 
+As with all optional instrumentation libraries, you can choose to include them in your application by 
+adding a suitable package reference.
+--
+
+Inside the `Program.cs` file of the ASP.NET Core application, add the following two using directives:
+
+[source,csharp]
+----
+using OpenTelemetry;
+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, 
+adding several opinionated defaults.
+
+In the minimal API template, the `WebApplicationBuilder` exposes a `Services` property that can be used 
+to register services with the dependency injection container. To enable tracing and metrics collection, 
+ensure that the OpenTelemetry SDK is registered.
+
+[source,csharp]
+----
+var builder = WebApplication.CreateBuilder(args);
+
+builder.Services
+	.AddHttpClient() <1>
+	.AddOpenTelemetry() <2>
+		.WithTracing(t => t.AddAspNetCoreInstrumentation()); <3>
+----
+<1> The `AddHttpClient` method registers the `IHttpClientFactory` service with the dependency 
+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.
+<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 
+OTLP.
+
+To demonstrate the tracing capabilities, add a simple endpoint to the application:
+
+[source,csharp]
+----
+app.MapGet("/", async (IHttpClientFactory httpClientFactory) =>
+{
+	using var client = httpClientFactory.CreateClient();
+
+	await Task.Delay(100);
+	var response = await client.GetAsync("http://elastic.co"); <1>
+	await Task.Delay(50);
+
+	return response.StatusCode == System.Net.HttpStatusCode.OK ? Results.Ok() : Results.StatusCode(500);
+});
+----
+<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 
+exporter requires that endpoint(s) are configured. A common mechanism for configuring endpoints is 
+via environment variables. 
+
+This demo uses an Elastic Cloud deployment as the destination for our observability data. From Kibana 
+running in Elastic Cloud, navigate to the observability set up guides. Select the OpenTelemetry option 
+to view the configuration details that should be supplied to the application.
+
+image::./images/elastic-cloud-opentelemetry-configuration.png[Elastic Cloud OpenTelemetry configuration]
+
+Configure environment variables for the application either in `launchSettings.json` or in the environment 
+where the application is running. 
+
+Once configured, run the application and make a request to the root endpoint. A trace will be generated 
+and exported to the OTLP endpoint.
+
+To view the traces, you can use the Elastic APM UI.
+
+image::./images/trace-sample-minimal-api.png[Minimal API request trace sample in the Elastic APM UI]

docs/index.asciidoc

@@ -1,6 +1,8 @@
 include::{asciidoc-dir}/../../shared/versions/stack/current.asciidoc[]
 include::{asciidoc-dir}/../../shared/attributes.asciidoc[]
 
-= Elastic OpenTelemetry Agent Distribution
+= Elastic OpenTelemetry Distribution
 
-Docs TODO
+include::./intro.asciidoc[]
+
+include::./getting-started.asciidoc[]

docs/intro.asciidoc

@@ -0,0 +1,20 @@
+[[introduction]]
+== Introduction
+
+The `Elastic.OpenTelemetry` package contains an Elastic distribution of the 
+https://opentelemetry.io/docs/languages/net[OpenTelemetry SDK for .NET]. A distribution 
+is a wrapper around an upstream OpenTelemetry repository with some customizations. For 
+more details about distributions in general, visit the 
+https://opentelemetry.io/docs/concepts/distributions[OpenTelemetry documentation].
+
+The Elastic distribution 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 
+collected by default. The distribution also ensures that the OTLP exporter is enabled 
+by default.
+
+The distribution includes extension methods to fully control the creation of the 
+underlying tracer and metric providers, providing a helpful set of defaults 
+to get developers up and running quickly with collecting and exporting OpenTelemetry 
+signals.

examples/Example.MinimalApi/Example.MinimalApi.csproj

@@ -0,0 +1,14 @@
+<Project Sdk="Microsoft.NET.Sdk.Web">
+
+  <PropertyGroup>
+    <TargetFramework>net8.0</TargetFramework>
+    <Nullable>enable</Nullable>
+    <ImplicitUsings>enable</ImplicitUsings>
+  </PropertyGroup>
+
+  <ItemGroup>
+    <ProjectReference Include="..\..\src\Elastic.OpenTelemetry\Elastic.OpenTelemetry.csproj" />
+    <PackageReference Include="OpenTelemetry.Instrumentation.AspNetCore" Version="1.7.0" />
+  </ItemGroup>
+
+</Project>

examples/Example.MinimalApi/Program.cs

@@ -0,0 +1,52 @@
+using System.Diagnostics;
+using Example.Api;
+using OpenTelemetry;
+using OpenTelemetry.Trace;
+
+var builder = WebApplication.CreateBuilder(args);
+
+builder.Services
+	.AddHttpClient() // Adds IHttpClientFactory
+	.AddOpenTelemetry() // Adds the OpenTelemetry SDK
+		.WithTracing(t => {
+			t.AddAspNetCoreInstrumentation(); // Configure tracing to instrument ASP.NET Core
+			t.AddSource(Api.ActivitySourceName);
+		});
+
+var app = builder.Build();
+
+app.UseHttpsRedirection();
+
+app.MapGet("/", (IHttpClientFactory httpClientFactory) => Api.HandleRoot(httpClientFactory));
+
+app.Run();
+
+namespace Example.Api
+{
+	internal static class Api
+	{
+		public static string ActivitySourceName = "CustomActivitySource";
+		private static readonly ActivitySource ActivitySource = new(ActivitySourceName);
+
+		public static async Task<IResult> HandleRoot(IHttpClientFactory httpClientFactory)
+		{
+			using var client = httpClientFactory.CreateClient();
+
+			using var activity = ActivitySource.StartActivity("DoingStuff", ActivityKind.Internal);
+			activity?.SetTag("custom-tag", "TagValue");
+
+			await Task.Delay(100);
+			var response = await client.GetAsync("http://elastic.co"); // using this URL will require 2 redirects
+			await Task.Delay(50);
+
+			if (response.StatusCode == System.Net.HttpStatusCode.OK)
+			{
+				activity?.SetStatus(ActivityStatusCode.Ok);
+				return Results.Ok();
+			}
+
+			activity?.SetStatus(ActivityStatusCode.Error);
+			return Results.StatusCode(500);
+		}
+	}
+}

examples/Example.MinimalApi/Properties/launchSettings.json

@@ -0,0 +1,44 @@
+{
+  "$schema": "http://json.schemastore.org/launchsettings.json",
+  "iisSettings": {
+    "windowsAuthentication": false,
+    "anonymousAuthentication": true,
+    "iisExpress": {
+      "applicationUrl": "http://localhost:4214",
+      "sslPort": 44348
+    }
+  },
+  "profiles": {
+    "http": {
+      "commandName": "Project",
+      "dotnetRunMessages": true,
+      "launchBrowser": true,
+      "launchUrl": "",
+      "applicationUrl": "http://localhost:5146",
+      "environmentVariables": {
+        "ASPNETCORE_ENVIRONMENT": "Development",
+        "OTEL_RESOURCE_ATTRIBUTES": "service.name=minimal-api-example"
+      }
+    },
+    "https": {
+      "commandName": "Project",
+      "dotnetRunMessages": true,
+      "launchBrowser": true,
+      "launchUrl": "",
+      "applicationUrl": "https://localhost:7140;http://localhost:5146",
+      "environmentVariables": {
+        "ASPNETCORE_ENVIRONMENT": "Development",
+        "OTEL_RESOURCE_ATTRIBUTES": "service.name=minimal-api-example"
+      }
+    },
+    "IIS Express": {
+      "commandName": "IISExpress",
+      "launchBrowser": true,
+      "launchUrl": "",
+      "environmentVariables": {
+        "ASPNETCORE_ENVIRONMENT": "Development",
+        "OTEL_RESOURCE_ATTRIBUTES": "service.name=minimal-api-example"
+      }
+    }
+  }
+}

examples/Example.MinimalApi/appsettings.Development.json

@@ -0,0 +1,8 @@
+{
+  "Logging": {
+    "LogLevel": {
+      "Default": "Information",
+      "Microsoft.AspNetCore": "Warning"
+    }
+  }
+}