Skip to content

Commit

Permalink
clean up code comments
Browse files Browse the repository at this point in the history
  • Loading branch information
@colleenmcginnis
colleenmcginnis committed Jul 17, 2024
1 parent bd01735 commit b31163c
Show file tree
Hide file tree
Showing 3 changed files with 37 additions and 65 deletions.
49 changes: 21 additions & 28 deletions docs/configure.asciidoc
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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]]
Expand All @@ -39,30 +39,30 @@ 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 <<configure-configuration-options>>.

// Example
// TO DO: Example

// Order of operations
// ✅ Order of operations
Environment variables always take precedence over configuration provided by the `IConfiguration`
system.

[discrete]
[[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`.

Expand All @@ -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]
Expand All @@ -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.

Expand All @@ -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:

Expand Down Expand Up @@ -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
Expand All @@ -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]
Expand Down Expand Up @@ -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.
////
Expand All @@ -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]
Expand All @@ -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?
Expand All @@ -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:
Expand Down
45 changes: 12 additions & 33 deletions docs/get-started.asciidoc
View file
Original file line number Diff line number Diff line change
Expand Up @@ -20,15 +20,15 @@ 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]
====
As an OpenTelemetry SDK, the distro supports sending data to any OpenTelemetry protocol (OTLP) endpoint (for example, an https://opentelemetry.io/docs/collector/[OpenTelemetry Collector]).
====

////
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]]
Expand All @@ -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:

Expand All @@ -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
Expand All @@ -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]]
Expand All @@ -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]]
Expand Down Expand Up @@ -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]]
Expand All @@ -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:

Expand All @@ -251,21 +244,7 @@ and exported to the OTLP endpoint.
For more information on all the available configuration options, refer to <<configure>>.

////
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]]
Expand All @@ -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]]
Expand Down
8 changes: 4 additions & 4 deletions docs/intro.asciidoc
View file
Original file line number Diff line number Diff line change
Expand Up @@ -21,16 +21,16 @@ 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:

* An easy way to instrument your application with OpenTelemetry.
* 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:

Expand All @@ -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.

Expand Down

0 comments on commit b31163c

Please sign in to comment.