[docs] Prepare docs

packages/opentelemetry-node/README.md

@@ -14,7 +14,7 @@ We welcome your feedback! You can reach us either on the [issue tracker](https:/
 or on [Elastic's Discuss forum](https://discuss.elastic.co/tags/c/observability/apm/58/nodejs).
 
 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).
+- 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).
 
 
 # Usage
@@ -32,7 +32,7 @@ export OTEL_SERVICE_NAME=my-service
 node -r @elastic/opentelemetry-node my-service.js
 ```
 
-If using an [Elastic Observability deployment](./docs/getting-started.mdx#elastic-observability-setup)
+If using an [Elastic Observability deployment](./docs/get-started.asciidoc#elastic-observability-setup)
 to which to send telemetry data, the `OTEL_EXPORTER_*` settings will look
 something like:
 
@@ -41,21 +41,21 @@ export OTEL_EXPORTER_OTLP_ENDPOINT=https://{deployment-name}.apm.{cloud-region}.
 export OTEL_EXPORTER_OTLP_HEADERS="Authorization=Bearer {deployment-secret-token}"
 ```
 
-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)))
+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.
+See the [Getting Started guide](./docs/get-started.asciidoc) for more details.
 
 
 # Documentation
 
-- [Getting Started](./docs/getting-started.mdx)
-- [Supported Technologies](./docs/supported-technologies.mdx)
-- [Metrics](./docs/metrics.mdx)
+- [Getting Started](./docs/get-started.asciidoc)
+- [Supported Technologies](./docs/supported-technologies.asciidoc)
+- [Metrics](./docs/metrics.asciidoc)
 
 
 # Why this distribution?

packages/opentelemetry-node/docs/configure.asciidoc

@@ -0,0 +1,175 @@
+////
+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
+////
+
+[[configure]]
+== Configure
+
+:language: Node.js
+:distro_name: Elastic Distribution for OpenTelemetry {language}
+
+include::release-status.asciidoc[]
+
+////
+Intro
+////
+The {distro_name} ("the distro") offers a lot of flexibility...
+
+////
+How users set configuration options
+////
+[discrete]
+[[configure-methods]]
+=== Configuration methods
+
+Configuration of the OpenTelemetry SDK should be performed through the
+mechanisms https://opentelemetry.io/docs/languages/js/automatic/configuration/[documented on the OpenTelemetry website].
+The distro can be further configured using advanced settings when you need complete control of its behavior.
+
+////
+TO DO:
+Are there other ways to define configuration options?
+For example like in https://github.com/colleenmcginnis/elastic-otel-dotnet/blob/prep-docs/docs/configure.asciidoc#configuration-methods
+If not, we can condense this and the next section.
+////
+You can set configuration options using a few different methods:
+
+* <<configure-environment-variables,Setting environment variables>>
+
+////
+✅ Configure via env variable
+////
+[discrete]
+[[configure-environment-variables]]
+==== Environment variables
+
+// ✅ What is this method?
+The distro can be configured using environment variables.
+// TO DO:
+// Why someone would use this?
+// (Context: This is what's mentioned in the .NET distro docs.)
+This is a cross-platform way to configure the distro and is especially useful in containerized environments.
+
+// ✅ How
+The distro is typically configured with `OTEL_*` environment variables defined by the OpenTelemetry spec.
+Environment variables are read at startup and can be used to configure the Elastic distribution.
+
+The distro 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:
+
+// tag::minimal-options[]
+* `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
+<<configure-auth-methods,authentication information>>.
+// end::minimal-options[]
+
+////
+✅ Example
+////
+For example, to send telemetry data to your Elastic Observability deployment you
+might start the application like this:
+
+[source,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
+----
+
+For details of the various options available and their corresponding environment variable names,
+see <<configure-configuration-options>>.
+
+////
+TO DO: If configuration options are defined in multiple places, which takes precedence?
+////
+
+////
+List all available configuration options
+////
+[discrete]
+[[configure-configuration-options]]
+=== Configuration options
+
+Because the {distro_name} ("the distro") is an extension of the https://github.com/open-telemetry/opentelemetry-js/tree/main/experimental/packages/opentelemetry-sdk-node[OpenTelemetry {language} SDK] and other OpenTelemetry JavaScript packages, it supports `OTEL_*` environment variables per the https://opentelemetry.io/docs/specs/otel/configuration/sdk-environment-variables/[OpenTelemetry Environment Variable] spec.
+
+////
+TO DO:
+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
+
+The distro supports the following Elastic-specific options:
+
+////
+TO DO:
+List config options
+////
+
+////
+TO DO:
+Are there multiple authentication methods when sending data to Elastic?
+If no, delete this section.
+////
+[discrete]
+[[configure-auth-methods]]
+=== Authentication methods
+
+When sending data to Elastic, there are two ways you can authenticate: using a secret token or using an APM agent key.
+
+[discrete]
+[[configure-secret-token]]
+==== Use a secret token
+
+// TO DO: What is this?
+// ??
+
+// TO DO: Why would you choose this method?
+// ??
+
+// TO DO: How do you authenticate using this method?
+// ??
+
+[discrete]
+[[configure-api-key]]
+==== Use an APM agent key (API key)
+
+// ✅ What is this?
+It is also possible to authenticate to an Elastic Observability endpoint using
+an _APM agent key_. These are revocable API keys.
+
+// TO DO: Why would you choose this method?
+// ??
+
+// ✅ How do you authenticate using this method?
+To create and manage APM Agent keys in Kibana:
+
+. Go to *APM Settings*.
+. Select the *Agent Keys* tab.
+
+image::img/kibana-apm-agent-keys.png[Kibana's APM Agent Keys section]
+
+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
+[source,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=="
+----
+
+:!language:
+:!distro_name: