[docs] Prepare docs

CONTRIBUTING.md

@@ -1,4 +1,4 @@
-# Contributing to the Elastic Distribution for OpenTelemetry Node.js
+# Contributing to the Elastic Distribution of OpenTelemetry Node.js
 
 This distribution is open source and we love to receive contributions.
 There are many ways to contribute: submitting bug reports and feature requests,

README.md

@@ -1,8 +1,9 @@
-# Elastic Distribution for OpenTelemetry Node.js
+# Elastic Distribution of OpenTelemetry Node.js
 
 This repository holds Node.js packages authored by Elastic for using
 and working with OpenTelemetry. Primarily that includes
 [`@elastic/opentelemetry-node`](./packages/opentelemetry-node), the
-Elastic Distribution for OpenTelemetry Node.js. It may also
+Elastic Distribution of OpenTelemetry Node.js. It may also
 include other Elastic-authored instrumentations or other utilities.
 
+[**Read the Elastic Distribution of OpenTelemetry Node.js docs →**](./packages/opentelemetry-node/README.md)

packages/mockotlpserver/share/k8s/README.md

@@ -95,7 +95,7 @@ Deployment config?).
 Let's run a small app in our Kubernetes cluster that uses the mockotlpserver to
 see it working. "example-app-manual/" holds a small Express-based HTTP app
 with a single `GET /ping` endpoint. There is a Kubernetes deployment config
-to instrument the app with the Elastic Distribution for OpenTelemetry Node.js
+to instrument the app with the Elastic Distribution of OpenTelemetry Node.js
 (an wrapper around the OpenTelemetry SDK).
 
 ```sh
@@ -113,7 +113,7 @@ kubectl apply -f ./deployment.yaml
 ```
 
 If this worked, then the logs for the example-app-manual pod will show the
-Elastic distribution for OpenTelemetry Node.js (`@elastic/opentelemetry-node`)
+Elastic Distribution of OpenTelemetry Node.js (`@elastic/opentelemetry-node`)
 has started, and a number of "server /ping" requests (one from "app.js"
 itself, the others from the Kubernetes deployment "livenessProbe"):
 
@@ -129,7 +129,7 @@ mockotlpserver-845f7d8489-q844c       1/1     Running   0          71m
 > [email protected] start
 > node app.js
 
-{"name":"elastic-otel-node","level":30,"preamble":true,"distroVersion":"0.1.3","env":{"os":"linux 6.6.32-linuxkit","arch":"arm64","runtime":"Node.js v18.20.4"},"msg":"start Elastic Distribution for OpenTelemetry Node.js","time":"2024-07-10T00:17:58.129Z"}
+{"name":"elastic-otel-node","level":30,"preamble":true,"distroVersion":"0.1.3","env":{"os":"linux 6.6.32-linuxkit","arch":"arm64","runtime":"Node.js v18.20.4"},"msg":"start Elastic Distribution of OpenTelemetry Node.js","time":"2024-07-10T00:17:58.129Z"}
 ...
 Listening on { address: '0.0.0.0', family: 'IPv4', port: 3000 }
 [2024-07-10T00:18:00.510Z] server /ping

packages/opentelemetry-node/CHANGELOG.md

@@ -53,5 +53,5 @@
 
 ## v0.1.0
 
