From b31163c2cecb8b60b4caca39657d18d5426269b1 Mon Sep 17 00:00:00 2001 From: Colleen McGinnis Date: Wed, 17 Jul 2024 14:43:26 -0500 Subject: [PATCH] clean up code comments --- docs/configure.asciidoc | 49 +++++++++++++++++---------------------- docs/get-started.asciidoc | 45 ++++++++++------------------------- docs/intro.asciidoc | 8 +++---- 3 files changed, 37 insertions(+), 65 deletions(-) diff --git a/docs/configure.asciidoc b/docs/configure.asciidoc index 6ed1312..87aa0a2 100644 --- a/docs/configure.asciidoc +++ b/docs/configure.asciidoc @@ -19,7 +19,7 @@ include::release-status.asciidoc[] The {distro_name} ("the distro") offers a lot of flexibility... //// -How do users set configuration options? +✅ How users set configuration options //// [discrete] [[configure-methods]] @@ -39,18 +39,18 @@ You can set configuration options using a few different methods: [[configure-environment-variables]] ==== Environment variables -// What and why +// ✅ What and why The distro can be configured using environment variables. This is a cross-platform way to configure the distro and is especially useful in containerized environments. -// How +// ✅ How 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, see <>. -// Example +// TO DO: Example -// Order of operations +// ✅ Order of operations Environment variables always take precedence over configuration provided by the `IConfiguration` system. @@ -58,11 +58,11 @@ system. [[configure-iconfiguration-integration]] ==== IConfiguration integration -// What and why +// ✅ What and why In applications that use the "host" pattern, such as ASP.NET Core and worker service, the distro can be configured using the `IConfiguration` integration. -// How +// ✅ How This is done by passing an `IConfiguration` instance to the `AddElasticOpenTelemetry` extension method on the `IServiceCollection`. @@ -80,7 +80,7 @@ By default, at this stage, the configuration will be populated from the default including the `appsettings.json` file(s) and command-line arguments. You may use these sources to define the configuration for the Elastic Distribution for OpenTelemetry .NET. -// Example +// ✅ Example For example, you can define the configuration for the Elastic Distribution for OpenTelemetry .NET in the `appsettings.json` file: [source,json] @@ -95,7 +95,7 @@ For example, you can define the configuration for the Elastic Distribution for O ---- <1> This example sets the file log directory to `C:\Logs` which enables diagnostic file logging. -// Order of operations +// ✅ Order of operations Configuration from the "Elastic:OpenTelemetry" section of the `IConfiguration` instance will be bound to the `ElasticOpenTelemetryOptions` instance used to configure the Elastic distribution. @@ -106,15 +106,15 @@ https://learn.microsoft.com/en-us/aspnet/core/fundamentals/configuration[Configu [[configure-manual-configuration]] ==== Manual configuration -// What and why +// ✅ What and why In all other scenarios, configuration can be achieved manually in code. -// How +// ✅ How This is done by creating an instance of `ElasticOpenTelemetryBuilderOptions` and passing it to the `ElasticOpenTelemetryBuilder` constructor or an overload of the `AddElasticOpenTelemetry` extension method on the `IServiceCollection`. -// Example +// ✅ Example For example, in traditional console applications, you can configure the Elastic Distribution for OpenTelemetry .NET like this: @@ -147,20 +147,16 @@ setting the corresponding property. <4> Pass the `ElasticOpenTelemetryBuilderOptions` instance to the `ElasticOpenTelemetryBuilder` constructor to configure the Elastic Distribution for OpenTelemetry .NET. -// Order of operations +// TO DO: Order of operations //// -What are the available configuration options? +✅ List all available configuration options //// [discrete] [[configure-configuration-options]] === Configuration options -//// -Is this true? Is the distro a wrapper around the OpenTelemetry .NET agent -which is a wrapper around the general OpenTelemetry SDK? 🌀 -//// -Because the {distro_name} ("the distro") is a wrapper around the https://github.com/open-telemetry/opentelemetry-{language_lc}-instrumentation[OpenTelemetry {language} agent], it supports both: +Because the {distro_name} ("the distro") is an extension of the https://github.com/open-telemetry/opentelemetry-{language_lc}-instrumentation[OpenTelemetry {language} agent], it supports both: * General OpenTelemetry SDK configuration options * Elastic-specific configuration options that are only available when using the distro @@ -169,10 +165,6 @@ Because the {distro_name} ("the distro") is a wrapper around the https://github. [[configure-otel-sdk-options]] ==== OpenTelemetry SDK configuration options -//// -Is this true? Are there any options that aren't supported? -Any options that shouldn't be used? -//// The distro supports all configuration options listed in the https://opentelemetry.io/docs/languages/sdk-configuration/general/[OpenTelemetry General SDK Configuration documentation]. [discrete] @@ -275,6 +267,7 @@ Elastic defaults only for tracing and metrics, set this value to `Tracing,Metric |=== //// +TO DO: Are there multiple authentication methods when sending data to Elastic? If no, delete this section. //// @@ -288,13 +281,13 @@ When sending data to Elastic, there are two ways you can authenticate: using a s [[configure-secret-token]] ==== Use a secret token -// What is this? +// TO DO:What is this? // ?? -// Why would you choose this method? +// TO DO:Why would you choose this method? // ?? -// How do you authenticate using this method? +// TO DO:How do you authenticate using this method? // ?? [discrete] @@ -305,7 +298,7 @@ When sending data to Elastic, there are two ways you can authenticate: using a s It is also possible to authenticate to an Elastic Observability endpoint using an _APM agent key_. These are revocable API keys. -// Why would you choose this method? +// TO DO:Why would you choose this method? // ?? // How do you authenticate using this method? @@ -318,7 +311,7 @@ When using an APM Agent key, the `OTEL_EXPORTER_OTLP_HEADERS` is set using a different auth schema (`ApiKey` rather than `Bearer`). For example: //// -Code example +TO DO:Code example //// :!language: diff --git a/docs/get-started.asciidoc b/docs/get-started.asciidoc index 5a87c4f..213e9c5 100644 --- a/docs/get-started.asciidoc +++ b/docs/get-started.asciidoc @@ -20,7 +20,7 @@ include::release-status.asciidoc[] This guide shows you how to use the {distro_name} ("the distro") to instrument your {language} application and send OpenTelemetry data to an Elastic Observability deployment. //// -Is this true? +TO DO: Is this true? //// [NOTE] ==== @@ -28,7 +28,7 @@ As an OpenTelemetry SDK, the distro supports sending data to any OpenTelemetry p ==== //// -What does a user need to know and/or do before they install the distro? +✅ What the user needs to know and/or do before they install the distro //// [discrete] [[get-started-prerequisites]] @@ -55,18 +55,14 @@ This section shows how to create an https://www.elastic.co/observability[Elastic ==== //// -Other prereqs? -//// - -//// -How does a user install the distro? +✅ How to install the distro //// [discrete] [[get-started-install]] === Install //// -Step-by-step instructions +✅ Step-by-step instructions //// To get started with the Elastic OpenTelemetry Distribution for .NET, add the `Elastic.OpenTelemetry` NuGet package reference to your project file: @@ -79,7 +75,7 @@ After adding the package reference, you can start using the distro in your application. //// -Any additional info related to installation +✅ Any additional info related to installation //// [NOTE] .The Elastic distro and the OpenTelemetry SDK @@ -100,7 +96,7 @@ switch to the opinionated configuration provided by the Elastic distro. ==== //// -What does the user need to do in their application to prepare to send data Elastic? +✅ Start-to-finish operation //// [discrete] [[get-started-send-data]] @@ -123,9 +119,7 @@ and the default choice for applications created using the latest templates. ==== //// -Are there any dependencies that need to be installed in addition to the distro? -If yes, does it matter in what order dependencies are defined? -If no, delete this section. +✅ Any dependencies that need to be installed in addition to the distro //// [discrete] [[get-started-add-dependencies]] @@ -210,8 +204,7 @@ exporter requires that endpoint(s) are configured. A common mechanism for config endpoints is via environment variables. //// -What does the _minimal_ configuration / setup look like? -Are there any configuration options that are _required_? +✅ Provide _minimal_ configuration/setup //// [discrete] [[get-started-configure]] @@ -232,7 +225,7 @@ for your observability data. ==== //// -Step-by-step instructions +✅ Step-by-step instructions //// When sending data to Elastic, you can find the values of these variables in Kibana's APM setup guide: @@ -251,21 +244,7 @@ and exported to the OTLP endpoint. For more information on all the available configuration options, refer to <>. //// -Does the user need to do something after configuring the distro -for data to start being sent Elastic? -If no, delete this section. -//// -[discrete] -[[get-started-initialization]] -==== Initialize the distro - -//// -Step-by-step instructions -//// - -//// -What should they expect to see after running this? -How do they know it worked as expected? +✅ What success looks like //// [discrete] [[get-started-view-traces]] @@ -274,13 +253,13 @@ How do they know it worked as expected? To view the traces, you can use the Elastic APM UI: //// -Step-by-step instructions +TO DO: Step-by-step instructions //// image:images/trace-sample-minimal-api.png[Minimal API request trace sample in the Elastic APM UI] //// -What should they do next? +TO DO: What should they do next? //// [discrete] [[get-started-next-steps]] diff --git a/docs/intro.asciidoc b/docs/intro.asciidoc index f7fe9b9..4124372 100644 --- a/docs/intro.asciidoc +++ b/docs/intro.asciidoc @@ -21,7 +21,7 @@ Assumptions we're comfortable making about the reader: include::release-status.asciidoc[] //// -Intro +✅ Intro //// The {distro_name} ("the distro") is a {language} package that provides: @@ -29,8 +29,8 @@ The {distro_name} ("the distro") is a {language} package that provides: * Configuration defaults for best usage. //// -What is it? -Why use it? +✅ What is it? +✅ Why use it? //// A _distribution_ is a wrapper around an upstream OpenTelemetry repository with some customizations. The {distro_name} is a wrapper around the https://opentelemetry.io/docs/languages/{language_lc}[OpenTelemetry SDK for {language}] and includes the following customizations: @@ -41,7 +41,7 @@ A _distribution_ is a wrapper around an upstream OpenTelemetry repository with s NOTE: For more details about OpenTelemetry distributions in general, visit the https://opentelemetry.io/docs/concepts/distributions[OpenTelemetry documentation]. //// -How to use it? +✅ How to use it? //// Use the distro to start the OpenTelemetry SDK with your {language} application to automatically capture tracing data, performance metrics, and logs. Traces, metrics, and logs are sent to any OTLP collector you choose.