-The first release of the Elastic Distribution for OpenTelemetry Node.js.
+The first release of the Elastic Distribution of OpenTelemetry Node.js.
 See [the README](https://github.com/elastic/elastic-otel-node/tree/main/packages/opentelemetry-node#readme).

packages/opentelemetry-node/NOTICE.md

@@ -1,4 +1,4 @@
-Elastic Distribution for OpenTelemetry Node.js
+Elastic Distribution of OpenTelemetry Node.js
 Copyright 2023-2024 Elasticsearch B.V.
 
 This project is licensed under the Apache License, Version 2.0 - https://www.apache.org/licenses/LICENSE-2.0

packages/opentelemetry-node/README.md

@@ -1,83 +1,46 @@
-# Elastic Distribution for OpenTelemetry Node.js
+# Elastic Distribution of OpenTelemetry Node.js
 
-This is the Elastic Distribution for OpenTelemetry Node.js (the "Distro").
-It is a light wrapper around the OpenTelemetry Node SDK that makes it easier to
-get started using OpenTelemetry in your Node.js applications, especially if you
-are using [Elastic Observability](https://www.elastic.co/observability) as your
-observability solution.
+> [!WARNING]
+> The Elastic Distribution of OpenTelemetry Node.js 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.
+>
+> We welcome your feedback! You can reach us by [opening a GitHub issue](https://github.com/elastic/elastic-otel-node/issues) or starting a discussion thread on the [Elastic Discuss forum](https://discuss.elastic.co/tags/c/observability/apm/58/nodejs).
 
+The Elastic Distribution of OpenTelemetry Node.js (EDOT Node.js) is a lightweight wrapper around the [OpenTelemetry SDK for Node.js](https://opentelemetry.io/docs/languages/js) that makes it easier to get started using OpenTelemetry in your Node.js applications, especially if you are using [Elastic Observability](https://www.elastic.co/observability) as your observability solution.
 
-# Current status
+> [!NOTE]
+> For more details about OpenTelemetry distributions in general, visit the [OpenTelemetry documentation](https://opentelemetry.io/docs/concepts/distributions).
 
-The current release is **alpha**, and not yet recommended for production use.
-We welcome your feedback! You can reach us either on the [issue tracker](https://github.com/elastic/elastic-otel-node/issues)
-or on [Elastic's Discuss forum](https://discuss.elastic.co/tags/c/observability/apm/58/nodejs).
+With EDOT Node.js you have access to all the features of the OpenTelemetry SDK for Node.js plus:
 
-Some limitations / notes:
-- We expect to support most every instrumentation included in [`@opentelemetry/auto-instrumentations-node`](https://github.com/open-telemetry/opentelemetry-js-contrib/tree/main/metapackages/auto-instrumentations-node#supported-instrumentations). However, currently only a subset is supported. See [the supported instrumentations here](./docs/supported-technologies.mdx#instrumentations).
+* Access to SDK improvements and bug fixes contributed by the Elastic team _before_ the changes are available upstream in the OpenTelemetry JavaScript repositories.
+* A single package that includes several OpenTelemetry packages as dependencies, so you only need to install and update a single package (for most use cases). This is similar to OpenTelemetry's `@opentelemetry/auto-instrumentations-node` package.
 
+<!-- I don't think we want to highlight this yet -->
+<!-- * Providing an eventual easy migration path for customers of our current non-OpenTelemetry-based [Node.js APM agent](https://github.com/elastic/apm-agent-nodejs) to this SDK may be made easier by having our own package entry point. -->
 
-# Usage
+Use EDOT Node.js to start the OpenTelemetry SDK with your Node.js application to automatically capture tracing data, performance metrics, and logs. EDOT Node.js will automatically instrument [popular modules](https://github.com/open-telemetry/opentelemetry-js-contrib/tree/main/metapackages/auto-instrumentations-node#supported-instrumentations) used by your service, and send the data to your configured observability backend using the OpenTelemetry protocol (OTLP).
 
-```sh
-# 1. install
-npm install --save @elastic/opentelemetry-node
+**Ready to try out EDOT Node.js?** Follow the step-by-step instructions in [Get started](./docs/get-started.md).
 
-# 2. configure via OTEL_ envvars, for example:
-export OTEL_EXPORTER_OTLP_ENDPOINT=https://{your-otlp-endpoint.example.com}
-export OTEL_EXPORTER_OTLP_HEADERS="Authorization={authorization-information}"
-export OTEL_SERVICE_NAME=my-service
+## Install
 
-# 3. start
-node -r @elastic/opentelemetry-node my-service.js
+```sh
+npm install --save @elastic/opentelemetry-node
 ```
 
-If using an [Elastic Observability deployment](./docs/getting-started.mdx#elastic-observability-setup)
-to which to send telemetry data, the `OTEL_EXPORTER_*` settings will look
-something like:
+## Run
 
 ```sh
-export OTEL_EXPORTER_OTLP_ENDPOINT=https://{deployment-name}.apm.{cloud-region}.cloud.es.io
-export OTEL_EXPORTER_OTLP_HEADERS="Authorization=Bearer {deployment-secret-token}"
+node -r @elastic/opentelemetry-node my-service.js
 ```
 
-The Distro will automatically instrument popular modules (see [supported instrumentations](https://github.com/open-telemetry/opentelemetry-js-contrib/tree/main/metapackages/auto-instrumentations-node#supported-instrumentations)))
-used by your service, and send trace, metrics, and logs telemetry data (using
-OTLP) to your configured observability backend.
-
-The Distro can be configured via `OTEL_*` environment variables, per the
-[OpenTelemetry Environment Variable spec](https://opentelemetry.io/docs/specs/otel/configuration/sdk-environment-variables/).
-
-See the [Getting Started guide](./docs/getting-started.mdx) for more details.
-
-
-# Documentation
-
-- [Getting Started](./docs/getting-started.mdx)
-- [Supported Technologies](./docs/supported-technologies.mdx)
-- [Metrics](./docs/metrics.mdx)
-
-
-# Why this distribution?
-
-As mentioned above, this Distro is a wrapper around the [OpenTelemetry Node
-SDK (`@opentelemetry/sdk-node`)](https://github.com/open-telemetry/opentelemetry-js/tree/main/experimental/packages/opentelemetry-sdk-node). So why the separate package?
-A few reasons:
-
-- With this separate package we hope to experiment with making it easier to get
-  started with OpenTelemetry instrumentation in Node.js services. For example,
-  `@elastic/opentelemetry-node` includes a number of OTel packages as dependencies,
-  so the user only needs to install/update a single package -- at least for the
-  default use case. This is similar to the OTel
-  `@opentelemetry/auto-instrumentations-node` package.
+## Read the docs
 
-- Having a separate package will sometimes allow us to iterate more quickly with
-  changes in SDK behavior. However, our plan is to upstream any improvements to
-  the OpenTelemetry JS repositories.
+* [Get started](./docs/get-started.md)
+* [Configure the distro](./docs/configure.md)
+* [Supported technologies](./docs/supported-technologies.md)
+* [Metrics](./docs/metrics.md)
 
-- Should it be necessary, having a separate package would allow us to more
-  quickly release a fix for a particular issue required by a customer of ours.
+## Limitations
 
-- Providing an eventual easy migration path for customers of our current
-  non-OpenTelemetry-based [Node.js APM agent](https://github.com/elastic/apm-agent-nodejs)
-  to this SDK may be made easier by having our own package entry point.
+We expect to support most every instrumentation included in [`@opentelemetry/auto-instrumentations-node`](https://github.com/open-telemetry/opentelemetry-js-contrib/tree/main/metapackages/auto-instrumentations-node#supported-instrumentations). However, currently only a subset is supported. See [the supported instrumentations here](./docs/supported-technologies.asciidoc#instrumentations).

packages/opentelemetry-node/docs/configure.md

@@ -0,0 +1,111 @@
+<!--
+Goal of this doc:
+Provide a complete reference of all available configuration options and where/how they can be set. (Any Elastic-specific configuration options are listed directly. General OpenTelemetry configuration options are linked.)
+
+Assumptions we're comfortable making about the reader:
+* They are familiar with Elastic
+* They are familiar with OpenTelemetry
+-->
+
+# Configuration
+
+Configure the Elastic Distribution of OpenTelemetry Node.js (EDOT Node.js) to send data to Elastic.
+
+<!-- ✅ How users set configuration options -->
+## Configuration method
+
+Configuration of the OpenTelemetry SDK should be performed through the
+mechanisms [documented on the OpenTelemetry website](https://opentelemetry.io/docs/languages/js/automatic/configuration/).
+EDOT Node.js can be further configured using advanced settings when you need complete control of its behavior.
+
+<!-- ✅ How -->
+EDOT Node.js is typically configured with `OTEL_*` environment variables defined by the OpenTelemetry spec.
+Environment variables are read at startup and can be used to configure EDOT Node.js.
+
+EDOT Node.js will send telemetry data via OpenTelemetry's protocol (OTLP) to the
+configured endpoint (by default it sends to <http://localhost:4317>). The
+endpoint can be changed by setting the following environment vars:
+
+* `OTEL_EXPORTER_OTLP_ENDPOINT`: The full URL of the endpoint where data will be sent.
+* `OTEL_EXPORTER_OTLP_HEADERS`: A comma-separated list of `key=value` pairs that will be added to the headers of every request. This is typically this is used for authentication information.
+
+<!-- ✅ Example -->
+For example, to send telemetry data to your Elastic Observability deployment you
+might start the application like this:
+
+```sh
+export OTEL_EXPORTER_OTLP_ENDPOINT=https://{your-otlp-endpoint.example.com}
+export OTEL_EXPORTER_OTLP_HEADERS="Authorization=Bearer {your-Elastic-secret-token}"
+export OTEL_SERVICE_NAME=my-service
+```
+
+<!-- ✅ List all available configuration options -->
+## Configuration options
+
+Because the EDOT Node.js is an extension of the [OpenTelemetry Node.js SDK](https://github.com/open-telemetry/opentelemetry-js/tree/main/experimental/packages/opentelemetry-sdk-node) and other OpenTelemetry JavaScript packages, it supports `OTEL_*` environment variables per the [OpenTelemetry Environment Variable](https://opentelemetry.io/docs/specs/otel/configuration/sdk-environment-variables/) spec.
+
+<!--
+TODO:
+Are there Elastic-specific custom configuration options
+in addition to the general OpenTelemetry SDK
+configuration options? Or are all the customizations
+"behind the scenes"?
+If not, you can delete this section.
+
+[discrete]
+[[configure-distro-options]]
+=== Elastic-specific configuration options
+
+EDOT Node.js supports the following Elastic-specific options:
+
+(List config options)
+-->
+
+<!-- ✅ List auth methods -->
+## Authentication methods
+
+When sending data to Elastic, there are two ways you can authenticate: using an APM agent key or using a secret token.
+
+### Use an APM agent key (API key)
+
+<!-- ✅ What and why -->
+[APM agent keys](https://www.elastic.co/guide/en/observability/current/apm-api-key.html) are
+used to authorize requests to an Elastic Observability endpoint.
+APM agent keys are revocable, you can have more than one of them, and
+you can add or remove them without restarting APM Server.
+
+<!-- ✅ How do you authenticate using this method? -->
+To create and manage APM Agent keys in Kibana:
+
+1. Go to **APM Settings**.
+1. Select the **Agent Keys** tab.
+
+![Kibana's APM Agent Keys section](./img/kibana-apm-agent-keys.png)
+
+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 -->
+```sh
+export OTEL_EXPORTER_OTLP_ENDPOINT=https://my-deployment.apm.us-west1.gcp.cloud.es.io
+export OTEL_EXPORTER_OTLP_HEADERS="Authorization=ApiKey TkpXUkx...dVZGQQ=="
+```
+
+### Use a secret token
+
+<!-- ✅ What and why -->
+[Secret tokens](https://elastic.co/guide/en/observability/current/apm-secret-token.html) are used to authorize
+requests to the APM Server. Both EDOT Node.js and APM Server must be configured with the same secret token for
+the request to be accepted.
+
+<!-- ✅ How do you authenticate using this method? -->
+You can find the values of these variables in Kibana's APM tutorial.
+In Kibana:
+
+1. Search for _APM Tutorial_.
+1. Scroll down to the _APM Agents_ section and select the **OpenTelemetry** tab.
+1. The appropriate values for `OTEL_EXPORTER_OTLP_ENDPOINT` and `OTEL_EXPORTER_OTLP_HEADERS` are shown there. For example:
+    ```sh
+    export OTEL_EXPORTER_OTLP_ENDPOINT=https://my-deployment.apm.us-west1.gcp.cloud.es.io
+    export OTEL_EXPORTER_OTLP_HEADERS="Authorization=Bearer P....l"
+    ```