From 17ad1cd89e7e92b0ccb22a1e86f2bf3be601bdc5 Mon Sep 17 00:00:00 2001 From: Colleen McGinnis Date: Fri, 12 Jul 2024 16:11:32 -0500 Subject: [PATCH 01/12] convert back to asciidoc --- .../docs/configure.asciidoc | 2 + .../docs/elastic-otel-node.docnav.json | 21 --- ...tting-started.mdx => get-started.asciidoc} | 119 ++++++++------- .../opentelemetry-node/docs/index.asciidoc | 17 +++ .../opentelemetry-node/docs/intro.asciidoc | 28 ++++ .../opentelemetry-node/docs/landing-page.mdx | 25 --- .../docs/{metrics.mdx => metrics.asciidoc} | 26 ++-- .../docs/supported-technologies.asciidoc | 143 ++++++++++++++++++ .../docs/supported-technologies.mdx | 62 -------- 9 files changed, 269 insertions(+), 174 deletions(-) create mode 100644 packages/opentelemetry-node/docs/configure.asciidoc delete mode 100644 packages/opentelemetry-node/docs/elastic-otel-node.docnav.json rename packages/opentelemetry-node/docs/{getting-started.mdx => get-started.asciidoc} (51%) create mode 100644 packages/opentelemetry-node/docs/index.asciidoc create mode 100644 packages/opentelemetry-node/docs/intro.asciidoc delete mode 100644 packages/opentelemetry-node/docs/landing-page.mdx rename packages/opentelemetry-node/docs/{metrics.mdx => metrics.asciidoc} (65%) create mode 100644 packages/opentelemetry-node/docs/supported-technologies.asciidoc delete mode 100644 packages/opentelemetry-node/docs/supported-technologies.mdx diff --git a/packages/opentelemetry-node/docs/configure.asciidoc b/packages/opentelemetry-node/docs/configure.asciidoc new file mode 100644 index 00000000..018af1be --- /dev/null +++ b/packages/opentelemetry-node/docs/configure.asciidoc @@ -0,0 +1,2 @@ +[[configuration-options]] +== Configuration options \ No newline at end of file diff --git a/packages/opentelemetry-node/docs/elastic-otel-node.docnav.json b/packages/opentelemetry-node/docs/elastic-otel-node.docnav.json deleted file mode 100644 index 005c2d78..00000000 --- a/packages/opentelemetry-node/docs/elastic-otel-node.docnav.json +++ /dev/null @@ -1,21 +0,0 @@ -{ - "mission": "Node.js", - "id": "elastic-otel-node", - "landingPageId": "otelNodeLanding", - "icon": "faceHappy", - "description": "Elastic Distribution for OpenTelemetry Node.js", - "items": [ - { - "label": "Get started", - "pageId": "otelNodeGetStarted" - }, - { - "label": "Supported technologies", - "pageId": "otelNodeSupportedTech" - }, - { - "label": "Metrics", - "pageId": "otelNodeMetrics" - } - ] -} diff --git a/packages/opentelemetry-node/docs/getting-started.mdx b/packages/opentelemetry-node/docs/get-started.asciidoc similarity index 51% rename from packages/opentelemetry-node/docs/getting-started.mdx rename to packages/opentelemetry-node/docs/get-started.asciidoc index 8e477d04..d2f01a78 100644 --- a/packages/opentelemetry-node/docs/getting-started.mdx +++ b/packages/opentelemetry-node/docs/get-started.asciidoc @@ -1,121 +1,130 @@ ---- -id: otelNodeGetStarted -slug: /otel-nodejs/get-started -title: Get started ---- +[[get-started]] +== Get started -This getting started guide will show how to use the Elastic Distribution for OpenTelemetry Node.js (the "Distro") to instrument your Node.js application and send OpenTelemetry data to an Elastic Observability deployment. Note, however, that as an OpenTelemetry SDK, it supports sending data to any OTLP endpoint, e.g. an [OpenTelemetry Collector](https://opentelemetry.io/docs/collector/). +This getting started guide will show how to use the Elastic Distribution for OpenTelemetry Node.js (the "Distro") to instrument your Node.js application and send OpenTelemetry data to an Elastic Observability deployment. Note, however, that as an OpenTelemetry SDK, it supports sending data to any OTLP endpoint, e.g. an https://opentelemetry.io/docs/collector/[OpenTelemetry Collector]. -## Installation +[discrete] +[[get-started-install]] +=== Installation -```sh +[source,sh] +---- npm install --save @elastic/opentelemetry-node -``` +---- The Distro is a single package that includes all the OpenTelemetry JS packages that are needed for most cases. -{/* TODO: refer to advanced section of "start the SDK" when we have that doc. */} +// TODO: refer to advanced section of "start the SDK" when we have that doc. -## Configuration +[discrete] +[[get-started-configuration]] +=== Configuration -The Distro is a wrapper around the [OpenTelemetry Node.js SDK](https://github.com/open-telemetry/opentelemetry-js/tree/main/experimental/packages/opentelemetry-sdk-node) +The Distro is a wrapper around the https://github.com/open-telemetry/opentelemetry-js/tree/main/experimental/packages/opentelemetry-sdk-node[OpenTelemetry Node.js SDK] and other OpenTelemetry JS packages. It is typically configured with `OTEL_*` environment variables defined by the OpenTelemetry spec. The most common configuration settings are `OTEL_EXPORTER_OTLP_*` to set the endpoint for sending data and `OTEL_SERVICE_NAME` to identify your service. The Distro will send telemetry data via OpenTelemetry's protocol (OTLP) to the -configured endpoint (by default it sends to \< http://localhost:4317 \>). 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`: full URL of the endpoint where to send the data -- `OTEL_EXPORTER_OTLP_HEADERS`: Comma-separated list of `key=value` pairs which - will be added to the headers of every request. Typically this is used for - authentication information. +* `OTEL_EXPORTER_OTLP_ENDPOINT`: full URL of the endpoint where to send the data +* `OTEL_EXPORTER_OTLP_HEADERS`: Comma-separated list of `key=value` pairs which +will be added to the headers of every request. Typically this is used for +authentication information. For example, to send telemetry data to your Elastic Observability deployment you might start the application like this: -```sh +[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 -``` +---- If you don't have an Elastic Observability deployment or don't have the -endpoint and auth data for your deployment, see the [Elastic Observability setup](#elastic-observability-setup) +endpoint and auth data for your deployment, see the <> section below. -See the [OpenTelemetry Environment Variable spec](https://opentelemetry.io/docs/specs/otel/configuration/sdk-environment-variables/) for other available configuration settings. +See the https://opentelemetry.io/docs/specs/otel/configuration/sdk-environment-variables/[OpenTelemetry Environment Variable spec] for other available configuration settings. -## Initialization +[discrete] +[[get-started-initialization]] +=== Initialization For the Distro to automatically instrument modules used by your Node.js service, it must be started before your service code `require`s its dependencies -- e.g. before `express`, `http`, etc. are loaded. The recommended way to get the Distro started is by using the `-r, --require` Node.js -[CLI option](https://nodejs.org/api/cli.html#-r---require-module). +https://nodejs.org/api/cli.html#-r---require-module[CLI option]. -```sh +[source,sh] +---- node --require @elastic/opentelemetry-node my-service.js -``` +---- -The Distro will automatically instrument popular modules (see [supported instrumentations](./supported-technologies.md#instrumentations)) +The Distro will automatically instrument popular modules (see <>) used by your service, and send traces, metrics, and logs telemetry data (using OTLP) to your configured observability backend. -{/* TODO: link to a reference section on other ways to start the Distro once we have those docs. */} +// TODO: link to a reference section on other ways to start the Distro once we have those docs. - -## Elastic Observability setup +[discrete] +[[get-started-elastic-observability-setup]] +=== Elastic Observability setup You'll need somewhere to send the gathered OpenTelemetry data, so it can be viewed and analyzed. The `@elastic/opentelemetry-node` package supports sending to any OTLP endpoint (e.g. an OpenTelemetry collector instance). This section -shows how to create an [Elastic Observability](https://www.elastic.co/observability) +shows how to create an https://www.elastic.co/observability[Elastic Observability] cloud deployment and get the data you need to configure the Distro to send data to it. -1. Register at [cloud.elastic.co](https://cloud.elastic.co/registration), if you haven't already. This supports starting **free trial**. - -2. After registering, click "Create deployment" at ``. Once that is created, click "Open" to visit your Kibana home page, e.g. `https://{DEPLOYMENT_NAME}.kb.{REGION}.cloud.es.io/app/home#/getting_started`. - +. Register at https://cloud.elastic.co/registration[cloud.elastic.co], if you haven't already. This supports starting **free trial**. +. After registering, click "Create deployment" at ``. Once that is created, click "Open" to visit your Kibana home page, e.g. `https://{DEPLOYMENT_NAME}.kb.{REGION}.cloud.es.io/app/home#/getting_started`. ++ To configure the Distro you'll need the deployment's OTLP endpoint and authorization data to set the appropriate `OTLP_*` environment variables. You can find these in Kibana's APM tutorial. ++ +image::img/otlp-endpoint-settings.png[Kibana's APM tutorial showing OTel settings] + +. In Kibana: +** Search for "APM Tutorial", +** Scroll down to the "APM Agents" section and select the "OpenTelemetry" tab, +** The appropriate values for `OTEL_EXPORTER_OTLP_ENDPOINT` and +`OTEL_EXPORTER_OTLP_HEADERS` are shown there. ++ +For example: ++ +[source,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" +---- -![Kibana's APM tutorial showing OTel settings](./img/otlp-endpoint-settings.png) - -3. In Kibana: - - - search for "APM Tutorial", - - scroll down to the "APM Agents" section and select the "OpenTelemetry" tab, - - the appropriate values for `OTEL_EXPORTER_OTLP_ENDPOINT` and - `OTEL_EXPORTER_OTLP_HEADERS` are shown there. - - For example: - - ``` - export OTEL_EXPORTER_OTLP_ENDPOINT=https://my-deployment.apm.us-west1.gcp.cloud.es.io - export OTEL_EXPORTER_OTLP_HEADERS="Authorization=Bearer P....l" - ``` - -Use these environment variables in the [Configuration](#configuration) step +Use these environment variables in the <> step above to configure the Distro. -### Authenticate using an APM Agent key (API key) +[discrete] +[[get-started-api-key]] +==== Authenticate using an APM Agent key (API key) It is also possible to authenticate to an Elastic Observability endpoint using an "APM Agent key". These are revocable API keys. To create and manage APM Agent keys, see the "Agent Keys" tab in "APM Settings" in Kibana. -![Kibana's APM Agent Keys section](./img/kibana-apm-agent-keys.png) +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: -``` +[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==" -``` +---- diff --git a/packages/opentelemetry-node/docs/index.asciidoc b/packages/opentelemetry-node/docs/index.asciidoc new file mode 100644 index 00000000..53550b98 --- /dev/null +++ b/packages/opentelemetry-node/docs/index.asciidoc @@ -0,0 +1,17 @@ +include::{asciidoc-dir}/../../shared/versions/stack/current.asciidoc[] +include::{asciidoc-dir}/../../shared/attributes.asciidoc[] + +ifdef::env-github[] +NOTE: For the best reading experience, +please view this documentation at https://www.elastic.co/guide/en/apm/open-telemetry/nodejs[elastic.co] +endif::[] + += Elastic Distribution for OpenTelemetry Node.js + +ifndef::env-github[] +include::./intro.asciidoc[] +include::./get-started.asciidoc[] +include::./configure.asciidoc[] +include::./supported-technologies.asciidoc[] +include::./metrics.asciidoc[] +endif::[] diff --git a/packages/opentelemetry-node/docs/intro.asciidoc b/packages/opentelemetry-node/docs/intro.asciidoc new file mode 100644 index 00000000..04128858 --- /dev/null +++ b/packages/opentelemetry-node/docs/intro.asciidoc @@ -0,0 +1,28 @@ +[[intro]] +== Elastic Distribution for OpenTelemetry Node.js + +++++ +Introduction +++++ + +[WARNING] +.Alpha release +==== +This project 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 https://github.com/elastic/elastic-otel-node/issues[opening an issue] or starting a discussion thread on the https://discuss.elastic.co/tags/c/observability/apm/58/nodejs[Elastic Discuss forum]. +==== + +The Elastic Distribution for OpenTelemetry Node.js (the "Distro") is a Node.js +package that provides: + +* an easy way to instrument your application with OpenTelemetry, and +* configuration defaults for best usage. + +Use the Distro to start the OpenTelemetry SDK with your Node.js application to automatically +capture tracing data, performance metrics, and logs. Traces, metrics, and logs are sent +to any OTLP collector you choose. Use an https://www.elastic.co/observability[Elastic Observability] +deployment -- hosted in Elastic's cloud or on-premises -- to monitor your applications, create alerts, +and quickly identify root causes of service issues. diff --git a/packages/opentelemetry-node/docs/landing-page.mdx b/packages/opentelemetry-node/docs/landing-page.mdx deleted file mode 100644 index aaee9c96..00000000 --- a/packages/opentelemetry-node/docs/landing-page.mdx +++ /dev/null @@ -1,25 +0,0 @@ ---- -id: otelNodeLanding -slug: /otel-nodejs/landing-page -title: Elastic Distribution for OpenTelemetry Node.js ---- - - - This project 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 an 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 for OpenTelemetry Node.js (the "Distro") is a Node.js -package that provides: - -- an easy way to instrument your application with OpenTelemetry, and -- configuration defaults for best usage. - -Use the Distro to start the OpenTelemetry SDK with your Node.js application to automatically -capture tracing data, performance metrics, and logs. Traces, metrics, and logs are sent -to any OTLP collector you choose. Use an [Elastic Observability](https://www.elastic.co/observability) -deployment -- hosted in Elastic's cloud or on-premises -- to monitor your applications, create alerts, -and quickly identify root causes of service issues. diff --git a/packages/opentelemetry-node/docs/metrics.mdx b/packages/opentelemetry-node/docs/metrics.asciidoc similarity index 65% rename from packages/opentelemetry-node/docs/metrics.mdx rename to packages/opentelemetry-node/docs/metrics.asciidoc index 643eafd8..fa472208 100644 --- a/packages/opentelemetry-node/docs/metrics.mdx +++ b/packages/opentelemetry-node/docs/metrics.asciidoc @@ -1,30 +1,34 @@ ---- -id: otelNodeMetrics -slug: /otel-nodejs/metrics -title: Metrics ---- +[[metrics]] +== Metrics -## Enabled by default +[discrete] +[[metrics-enabled-by-default]] +=== Enabled by default In this distribution metrics are enabled by default and sent to the endpoint configured by you. If you wish to disable metrics you can by setting the env variable `ELASTIC_OTEL_METRICS_DISABLED` to the string `true`. -```sh +[source,sh] +---- export ELASTIC_APM_SERVER_URL="https://apm-server-host.co" export ELASTIC_APM_SECRET_TOKEN="secret_token" export OTEL_EXPORTER_OTLP_ENDPOINT="${ELASTIC_APM_SERVER_URL}" export OTEL_EXPORTER_OTLP_HEADERS="Authorization=Bearer ${ELASTIC_APM_SECRET_TOKEN}" export ELASTIC_OTEL_METRICS_DISABLED=true node -r @elastic/opentelemetry-node/start.js my-app.js -``` +---- -## Advanced Configuration +[discrete] +[[metrics-advanced-configuration]] +=== Advanced Configuration You can tune how often metrics data is exported to the endpoint and the max time -to export data you can use the env vars already defined in [the spec](https://opentelemetry.io/docs/specs/otel/configuration/sdk-environment-variables/#periodic-exporting-metricreader). +to export data you can use the env vars already defined in https://opentelemetry.io/docs/specs/otel/configuration/sdk-environment-variables/#periodic-exporting-metricreader[the spec]. -## Host metrics +[discrete] +[[metrics-host-metrics]] +=== Host metrics The Elastic Distribution for OpenTelemetry Node.js also gathers metrics from the host machine with `@opentelemetry/host-metrics` pacakge. diff --git a/packages/opentelemetry-node/docs/supported-technologies.asciidoc b/packages/opentelemetry-node/docs/supported-technologies.asciidoc new file mode 100644 index 00000000..45aa6490 --- /dev/null +++ b/packages/opentelemetry-node/docs/supported-technologies.asciidoc @@ -0,0 +1,143 @@ +[[supported-technologies]] +== Supported Technologies + +[discrete] +[[supported-technologies-elastic-stack-versions]] +=== Elastic stack versions + +The Elastic Distribution for OpenTelemetry Node.js (the "Distro") sends data +via OpenTelemetry protocol (OTLP). Since version 7.14, Elastic Observability +https://www.elastic.co/blog/native-opentelemetry-support-in-elastic-observability[supports OTLP natively]. + +Note that OpenTelemetry support is being improved in the 8.x versions of the +Elastic stack, so it is strongly recommended to be using a recent 8.x version. + +[discrete] +[[supported-technologies-nodejs-versions]] +=== Node.js versions + +The Elastic Distribution for OpenTelemety Node.js supports Node.js v14 and later. +This follows from the https://github.com/open-telemetry/opentelemetry-js#supported-runtimes[OpenTelemetry JS supported runtimes]. + +[discrete] +[[supported-technologies-instrumentations]] +=== Instrumentations + +[%header] +|=== +| Name | Packages instrumented | Reference + +| `@opentelemetry/instrumentation-aws-sdk` +| `aws-sdk` v2 and `@aws-sdk/client-*` v3 +| https://github.com/open-telemetry/opentelemetry-js-contrib/tree/main/plugins/node/opentelemetry-instrumentation-aws-sdk#readme[README] + +| `@opentelemetry/instrumentation-bunyan` +| `bunyan` version range `^1.0.0` +| https://github.com/open-telemetry/opentelemetry-js-contrib/tree/main/plugins/node/opentelemetry-instrumentation-bunyan#readme[README] + +| `@opentelemetry/instrumentation-express` +| `express` version range `^4.0.0` +| https://github.com/open-telemetry/opentelemetry-js-contrib/tree/main/plugins/node/opentelemetry-instrumentation-express#readme[README] + +| `@opentelemetry/instrumentation-fastify` +| `fastify` version range `>=3 <5` +| https://github.com/open-telemetry/opentelemetry-js-contrib/tree/main/plugins/node/opentelemetry-instrumentation-fastify#readme[README] + +| `@opentelemetry/instrumentation-generic-pool` +| `generic-pool` version range `2 - 2.3, ^2.4, >=3` +| https://github.com/open-telemetry/opentelemetry-js-contrib/tree/main/plugins/node/opentelemetry-instrumentation-generic-pool#readme[README] + +| `@opentelemetry/instrumentation-grpc` +| `@grpc/grpc-js` version range `^1.0.0` +| https://github.com/open-telemetry/opentelemetry-js/tree/main/experimental/packages/opentelemetry-instrumentation-grpc#readme[README] + +| `@opentelemetry/instrumentation-hapi` +| `@hapi/hapi >=17.0.0 <21` +| https://github.com/open-telemetry/opentelemetry-js-contrib/tree/main/plugins/node/opentelemetry-instrumentation-hapi#readme[README] + +| `@opentelemetry/instrumentation-http` +| `http` module for Node.js `>=14` +| https://github.com/open-telemetry/opentelemetry-js/tree/main/experimental/packages/opentelemetry-instrumentation-http#readme[README] + +| `@opentelemetry/instrumentation-ioredis` +| `ioredis` version range `>=2 <6` +| https://github.com/open-telemetry/opentelemetry-js-contrib/tree/main/plugins/node/opentelemetry-instrumentation-ioredis#readme[README] + +| `@opentelemetry/instrumentation-knex` +| `knex` version range `>=0.10.0` +| https://github.com/open-telemetry/opentelemetry-js-contrib/tree/main/plugins/node/opentelemetry-instrumentation-knex#readme[README] + +| `@opentelemetry/instrumentation-koa` +| `koa` version range `^2.0.0` +| https://github.com/open-telemetry/opentelemetry-js-contrib/tree/main/plugins/node/opentelemetry-instrumentation-koa#readme[README] + +| `@opentelemetry/instrumentation-lru-memoizer` +| `lru-memoizer` version range `>=1.3 <3` +| https://github.com/open-telemetry/opentelemetry-js-contrib/tree/main/plugins/node/instrumentation-lru-memoizer#readme[README] + +| `@opentelemetry/instrumentation-memcached` +| `memcached` version range `>=2.2` +| https://github.com/open-telemetry/opentelemetry-js-contrib/tree/main/plugins/node/opentelemetry-instrumentation-memcached#readme[README] + +| `@opentelemetry/instrumentation-mongodb` +| `mongodb` version range `>=3.3 <7` +| https://github.com/open-telemetry/opentelemetry-js-contrib/tree/main/plugins/node/opentelemetry-instrumentation-mongodb#readme[README] + +| `@opentelemetry/instrumentation-nestjs-core` +| `@nestjs/core` version range `>=4.0.0` +| https://github.com/open-telemetry/opentelemetry-js-contrib/tree/main/plugins/node/opentelemetry-instrumentation-nestjs-core#readme[README] + +| `@opentelemetry/instrumentation-net` +| `net` module for Node.js `>=14` +| https://github.com/open-telemetry/opentelemetry-js-contrib/tree/main/plugins/node/opentelemetry-instrumentation-net#readme[README] + +| `@opentelemetry/instrumentation-pino` +| `pino` version range `>=5.14.0 <10` +| https://github.com/open-telemetry/opentelemetry-js-contrib/tree/main/plugins/node/opentelemetry-instrumentation-pino#readme[README] + +| `@opentelemetry/instrumentation-pg` +| `pg` version range `>=8 <9` +| https://github.com/open-telemetry/opentelemetry-js-contrib/tree/main/plugins/node/opentelemetry-instrumentation-pg#readme[README] + +| `@opentelemetry/instrumentation-redis-4` +| `redis` version range `^4.0.0` +| https://github.com/open-telemetry/opentelemetry-js-contrib/tree/main/plugins/node/opentelemetry-instrumentation-redis-4#readme[README] + +| `@opentelemetry/instrumentation-restify` +| `restify` version range `>=4.0.0 <12` +| https://github.com/open-telemetry/opentelemetry-js-contrib/tree/main/plugins/node/opentelemetry-instrumentation-restify#readme[README] + +| `@opentelemetry/instrumentation-router` +| `router` version range `1` +| https://github.com/open-telemetry/opentelemetry-js-contrib/tree/main/plugins/node/opentelemetry-instrumentation-router#readme[README] + +| `@opentelemetry/instrumentation-socket.io` +| `socket.io` version range `2, >=3 <5` +| https://github.com/open-telemetry/opentelemetry-js-contrib/tree/main/plugins/node/instrumentation-socket.io#readme[README] + +| `@opentelemetry/instrumentation-tedious` +| `tedious` version range `>=1.11.0 <=15` +| https://github.com/open-telemetry/opentelemetry-js-contrib/tree/main/plugins/node/instrumentation-tedious#readme[README] + +| `@opentelemetry/instrumentation-undici` +| `undici` version range `>=5.12.0` +| https://github.com/open-telemetry/opentelemetry-js-contrib/tree/main/plugins/node/instrumentation-undici#readme[README] + +| `@opentelemetry/instrumentation-winston` +| `winston` version range `>1 <4` +| https://github.com/open-telemetry/opentelemetry-js-contrib/tree/main/plugins/node/opentelemetry-instrumentation-winston#readme[README] +|=== + +[discrete] +[[supported-technologies-esm]] +=== ECMAScript Modules (ESM) + +This Distro includes *limited and experimental* support for instrumenting https://nodejs.org/api/esm.html#modules-ecmascript-modules[ECMAScript module imports], i.e. modules that are loaded via `import ...` statements and `import('...')` (dynamic import). + +// TODO: add this to the above paragraph once we have an esm.md doc: +// See the [ECMAScript module support](./esm.md) document for details. + +Limitations: + +* For Node.js `>=20.6.0 || >=18.19.0`, support for hooking `import`s is automatically enabled. For earlier versions of Node.js, you must manually enable the `import`-hook via the `--experimental-loader=@elastic/opentelemetry-node/hook.mjs` option, e.g.: `node --experimental-loader=@elastic/opentelemetry-node/hook.mjs --require=@elastic/opentelemetry-node app.js`. +* Currently only a subset of instrumentations support ESM: `express`, `ioredis`, `koa`, `pg`, `pino`. See https://github.com/open-telemetry/opentelemetry-js-contrib/issues/1942[this OpenTelemetry JS tracking issue] for progress. diff --git a/packages/opentelemetry-node/docs/supported-technologies.mdx b/packages/opentelemetry-node/docs/supported-technologies.mdx deleted file mode 100644 index d283668c..00000000 --- a/packages/opentelemetry-node/docs/supported-technologies.mdx +++ /dev/null @@ -1,62 +0,0 @@ ---- -id: otelNodeSupportedTech -slug: /otel-nodejs/supported-technologies -title: Supported Technologies ---- - -## Elastic stack versions - -The Elastic Distribution for OpenTelemetry Node.js (the "Distro") sends data -via OpenTelemetry protocol (OTLP). Since version 7.14, Elastic Observability [supports OTLP natively](https://www.elastic.co/blog/native-opentelemetry-support-in-elastic-observability). - -Note that OpenTelemetry support is being improved in the 8.x versions of the -Elastic stack, so it is strongly recommended to be using a recent 8.x version. - - -## Node.js versions - -The Elastic Distribution for OpenTelemety Node.js supports Node.js v14 and later. -This follows from the [OpenTelemetry JS supported runtimes](https://github.com/open-telemetry/opentelemetry-js#supported-runtimes). - - -## Instrumentations - -| Name | Packages instrumented | Reference | -| --------------------------------------------- | ------------------------------------------------- | --------- | -| `@opentelemetry/instrumentation-aws-sdk` | `aws-sdk` v2 and `@aws-sdk/client-*` v3 | [README](https://github.com/open-telemetry/opentelemetry-js-contrib/tree/main/plugins/node/opentelemetry-instrumentation-aws-sdk#readme) | -| `@opentelemetry/instrumentation-bunyan` | `bunyan` version range `^1.0.0` | [README](https://github.com/open-telemetry/opentelemetry-js-contrib/tree/main/plugins/node/opentelemetry-instrumentation-bunyan#readme) | -| `@opentelemetry/instrumentation-express` | `express` version range `^4.0.0` | [README](https://github.com/open-telemetry/opentelemetry-js-contrib/tree/main/plugins/node/opentelemetry-instrumentation-express#readme) | -| `@opentelemetry/instrumentation-fastify` | `fastify` version range `>=3 <5` | [README](https://github.com/open-telemetry/opentelemetry-js-contrib/tree/main/plugins/node/opentelemetry-instrumentation-fastify#readme) | -| `@opentelemetry/instrumentation-generic-pool` | `generic-pool` version range `2 - 2.3, ^2.4, >=3` | [README](https://github.com/open-telemetry/opentelemetry-js-contrib/tree/main/plugins/node/opentelemetry-instrumentation-generic-pool#readme) | -| `@opentelemetry/instrumentation-grpc` | `@grpc/grpc-js` version range `^1.0.0` | [README](https://github.com/open-telemetry/opentelemetry-js/tree/main/experimental/packages/opentelemetry-instrumentation-grpc#readme) | -| `@opentelemetry/instrumentation-hapi` | `@hapi/hapi >=17.0.0 <21` | [README](https://github.com/open-telemetry/opentelemetry-js-contrib/tree/main/plugins/node/opentelemetry-instrumentation-hapi#readme) | -| `@opentelemetry/instrumentation-http` | `http` module for Node.js `>=14` | [README](https://github.com/open-telemetry/opentelemetry-js/tree/main/experimental/packages/opentelemetry-instrumentation-http#readme) | -| `@opentelemetry/instrumentation-ioredis` | `ioredis` version range `>=2 <6` | [README](https://github.com/open-telemetry/opentelemetry-js-contrib/tree/main/plugins/node/opentelemetry-instrumentation-ioredis#readme) | -| `@opentelemetry/instrumentation-knex` | `knex` version range `>=0.10.0` | [README](https://github.com/open-telemetry/opentelemetry-js-contrib/tree/main/plugins/node/opentelemetry-instrumentation-knex#readme) | -| `@opentelemetry/instrumentation-koa` | `koa` version range `^2.0.0` | [README](https://github.com/open-telemetry/opentelemetry-js-contrib/tree/main/plugins/node/opentelemetry-instrumentation-koa#readme) | -| `@opentelemetry/instrumentation-lru-memoizer` | `lru-memoizer` version range `>=1.3 <3` | [README](https://github.com/open-telemetry/opentelemetry-js-contrib/tree/main/plugins/node/instrumentation-lru-memoizer#readme) | -| `@opentelemetry/instrumentation-memcached` | `memcached` version range `>=2.2` | [README](https://github.com/open-telemetry/opentelemetry-js-contrib/tree/main/plugins/node/opentelemetry-instrumentation-memcached#readme) | -| `@opentelemetry/instrumentation-mongodb` | `mongodb` version range `>=3.3 <7` | [README](https://github.com/open-telemetry/opentelemetry-js-contrib/tree/main/plugins/node/opentelemetry-instrumentation-mongodb#readme) | -| `@opentelemetry/instrumentation-nestjs-core` | `@nestjs/core` version range `>=4.0.0` | [README](https://github.com/open-telemetry/opentelemetry-js-contrib/tree/main/plugins/node/opentelemetry-instrumentation-nestjs-core#readme) | -| `@opentelemetry/instrumentation-net` | `net` module for Node.js `>=14` | [README](https://github.com/open-telemetry/opentelemetry-js-contrib/tree/main/plugins/node/opentelemetry-instrumentation-net#readme) | -| `@opentelemetry/instrumentation-pino` | `pino` version range `>=5.14.0 <10` | [README](https://github.com/open-telemetry/opentelemetry-js-contrib/tree/main/plugins/node/opentelemetry-instrumentation-pino#readme) | -| `@opentelemetry/instrumentation-pg` | `pg` version range `>=8 <9` | [README](https://github.com/open-telemetry/opentelemetry-js-contrib/tree/main/plugins/node/opentelemetry-instrumentation-pg#readme) | -| `@opentelemetry/instrumentation-redis-4` | `redis` version range `^4.0.0` | [README](https://github.com/open-telemetry/opentelemetry-js-contrib/tree/main/plugins/node/opentelemetry-instrumentation-redis-4#readme) | -| `@opentelemetry/instrumentation-restify` | `restify` version range `>=4.0.0 <12` | [README](https://github.com/open-telemetry/opentelemetry-js-contrib/tree/main/plugins/node/opentelemetry-instrumentation-restify#readme) | -| `@opentelemetry/instrumentation-router` | `router` version range `1` | [README](https://github.com/open-telemetry/opentelemetry-js-contrib/tree/main/plugins/node/opentelemetry-instrumentation-router#readme) | -| `@opentelemetry/instrumentation-socket.io` | `socket.io` version range `2, >=3 <5` | [README](https://github.com/open-telemetry/opentelemetry-js-contrib/tree/main/plugins/node/instrumentation-socket.io#readme) | -| `@opentelemetry/instrumentation-tedious` | `tedious` version range `>=1.11.0 <=15` | [README](https://github.com/open-telemetry/opentelemetry-js-contrib/tree/main/plugins/node/instrumentation-tedious#readme) | -| `@opentelemetry/instrumentation-undici` | `undici` version range `>=5.12.0` | [README](https://github.com/open-telemetry/opentelemetry-js-contrib/tree/main/plugins/node/instrumentation-undici#readme) | -| `@opentelemetry/instrumentation-winston` | `winston` version range `>1 <4` | [README](https://github.com/open-telemetry/opentelemetry-js-contrib/tree/main/plugins/node/opentelemetry-instrumentation-winston#readme) | - - -## ECMAScript Modules (ESM) - -This Distro includes *limited and experimental* support for instrumenting [ECMAScript module imports](https://nodejs.org/api/esm.html#modules-ecmascript-modules), i.e. modules that are loaded via `import ...` statements and `import('...')` (dynamic import). - -{/* TODO: add this to the above paragraph once we have an esm.md doc: -See the [ECMAScript module support](./esm.md) document for details. */} - -Limitations: -- For Node.js `>=20.6.0 || >=18.19.0`, support for hooking `import`s is automatically enabled. For earlier versions of Node.js, you must manually enable the `import`-hook via the `--experimental-loader=@elastic/opentelemetry-node/hook.mjs` option, e.g.: `node --experimental-loader=@elastic/opentelemetry-node/hook.mjs --require=@elastic/opentelemetry-node app.js`. -- Currently only a subset of instrumentations support ESM: `express`, `ioredis`, `koa`, `pg`, `pino`. See [this OpenTelemetry JS tracking issue](https://github.com/open-telemetry/opentelemetry-js-contrib/issues/1942) for progress. From b5ecab5c10afb9d67babbe5fb1f2d16c5985f607 Mon Sep 17 00:00:00 2001 From: Colleen McGinnis Date: Mon, 15 Jul 2024 11:23:41 -0500 Subject: [PATCH 02/12] structure initial outline --- .../docs/configure.asciidoc | 152 +++++++++++- .../docs/get-started.asciidoc | 220 +++++++++++------- .../opentelemetry-node/docs/intro.asciidoc | 57 +++-- .../opentelemetry-node/docs/metrics.asciidoc | 15 ++ .../docs/release-status.asciidoc | 9 + .../docs/supported-technologies.asciidoc | 25 +- 6 files changed, 372 insertions(+), 106 deletions(-) create mode 100644 packages/opentelemetry-node/docs/release-status.asciidoc diff --git a/packages/opentelemetry-node/docs/configure.asciidoc b/packages/opentelemetry-node/docs/configure.asciidoc index 018af1be..47233829 100644 --- a/packages/opentelemetry-node/docs/configure.asciidoc +++ b/packages/opentelemetry-node/docs/configure.asciidoc @@ -1,2 +1,150 @@ -[[configuration-options]] -== Configuration options \ No newline at end of file +//// +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 +- They know how to define Node environment variables +//// + +[[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 do 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. + +//// +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: + +* <> + +[discrete] +[[configure-environment-variables]] +==== Environment variables + +// What and why +The distro can be configured using environment variables. +// Is this true? +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 ). 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 +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 <>. + +//// +If configuration options are defined in multiple places, which takes precedence? +//// + +//// +What are the available configuration options? +//// +[discrete] +[[configure-configuration-options]] +=== Configuration options + +Because the {distro_name} ("the distro") is a wrapper around 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. + +//// +It doesn't look like there are any Elastic-specific config options. +Is that correct? +//// + +[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 + +// What is this? +// ?? + +// Why would you choose this method? +// ?? + +// 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. + +// 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: + +[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: diff --git a/packages/opentelemetry-node/docs/get-started.asciidoc b/packages/opentelemetry-node/docs/get-started.asciidoc index d2f01a78..43a0c83d 100644 --- a/packages/opentelemetry-node/docs/get-started.asciidoc +++ b/packages/opentelemetry-node/docs/get-started.asciidoc @@ -1,130 +1,184 @@ +//// +Goal of this doc: +The user is able to successfully see data from their Node application make it to the Elastic UI via the Elastic Distribution for OpenTelemetry Node.js + +Assumptions we're comfortable making about the reader: +- They know what both Elastic and OpenTelemetry are +- They have Node and NPM installed +//// + [[get-started]] == Get started -This getting started guide will show how to use the Elastic Distribution for OpenTelemetry Node.js (the "Distro") to instrument your Node.js application and send OpenTelemetry data to an Elastic Observability deployment. Note, however, that as an OpenTelemetry SDK, it supports sending data to any OTLP endpoint, e.g. an https://opentelemetry.io/docs/collector/[OpenTelemetry Collector]. +:language: Node.js +:distro_name: Elastic Distribution for OpenTelemetry {language} + +include::release-status.asciidoc[] + +This guide shows you how to use the Elastic Distribution for OpenTelemetry {language} ("the distro") to instrument your {language} application and send OpenTelemetry data to an Elastic Observability deployment. + +[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? +//// +[discrete] +[[get-started-prereq]] +=== Prerequisites + +Before getting started: + +// Familiarity with OpenTelemetry +* *Familiarize yourself with the OpenTelemetry SDK.* The distro 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 familiar with this, start with the https://opentelemetry.io/docs/languages/net[OpenTelemetry SDK documentation]. ++ +// Any dependencies (including supported versions) +* *Check your Node.js version*. +include::supported-technologies.asciidoc[tag=node-version] ++ +* *Set up Elastic Observability*. You'll need somewhere to send the gathered OpenTelemetry data, so it can be viewed and analyzed. While the `@elastic/opentelemetry-node` package supports sending to any OTLP endpoint, this doc assumes you're using Elastic Observability. You can use an existing Elastic deployment that uses version 7.14 or higher or set up a new one. ++ +[%collapsible] +.*Expand for setup instructions* +==== +This section shows how to create an https://www.elastic.co/observability[Elastic Observability] cloud deployment and get the data you need to configure the distro to send data to it. + +. Register at https://cloud.elastic.co/registration[cloud.elastic.co], if you haven't already. This supports starting **free trial**. +. After registering, click "Create deployment" at ``. Once that is created, click "Open" to visit your Kibana home page, e.g. `https://{DEPLOYMENT_NAME}.kb.{REGION}.cloud.es.io/app/home#/getting_started`. +==== + +//// +Other prereqs? +//// +//// +How does a user install the distro? +//// [discrete] [[get-started-install]] -=== Installation +=== Install + +//// +Step-by-step instructions +//// +Install the `@elastic/opentelemetry-node` package: [source,sh] ---- npm install --save @elastic/opentelemetry-node ---- -The Distro is a single package that includes all the OpenTelemetry JS packages +The distro is a single package that includes all the OpenTelemetry JS packages that are needed for most cases. // TODO: refer to advanced section of "start the SDK" when we have that doc. +//// +Any additional info related to installation +Is this relevant to the Node distro? +//// +[NOTE] +.The Elastic distro and the OpenTelemetry SDK +==== +The distro includes a transitive dependency on the OpenTelemetry SDK, so you do not _need_ to add the OpenTelemetry SDK package to your project directly. However, you _can_ explicitly add the OpenTelemetry SDK as a dependency if you want to opt into newer SDK versions. If you do this, the OpenTelemetry SDK dependency must +be defined _before_ the {distro_name} is defined. +==== + +//// +Are there any configuration options that are _required_? +What does the _minimal_ configuration / set up look like? +What should they expect to see after setting up and running the distro? +How do they know it worked as expected? +//// [discrete] -[[get-started-configuration]] -=== Configuration +[[get-started-send-data-to-Elastic]] +=== Send data to Elastic + +After installing the distro, configure and initialize it to start +sending data to Elastic. -The Distro is a wrapper around the https://github.com/open-telemetry/opentelemetry-js/tree/main/experimental/packages/opentelemetry-sdk-node[OpenTelemetry Node.js SDK] -and other OpenTelemetry JS packages. It is typically configured with `OTEL_*` -environment variables defined by the OpenTelemetry spec. The most common -configuration settings are `OTEL_EXPORTER_OTLP_*` to set the endpoint for -sending data and `OTEL_SERVICE_NAME` to identify your service. +[discrete] +[[get-started-configure]] +==== Configure the distro -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: +To configure the distro you'll need the deployment's OTLP endpoint and +authorization data to set the appropriate `OTLP_*` environment variables: -* `OTEL_EXPORTER_OTLP_ENDPOINT`: full URL of the endpoint where to send the data -* `OTEL_EXPORTER_OTLP_HEADERS`: Comma-separated list of `key=value` pairs which -will be added to the headers of every request. Typically this is used for -authentication information. +include::configure.asciidoc[tag=minimal-options] -For example, to send telemetry data to your Elastic Observability deployment you -might start the application like this: +When sending data to Elastic, you can find the values of these variables in Kibana's APM tutorial. +In Kibana: +. Search for _APM Tutorial_ +. Scroll down to the _APM Agents_ section and select the *OpenTelemetry* tab +. The appropriate values for `OTEL_EXPORTER_OTLP_ENDPOINT` and +`OTEL_EXPORTER_OTLP_HEADERS` are shown there ++ +For example: ++ [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 +export OTEL_EXPORTER_OTLP_ENDPOINT=https://my-deployment.apm.us-west1.gcp.cloud.es.io +export OTEL_EXPORTER_OTLP_HEADERS="Authorization=Bearer P....l" ---- -If you don't have an Elastic Observability deployment or don't have the -endpoint and auth data for your deployment, see the <> -section below. +image::img/otlp-endpoint-settings.png[Kibana's APM tutorial showing OTel settings] -See the https://opentelemetry.io/docs/specs/otel/configuration/sdk-environment-variables/[OpenTelemetry Environment Variable spec] for other available configuration settings. +[NOTE] +==== +For more information on authentication methods, refer to <>. +==== [discrete] [[get-started-initialization]] -=== Initialization +==== Initialize the distro + +For the distro to automatically instrument modules used by your Node.js service, +it must be started before you `require` your service code's dependencies -- +for example, before `express` or `http` are loaded. -For the Distro to automatically instrument modules used by your Node.js service, -it must be started before your service code `require`s its dependencies -- -e.g. before `express`, `http`, etc. are loaded. The recommended way to get the -Distro started is by using the `-r, --require` Node.js -https://nodejs.org/api/cli.html#-r---require-module[CLI option]. +The recommended way to get the +distro started is by using the `-r, --require` Node.js +https://nodejs.org/api/cli.html#-r---require-module[CLI option]: [source,sh] ---- node --require @elastic/opentelemetry-node my-service.js ---- -The Distro will automatically instrument popular modules (see <>) +The distro will automatically instrument popular modules (listed in <>) used by your service, and send traces, metrics, and logs telemetry data (using OTLP) to your configured observability backend. -// TODO: link to a reference section on other ways to start the Distro once we have those docs. +// TODO: link to a reference section on other ways to start the distro once we have those docs. [discrete] -[[get-started-elastic-observability-setup]] -=== Elastic Observability setup - -You'll need somewhere to send the gathered OpenTelemetry data, so it can be -viewed and analyzed. The `@elastic/opentelemetry-node` package supports sending -to any OTLP endpoint (e.g. an OpenTelemetry collector instance). This section -shows how to create an https://www.elastic.co/observability[Elastic Observability] -cloud deployment and get the data you need to configure the Distro to send -data to it. +[[get-started-asp-net-core-view-traces]] +=== View traces -. Register at https://cloud.elastic.co/registration[cloud.elastic.co], if you haven't already. This supports starting **free trial**. -. After registering, click "Create deployment" at ``. Once that is created, click "Open" to visit your Kibana home page, e.g. `https://{DEPLOYMENT_NAME}.kb.{REGION}.cloud.es.io/app/home#/getting_started`. -+ -To configure the Distro you'll need the deployment's OTLP endpoint and -authorization data to set the appropriate `OTLP_*` environment variables. You -can find these in Kibana's APM tutorial. -+ -image::img/otlp-endpoint-settings.png[Kibana's APM tutorial showing OTel settings] +To view traces, you can use the Elastic APM UI: -. In Kibana: -** Search for "APM Tutorial", -** Scroll down to the "APM Agents" section and select the "OpenTelemetry" tab, -** The appropriate values for `OTEL_EXPORTER_OTLP_ENDPOINT` and -`OTEL_EXPORTER_OTLP_HEADERS` are shown there. -+ -For example: -+ -[source,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" ----- +//// +Step-by-step instructions +//// -Use these environment variables in the <> step -above to configure the Distro. +//// +What should they do next? +//// [discrete] -[[get-started-api-key]] -==== Authenticate using an APM Agent key (API key) - -It is also possible to authenticate to an Elastic Observability endpoint using -an "APM Agent key". These are revocable API keys. To create and manage -APM Agent keys, see the "Agent Keys" tab in "APM Settings" in Kibana. - -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: - -[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==" ----- +[[get-started-next-steps]] +=== Next steps + +//// +// Examples: +// +// See all configuration options +// Learn more about interpreting data +// Other +//// + +:!language: +:!distro_name: diff --git a/packages/opentelemetry-node/docs/intro.asciidoc b/packages/opentelemetry-node/docs/intro.asciidoc index 04128858..9d7e23a6 100644 --- a/packages/opentelemetry-node/docs/intro.asciidoc +++ b/packages/opentelemetry-node/docs/intro.asciidoc @@ -1,3 +1,11 @@ +//// +Goal of this doc: +Provide all the information a user needs to determine if the product is a good enough fit for their use case to merit further exploration + +Assumptions we're comfortable making about the reader: +- Already knows what both Elastic and OpenTelemetry are +//// + [[intro]] == Elastic Distribution for OpenTelemetry Node.js @@ -5,24 +13,39 @@ Introduction ++++ -[WARNING] -.Alpha release -==== -This project 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. +:language: Node.js +:distro_name: Elastic Distribution for OpenTelemetry {language} + +include::release-status.asciidoc[] + +//// +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? +//// +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/js[OpenTelemetry SDK for {language}] and includes the following customizations: + +* Uses Elastic-specific processors that ensure optimal compatibility when exporting OpenTelemetry signal data to an Elastic backend like Elastic APM server. +* Preconfigures the collection of tracing and metrics signals, applying some opinionated defaults, such as which sources are collected by default. +* Ensures that the OpenTelemetry protocol (OTLP) exporter is enabled by default. + +NOTE: For more details about OpenTelemetry distributions in general, visit the https://opentelemetry.io/docs/concepts/distributions[OpenTelemetry documentation]. -We welcome your feedback! You can reach us by https://github.com/elastic/elastic-otel-node/issues[opening an issue] or starting a discussion thread on the https://discuss.elastic.co/tags/c/observability/apm/58/nodejs[Elastic Discuss forum]. -==== +//// +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. -The Elastic Distribution for OpenTelemetry Node.js (the "Distro") is a Node.js -package that provides: +Start with helpful defaults to begin collecting and exporting OpenTelemetry signals quickly. Then, further refine how you use the distro using extension methods that allow you to fully control the creation of the underlying tracer and metric providers. -* an easy way to instrument your application with OpenTelemetry, and -* configuration defaults for best usage. +After you start sending data to Elastic, use an {observability-guide}/index.html[Elastic Observability] deployment -- hosted on Elastic Cloud or on-premises -- to monitor your applications, create alerts, and quickly identify root causes of service issues. -Use the Distro to start the OpenTelemetry SDK with your Node.js application to automatically -capture tracing data, performance metrics, and logs. Traces, metrics, and logs are sent -to any OTLP collector you choose. Use an https://www.elastic.co/observability[Elastic Observability] -deployment -- hosted in Elastic's cloud or on-premises -- to monitor your applications, create alerts, -and quickly identify root causes of service issues. +:!language: +:!distro_name: diff --git a/packages/opentelemetry-node/docs/metrics.asciidoc b/packages/opentelemetry-node/docs/metrics.asciidoc index fa472208..48232ee7 100644 --- a/packages/opentelemetry-node/docs/metrics.asciidoc +++ b/packages/opentelemetry-node/docs/metrics.asciidoc @@ -1,6 +1,21 @@ +//// +Goal of this doc: +??? + +Assumptions we're comfortable making about the reader: +- ??? +- ??? +- ??? +//// + [[metrics]] == Metrics +:language: Node.js +:distro_name: Elastic Distribution for OpenTelemetry {language} + +include::release-status.asciidoc[] + [discrete] [[metrics-enabled-by-default]] === Enabled by default diff --git a/packages/opentelemetry-node/docs/release-status.asciidoc b/packages/opentelemetry-node/docs/release-status.asciidoc new file mode 100644 index 00000000..ba2eef62 --- /dev/null +++ b/packages/opentelemetry-node/docs/release-status.asciidoc @@ -0,0 +1,9 @@ +.Alpha release +[WARNING] +==== +The {distro_name} 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 https://github.com/elastic/elastic-otel-node/issues[opening a GitHub issue] or starting a discussion thread on the https://discuss.elastic.co/tags/c/observability/apm/58/nodejs[Elastic Discuss forum]. +==== diff --git a/packages/opentelemetry-node/docs/supported-technologies.asciidoc b/packages/opentelemetry-node/docs/supported-technologies.asciidoc index 45aa6490..5f306908 100644 --- a/packages/opentelemetry-node/docs/supported-technologies.asciidoc +++ b/packages/opentelemetry-node/docs/supported-technologies.asciidoc @@ -1,23 +1,40 @@ +//// +Goal of this doc: +??? + +Assumptions we're comfortable making about the reader: +- ??? +- ??? +- ??? +//// + [[supported-technologies]] -== Supported Technologies +== Supported technologies + +:language: Node.js +:distro_name: Elastic Distribution for OpenTelemetry {language} + +include::release-status.asciidoc[] [discrete] [[supported-technologies-elastic-stack-versions]] -=== Elastic stack versions +=== Elastic Stack versions -The Elastic Distribution for OpenTelemetry Node.js (the "Distro") sends data +The Elastic Distribution for OpenTelemetry Node.js ("the distro") sends data via OpenTelemetry protocol (OTLP). Since version 7.14, Elastic Observability https://www.elastic.co/blog/native-opentelemetry-support-in-elastic-observability[supports OTLP natively]. Note that OpenTelemetry support is being improved in the 8.x versions of the -Elastic stack, so it is strongly recommended to be using a recent 8.x version. +Elastic Stack, so it is strongly recommended to be using a recent 8.x version. [discrete] [[supported-technologies-nodejs-versions]] === Node.js versions +// tag::node-version[] The Elastic Distribution for OpenTelemety Node.js supports Node.js v14 and later. This follows from the https://github.com/open-telemetry/opentelemetry-js#supported-runtimes[OpenTelemetry JS supported runtimes]. +// end::node-version[] [discrete] [[supported-technologies-instrumentations]] From c682f1e05ea5d438d0979da320edb5b96c19cbc6 Mon Sep 17 00:00:00 2001 From: Colleen McGinnis Date: Mon, 15 Jul 2024 14:31:06 -0500 Subject: [PATCH 03/12] update readme --- packages/opentelemetry-node/README.md | 14 +++++++------- .../opentelemetry-node/docs/get-started.asciidoc | 1 + .../docs/supported-technologies.asciidoc | 2 +- 3 files changed, 9 insertions(+), 8 deletions(-) diff --git a/packages/opentelemetry-node/README.md b/packages/opentelemetry-node/README.md index 362b0b88..839aeea3 100644 --- a/packages/opentelemetry-node/README.md +++ b/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? diff --git a/packages/opentelemetry-node/docs/get-started.asciidoc b/packages/opentelemetry-node/docs/get-started.asciidoc index 43a0c83d..311a267d 100644 --- a/packages/opentelemetry-node/docs/get-started.asciidoc +++ b/packages/opentelemetry-node/docs/get-started.asciidoc @@ -40,6 +40,7 @@ include::supported-technologies.asciidoc[tag=node-version] + * *Set up Elastic Observability*. You'll need somewhere to send the gathered OpenTelemetry data, so it can be viewed and analyzed. While the `@elastic/opentelemetry-node` package supports sending to any OTLP endpoint, this doc assumes you're using Elastic Observability. You can use an existing Elastic deployment that uses version 7.14 or higher or set up a new one. + +[[elastic-observability-setup]] [%collapsible] .*Expand for setup instructions* ==== diff --git a/packages/opentelemetry-node/docs/supported-technologies.asciidoc b/packages/opentelemetry-node/docs/supported-technologies.asciidoc index 5f306908..175b15ab 100644 --- a/packages/opentelemetry-node/docs/supported-technologies.asciidoc +++ b/packages/opentelemetry-node/docs/supported-technologies.asciidoc @@ -37,7 +37,7 @@ This follows from the https://github.com/open-telemetry/opentelemetry-js#support // end::node-version[] [discrete] -[[supported-technologies-instrumentations]] +[[instrumentations]] === Instrumentations [%header] From 3d41f59f522e0bb08f191bf81d3fb1a614d1dd67 Mon Sep 17 00:00:00 2001 From: Colleen McGinnis Date: Mon, 15 Jul 2024 17:20:47 -0500 Subject: [PATCH 04/12] align with other languages --- .../docs/configure.asciidoc | 27 +++++++-- .../docs/get-started.asciidoc | 57 ++++++++++++++----- .../opentelemetry-node/docs/intro.asciidoc | 3 +- 3 files changed, 65 insertions(+), 22 deletions(-) diff --git a/packages/opentelemetry-node/docs/configure.asciidoc b/packages/opentelemetry-node/docs/configure.asciidoc index 47233829..bf839119 100644 --- a/packages/opentelemetry-node/docs/configure.asciidoc +++ b/packages/opentelemetry-node/docs/configure.asciidoc @@ -3,9 +3,8 @@ 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 -- They know how to define Node environment variables +* They are familiar with Elastic +* They are familiar with OpenTelemetry //// [[configure]] @@ -62,7 +61,7 @@ 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. +<>. // end::minimal-options[] //// @@ -95,10 +94,26 @@ What are the available configuration options? Because the {distro_name} ("the distro") is a wrapper around 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. //// -It doesn't look like there are any Elastic-specific config options. -Is that correct? +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: +//// +List config options +//// + +//// +Are there multiple authentication methods when sending data to Elastic? +If no, delete this section. +//// [discrete] [[configure-auth-methods]] === Authentication methods diff --git a/packages/opentelemetry-node/docs/get-started.asciidoc b/packages/opentelemetry-node/docs/get-started.asciidoc index 311a267d..8c9002a8 100644 --- a/packages/opentelemetry-node/docs/get-started.asciidoc +++ b/packages/opentelemetry-node/docs/get-started.asciidoc @@ -3,8 +3,9 @@ Goal of this doc: The user is able to successfully see data from their Node application make it to the Elastic UI via the Elastic Distribution for OpenTelemetry Node.js Assumptions we're comfortable making about the reader: -- They know what both Elastic and OpenTelemetry are -- They have Node and NPM installed +* They are familiar with Elastic +* They are familiar with OpenTelemetry +* They have Node and NPM installed //// [[get-started]] @@ -26,7 +27,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? //// [discrete] -[[get-started-prereq]] +[[get-started-prerequisites]] === Prerequisites Before getting started: @@ -38,7 +39,7 @@ Before getting started: * *Check your Node.js version*. include::supported-technologies.asciidoc[tag=node-version] + -* *Set up Elastic Observability*. You'll need somewhere to send the gathered OpenTelemetry data, so it can be viewed and analyzed. While the `@elastic/opentelemetry-node` package supports sending to any OTLP endpoint, this doc assumes you're using Elastic Observability. You can use an existing Elastic deployment that uses version 7.14 or higher or set up a new one. +* *Set up Elastic Observability*. You'll need somewhere to send the gathered OpenTelemetry data, so it can be viewed and analyzed. This doc assumes you're using an https://www.elastic.co/observability[Elastic Observability] cloud deployment. You can use an existing one or set up a new one. + [[elastic-observability-setup]] [%collapsible] @@ -47,7 +48,8 @@ include::supported-technologies.asciidoc[tag=node-version] This section shows how to create an https://www.elastic.co/observability[Elastic Observability] cloud deployment and get the data you need to configure the distro to send data to it. . Register at https://cloud.elastic.co/registration[cloud.elastic.co], if you haven't already. This supports starting **free trial**. -. After registering, click "Create deployment" at ``. Once that is created, click "Open" to visit your Kibana home page, e.g. `https://{DEPLOYMENT_NAME}.kb.{REGION}.cloud.es.io/app/home#/getting_started`. +. After registering, click *Create deployment* at ``. +. Once that is created, click *Open* to visit your Kibana home page, e.g. `https://{DEPLOYMENT_NAME}.kb.{REGION}.cloud.es.io/app/home#/getting_started`. ==== //// @@ -88,23 +90,39 @@ be defined _before_ the {distro_name} is defined. ==== //// -Are there any configuration options that are _required_? -What does the _minimal_ configuration / set up look like? -What should they expect to see after setting up and running the distro? -How do they know it worked as expected? +What does the user need to do in their application to prepare to send data to Elastic? //// [discrete] -[[get-started-send-data-to-Elastic]] +[[get-started-send-data]] === Send data to Elastic After installing the distro, configure and initialize it to start sending data to Elastic. +//// +Are there any dependencies that need to be installed in addition to the distro? + +I think the answer here is no because the dependencies are already defined in the +distro package so the user shouldn't have to individually install any other packages. +If that's true, delete this section. + +[discrete] +[[get-started-add-dependencies]] +==== Add dependencies +//// + +//// +What does the _minimal_ configuration / setup look like? +Are there any configuration options that are _required_? +//// [discrete] [[get-started-configure]] ==== Configure the distro -To configure the distro you'll need the deployment's OTLP endpoint and +//// +Step-by-step instructions +//// +To configure the distro, at a minimum you'll need the deployment's OTLP endpoint and authorization data to set the appropriate `OTLP_*` environment variables: include::configure.asciidoc[tag=minimal-options] @@ -127,11 +145,13 @@ export OTEL_EXPORTER_OTLP_HEADERS="Authorization=Bearer P....l" image::img/otlp-endpoint-settings.png[Kibana's APM tutorial showing OTel settings] -[NOTE] -==== -For more information on authentication methods, refer to <>. -==== +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 @@ -155,6 +175,10 @@ OTLP) to your configured observability backend. // TODO: link to a reference section on other ways to start the distro once we have those docs. +//// +What should they expect to see after setting up and running the distro? +How do they know it worked as expected? +//// [discrete] [[get-started-asp-net-core-view-traces]] === View traces @@ -165,6 +189,9 @@ To view traces, you can use the Elastic APM UI: Step-by-step instructions //// +//// +Optional: Add an image +//// //// What should they do next? diff --git a/packages/opentelemetry-node/docs/intro.asciidoc b/packages/opentelemetry-node/docs/intro.asciidoc index 9d7e23a6..36156d38 100644 --- a/packages/opentelemetry-node/docs/intro.asciidoc +++ b/packages/opentelemetry-node/docs/intro.asciidoc @@ -3,7 +3,8 @@ Goal of this doc: Provide all the information a user needs to determine if the product is a good enough fit for their use case to merit further exploration Assumptions we're comfortable making about the reader: -- Already knows what both Elastic and OpenTelemetry are +* They are familiar with Elastic +* They are familiar with OpenTelemetry //// [[intro]] From 8f85e200ec9165fc77e0f9476cd0ad9c9bab5122 Mon Sep 17 00:00:00 2001 From: Colleen McGinnis Date: Wed, 17 Jul 2024 15:07:07 -0500 Subject: [PATCH 05/12] clean up code comments, align with other distro docs --- .../docs/configure.asciidoc | 38 ++++++++++++------- .../docs/get-started.asciidoc | 37 +++++++++--------- .../opentelemetry-node/docs/intro.asciidoc | 8 ++-- 3 files changed, 45 insertions(+), 38 deletions(-) diff --git a/packages/opentelemetry-node/docs/configure.asciidoc b/packages/opentelemetry-node/docs/configure.asciidoc index bf839119..ef20c459 100644 --- a/packages/opentelemetry-node/docs/configure.asciidoc +++ b/packages/opentelemetry-node/docs/configure.asciidoc @@ -21,7 +21,7 @@ Intro The {distro_name} ("the distro") offers a lot of flexibility... //// -How do users set configuration options? +How users set configuration options //// [discrete] [[configure-methods]] @@ -32,6 +32,7 @@ mechanisms https://opentelemetry.io/docs/languages/js/automatic/configuration/[d 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. @@ -40,16 +41,21 @@ You can set configuration options using a few different methods: * <> +//// +✅ Configure via env variable +//// [discrete] [[configure-environment-variables]] ==== Environment variables -// What and why +// ✅ What is this method? The distro can be configured using environment variables. -// Is this true? +// 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? +// ✅ 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. @@ -65,7 +71,7 @@ be added to the headers of every request. This is typically this is used for // end::minimal-options[] //// -Example +✅ Example //// For example, to send telemetry data to your Elastic Observability deployment you might start the application like this: @@ -81,19 +87,20 @@ For details of the various options available and their corresponding environment see <>. //// -If configuration options are defined in multiple places, which takes precedence? +TO DO: If configuration options are defined in multiple places, which takes precedence? //// //// -What are the available configuration options? +List all available configuration options //// [discrete] [[configure-configuration-options]] === Configuration options -Because the {distro_name} ("the distro") is a wrapper around 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. +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 @@ -107,10 +114,12 @@ If not, you can delete this section. 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. //// @@ -124,27 +133,27 @@ 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] [[configure-api-key]] ==== Use an APM agent key (API key) -// What is this? +// ✅ What is this? 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? +// ✅ How do you authenticate using this method? To create and manage APM Agent keys in Kibana: . Go to *APM Settings*. @@ -155,6 +164,7 @@ 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 diff --git a/packages/opentelemetry-node/docs/get-started.asciidoc b/packages/opentelemetry-node/docs/get-started.asciidoc index 8c9002a8..1c93d919 100644 --- a/packages/opentelemetry-node/docs/get-started.asciidoc +++ b/packages/opentelemetry-node/docs/get-started.asciidoc @@ -20,11 +20,11 @@ This guide shows you how to use the Elastic Distribution for OpenTelemetry {lang [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]). +As an OpenTelemetry SDK, the distro supports sending data to any OpenTelemetry protocol (OTLP) endpoint (https://opentelemetry.io/docs/collector/[OpenTelemetry Collector]), but this guide assumes you are sending data to Elastic. ==== //// -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]] @@ -53,18 +53,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 //// Install the `@elastic/opentelemetry-node` package: @@ -76,11 +72,10 @@ npm install --save @elastic/opentelemetry-node The distro is a single package that includes all the OpenTelemetry JS packages that are needed for most cases. -// TODO: refer to advanced section of "start the SDK" when we have that doc. +// TO DO: refer to advanced section of "start the SDK" when we have that doc. //// -Any additional info related to installation -Is this relevant to the Node distro? +✅ Any additional info related to installation //// [NOTE] .The Elastic distro and the OpenTelemetry SDK @@ -90,7 +85,7 @@ be defined _before_ the {distro_name} is defined. ==== //// -What does the user need to do in their application to prepare to send data to Elastic? +✅ Start-to-finish operation //// [discrete] [[get-started-send-data]] @@ -104,7 +99,7 @@ Are there any dependencies that need to be installed in addition to the distro? I think the answer here is no because the dependencies are already defined in the distro package so the user shouldn't have to individually install any other packages. -If that's true, delete this section. +If that's true, delete this comment. [discrete] [[get-started-add-dependencies]] @@ -112,15 +107,14 @@ If that's true, delete this section. //// //// -What does the _minimal_ configuration / setup look like? -Are there any configuration options that are _required_? +✅ Provide _minimal_ configuration/setup //// [discrete] [[get-started-configure]] ==== Configure the distro //// -Step-by-step instructions +✅ Step-by-step instructions //// To configure the distro, at a minimum you'll need the deployment's OTLP endpoint and authorization data to set the appropriate `OTLP_*` environment variables: @@ -148,9 +142,7 @@ image::img/otlp-endpoint-settings.png[Kibana's APM tutorial showing OTel setting 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. +✅ Start sending data to Elastic //// [discrete] [[get-started-initialization]] @@ -160,6 +152,9 @@ For the distro to automatically instrument modules used by your Node.js service, it must be started before you `require` your service code's dependencies -- for example, before `express` or `http` are loaded. +//// +✅ Step-by-step instructions +//// The recommended way to get the distro started is by using the `-r, --require` Node.js https://nodejs.org/api/cli.html#-r---require-module[CLI option]: @@ -176,6 +171,7 @@ OTLP) to your configured observability backend. // TODO: link to a reference section on other ways to start the distro once we have those docs. //// +TO DO: What should they expect to see after setting up and running the distro? How do they know it worked as expected? //// @@ -186,7 +182,7 @@ How do they know it worked as expected? To view traces, you can use the Elastic APM UI: //// -Step-by-step instructions +TO DO: Step-by-step instructions //// //// @@ -194,6 +190,7 @@ Optional: Add an image //// //// +TO DO: What should they do next? //// [discrete] diff --git a/packages/opentelemetry-node/docs/intro.asciidoc b/packages/opentelemetry-node/docs/intro.asciidoc index 36156d38..8966da00 100644 --- a/packages/opentelemetry-node/docs/intro.asciidoc +++ b/packages/opentelemetry-node/docs/intro.asciidoc @@ -20,7 +20,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: @@ -28,8 +28,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/js[OpenTelemetry SDK for {language}] and includes the following customizations: @@ -40,7 +40,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. From ce2f949bee05b5b996cc9e8a03a7a4069d5df4b8 Mon Sep 17 00:00:00 2001 From: Colleen McGinnis Date: Thu, 18 Jul 2024 13:44:36 -0500 Subject: [PATCH 06/12] address feedback --- .../docs/configure.asciidoc | 88 ++++++--------- .../docs/get-started.asciidoc | 105 ++++++------------ .../opentelemetry-node/docs/intro.asciidoc | 15 ++- .../opentelemetry-node/docs/metrics.asciidoc | 4 +- 4 files changed, 75 insertions(+), 137 deletions(-) diff --git a/packages/opentelemetry-node/docs/configure.asciidoc b/packages/opentelemetry-node/docs/configure.asciidoc index ef20c459..e19ed736 100644 --- a/packages/opentelemetry-node/docs/configure.asciidoc +++ b/packages/opentelemetry-node/docs/configure.asciidoc @@ -16,45 +16,16 @@ Assumptions we're comfortable making about the reader: include::release-status.asciidoc[] //// -Intro -//// -The {distro_name} ("the distro") offers a lot of flexibility... - -//// -How users set configuration options +✅ How users set configuration options //// [discrete] [[configure-methods]] -=== Configuration methods +=== Configuration method 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 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. @@ -83,15 +54,8 @@ export OTEL_EXPORTER_OTLP_HEADERS="Authorization=Bearer {your-Elastic-secret-tok export OTEL_SERVICE_NAME=my-service ---- -For details of the various options available and their corresponding environment variable names, -see <>. - -//// -TO DO: If configuration options are defined in multiple places, which takes precedence? -//// - //// -List all available configuration options +✅ List all available configuration options //// [discrete] [[configure-configuration-options]] @@ -100,28 +64,24 @@ List all available 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: +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 The distro supports the following Elastic-specific options: -//// -TO DO: -List config options +(List config options) //// //// -TO DO: -Are there multiple authentication methods when sending data to Elastic? -If no, delete this section. +✅ List auth methods //// [discrete] [[configure-auth-methods]] @@ -133,14 +93,30 @@ When sending data to Elastic, there are two ways you can authenticate: using a s [[configure-secret-token]] ==== Use a secret token -// TO DO: What is this? -// ?? +// ✅ What is this +{observability-guide}/apm-secret-token.html[Secret tokens] are used to authorize requests to the APM Server. +// ✅ Why use this +Both the distro and APM Server must be configured with the same secret token for the request to be accepted. -// TO DO: Why would you choose this method? -// ?? +// ✅ How do you authenticate using this method? -// TO DO: How do you authenticate using this method? -// ?? +// tag::get-auth[] +You can find the values of these variables in Kibana's APM tutorial. +In Kibana: + +. Search for _APM Tutorial_ +. Scroll down to the _APM Agents_ section and select the *OpenTelemetry* tab +. The appropriate values for `OTEL_EXPORTER_OTLP_ENDPOINT` and +`OTEL_EXPORTER_OTLP_HEADERS` are shown there ++ +For example: ++ +[source,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" +---- +// end::get-auth[] [discrete] [[configure-api-key]] @@ -148,10 +124,10 @@ When sending data to Elastic, there are two ways you can authenticate: using a s // ✅ What is this? It is also possible to authenticate to an Elastic Observability endpoint using -an _APM agent key_. These are revocable API keys. +an {observability-guide}/apm-api-key.html[APM agent key]. These are revocable API keys. -// TO DO: Why would you choose this method? -// ?? +// TODO: Why would you choose this method? +// Use this method only if it's enabled? // ✅ How do you authenticate using this method? To create and manage APM Agent keys in Kibana: diff --git a/packages/opentelemetry-node/docs/get-started.asciidoc b/packages/opentelemetry-node/docs/get-started.asciidoc index 1c93d919..b58b54db 100644 --- a/packages/opentelemetry-node/docs/get-started.asciidoc +++ b/packages/opentelemetry-node/docs/get-started.asciidoc @@ -4,7 +4,7 @@ The user is able to successfully see data from their Node application make it to Assumptions we're comfortable making about the reader: * They are familiar with Elastic -* They are familiar with OpenTelemetry +* They are sending data to Elastic * They have Node and NPM installed //// @@ -16,7 +16,11 @@ Assumptions we're comfortable making about the reader: include::release-status.asciidoc[] -This guide shows you how to use the Elastic Distribution for OpenTelemetry {language} ("the distro") to instrument your {language} application and send OpenTelemetry data to an Elastic Observability deployment. +This guide shows you how to use the Elastic Distribution for OpenTelemetry {language} ("the distro") +to instrument your {language} application and send OpenTelemetry data to an Elastic Observability deployment. + +This doc will guide you through the minimal configuration options to get the Elastic distro set up in your application. +You do _not_ need any existing experience with OpenTelemetry to set up the Elastic distro initially. [NOTE] ==== @@ -30,17 +34,8 @@ As an OpenTelemetry SDK, the distro supports sending data to any OpenTelemetry p [[get-started-prerequisites]] === Prerequisites -Before getting started: +Before getting started, you'll need somewhere to send the gathered OpenTelemetry data, so it can be viewed and analyzed. This doc assumes you're using an https://www.elastic.co/observability[Elastic Observability] cloud deployment. You can use an existing one or set up a new one. -// Familiarity with OpenTelemetry -* *Familiarize yourself with the OpenTelemetry SDK.* The distro 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 familiar with this, start with the https://opentelemetry.io/docs/languages/net[OpenTelemetry SDK documentation]. -+ -// Any dependencies (including supported versions) -* *Check your Node.js version*. -include::supported-technologies.asciidoc[tag=node-version] -+ -* *Set up Elastic Observability*. You'll need somewhere to send the gathered OpenTelemetry data, so it can be viewed and analyzed. This doc assumes you're using an https://www.elastic.co/observability[Elastic Observability] cloud deployment. You can use an existing one or set up a new one. -+ [[elastic-observability-setup]] [%collapsible] .*Expand for setup instructions* @@ -72,17 +67,7 @@ npm install --save @elastic/opentelemetry-node The distro is a single package that includes all the OpenTelemetry JS packages that are needed for most cases. -// TO DO: refer to advanced section of "start the SDK" when we have that doc. - -//// -✅ Any additional info related to installation -//// -[NOTE] -.The Elastic distro and the OpenTelemetry SDK -==== -The distro includes a transitive dependency on the OpenTelemetry SDK, so you do not _need_ to add the OpenTelemetry SDK package to your project directly. However, you _can_ explicitly add the OpenTelemetry SDK as a dependency if you want to opt into newer SDK versions. If you do this, the OpenTelemetry SDK dependency must -be defined _before_ the {distro_name} is defined. -==== +// TODO: refer to advanced section of "start the SDK" when we have that doc. //// ✅ Start-to-finish operation @@ -94,18 +79,6 @@ be defined _before_ the {distro_name} is defined. After installing the distro, configure and initialize it to start sending data to Elastic. -//// -Are there any dependencies that need to be installed in addition to the distro? - -I think the answer here is no because the dependencies are already defined in the -distro package so the user shouldn't have to individually install any other packages. -If that's true, delete this comment. - -[discrete] -[[get-started-add-dependencies]] -==== Add dependencies -//// - //// ✅ Provide _minimal_ configuration/setup //// @@ -116,26 +89,12 @@ If that's true, delete this comment. //// ✅ Step-by-step instructions //// -To configure the distro, at a minimum you'll need the deployment's OTLP endpoint and +To configure the distro, at a minimum you'll need your Elastic Observability cloud deployment's OTLP endpoint and authorization data to set the appropriate `OTLP_*` environment variables: include::configure.asciidoc[tag=minimal-options] -When sending data to Elastic, you can find the values of these variables in Kibana's APM tutorial. -In Kibana: - -. Search for _APM Tutorial_ -. Scroll down to the _APM Agents_ section and select the *OpenTelemetry* tab -. The appropriate values for `OTEL_EXPORTER_OTLP_ENDPOINT` and -`OTEL_EXPORTER_OTLP_HEADERS` are shown there -+ -For example: -+ -[source,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" ----- +include::configure.asciidoc[tag=get-auth] image::img/otlp-endpoint-settings.png[Kibana's APM tutorial showing OTel settings] @@ -171,39 +130,41 @@ OTLP) to your configured observability backend. // TODO: link to a reference section on other ways to start the distro once we have those docs. //// -TO DO: -What should they expect to see after setting up and running the distro? -How do they know it worked as expected? +✅ What success looks like //// [discrete] -[[get-started-asp-net-core-view-traces]] -=== View traces +[[get-started-confirm]] +=== Confirm the distro is working -To view traces, you can use the Elastic APM UI: +To confirm that the distro has successfully connected to Elastic: -//// -TO DO: Step-by-step instructions -//// +. Go to *APM* → *Traces*. +. You should see the name of the service to which you just added the distro. +It can take several minutes after initializing the distro for the service to show up in this list. +. Click on the name in the list to see trace data. ++ +NOTE: There may be no trace data to visualize unless you have _used_ your application since +initializing the distro. -//// -Optional: Add an image -//// +[TIP] +==== +Alternatively, if you are able to see the stdout from your service, you can look for an "INFO" level +log message, `start Elastic Distribution for OpenTelemetry Node.js`, at startup to confirm that the +distro is up and running. +==== //// -TO DO: -What should they do next? +✅ What they should do next //// [discrete] [[get-started-next-steps]] === Next steps -//// -// Examples: -// -// See all configuration options -// Learn more about interpreting data -// Other -//// +* Learn how to configure the distro and browse all <>. +// TODO: Link to a more specific OpenTelemetry <-> Elastic Observability doc if/when it exists +* Learn more about viewing and interpreting APM data in the {observability-guide}/apm.html[Observability guide]. +* Have a question? Start a discussion thread on the https://discuss.elastic.co/tags/c/observability/apm/58/nodejs[Elastic Discuss forum]. +// TODO: Link to advanced usage when we have that doc :!language: :!distro_name: diff --git a/packages/opentelemetry-node/docs/intro.asciidoc b/packages/opentelemetry-node/docs/intro.asciidoc index 8966da00..8d6cdaf5 100644 --- a/packages/opentelemetry-node/docs/intro.asciidoc +++ b/packages/opentelemetry-node/docs/intro.asciidoc @@ -31,11 +31,11 @@ The {distro_name} ("the distro") is a {language} package that provides: ✅ 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/js[OpenTelemetry SDK for {language}] and includes the following customizations: +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/js[OpenTelemetry SDK for {language}]. With the Elastic distro you have access to all the features of the OpenTelemetry SDK for {language} plus: -* Uses Elastic-specific processors that ensure optimal compatibility when exporting OpenTelemetry signal data to an Elastic backend like Elastic APM server. -* Preconfigures the collection of tracing and metrics signals, applying some opinionated defaults, such as which sources are collected by default. -* Ensures that the OpenTelemetry protocol (OTLP) exporter is enabled by default. +* Potential 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). +// * Preconfigures the collection of tracing and metrics signals, applying some opinionated defaults, such as which sources are collected by default. NOTE: For more details about OpenTelemetry distributions in general, visit the https://opentelemetry.io/docs/concepts/distributions[OpenTelemetry documentation]. @@ -44,9 +44,12 @@ NOTE: For more details about OpenTelemetry distributions in general, visit the h //// 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. -Start with helpful defaults to begin collecting and exporting OpenTelemetry signals quickly. Then, further refine how you use the distro using extension methods that allow you to fully control the creation of the underlying tracer and metric providers. - After you start sending data to Elastic, use an {observability-guide}/index.html[Elastic Observability] deployment -- hosted on Elastic Cloud or on-premises -- to monitor your applications, create alerts, and quickly identify root causes of service issues. +//// +✅ What they should do next +//// +*Ready to try out the distro?* Follow the step-by-step instructions in <>. + :!language: :!distro_name: diff --git a/packages/opentelemetry-node/docs/metrics.asciidoc b/packages/opentelemetry-node/docs/metrics.asciidoc index 48232ee7..1bb6d9dc 100644 --- a/packages/opentelemetry-node/docs/metrics.asciidoc +++ b/packages/opentelemetry-node/docs/metrics.asciidoc @@ -26,8 +26,6 @@ variable `ELASTIC_OTEL_METRICS_DISABLED` to the string `true`. [source,sh] ---- -export ELASTIC_APM_SERVER_URL="https://apm-server-host.co" -export ELASTIC_APM_SECRET_TOKEN="secret_token" export OTEL_EXPORTER_OTLP_ENDPOINT="${ELASTIC_APM_SERVER_URL}" export OTEL_EXPORTER_OTLP_HEADERS="Authorization=Bearer ${ELASTIC_APM_SECRET_TOKEN}" export ELASTIC_OTEL_METRICS_DISABLED=true @@ -36,7 +34,7 @@ node -r @elastic/opentelemetry-node/start.js my-app.js [discrete] [[metrics-advanced-configuration]] -=== Advanced Configuration +=== Advanced configuration You can tune how often metrics data is exported to the endpoint and the max time to export data you can use the env vars already defined in https://opentelemetry.io/docs/specs/otel/configuration/sdk-environment-variables/#periodic-exporting-metricreader[the spec]. From 10b3447f059d15e56366bb822eff79c7f7484158 Mon Sep 17 00:00:00 2001 From: Colleen McGinnis Date: Thu, 1 Aug 2024 14:47:57 -0500 Subject: [PATCH 07/12] align with other distro docs --- packages/opentelemetry-node/docs/get-started.asciidoc | 5 +++-- packages/opentelemetry-node/docs/intro.asciidoc | 4 ++-- 2 files changed, 5 insertions(+), 4 deletions(-) diff --git a/packages/opentelemetry-node/docs/get-started.asciidoc b/packages/opentelemetry-node/docs/get-started.asciidoc index b58b54db..d62f15bf 100644 --- a/packages/opentelemetry-node/docs/get-started.asciidoc +++ b/packages/opentelemetry-node/docs/get-started.asciidoc @@ -21,6 +21,7 @@ to instrument your {language} application and send OpenTelemetry data to an Elas This doc will guide you through the minimal configuration options to get the Elastic distro set up in your application. You do _not_ need any existing experience with OpenTelemetry to set up the Elastic distro initially. +If you need more control over your configuration after getting set up, you can learn more in https://opentelemetry.io/docs/languages/js[OpenTelemetry SDK documentation]. [NOTE] ==== @@ -134,11 +135,11 @@ OTLP) to your configured observability backend. //// [discrete] [[get-started-confirm]] -=== Confirm the distro is working +=== Confirm that the distro is working To confirm that the distro has successfully connected to Elastic: -. Go to *APM* → *Traces*. +. Go to *Applications* → *Services*. . You should see the name of the service to which you just added the distro. It can take several minutes after initializing the distro for the service to show up in this list. . Click on the name in the list to see trace data. diff --git a/packages/opentelemetry-node/docs/intro.asciidoc b/packages/opentelemetry-node/docs/intro.asciidoc index 8d6cdaf5..f28919fb 100644 --- a/packages/opentelemetry-node/docs/intro.asciidoc +++ b/packages/opentelemetry-node/docs/intro.asciidoc @@ -31,9 +31,9 @@ The {distro_name} ("the distro") is a {language} package that provides: ✅ 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/js[OpenTelemetry SDK for {language}]. With the Elastic distro you have access to all the features of the OpenTelemetry SDK for {language} plus: +A _distribution_ is a customized version of an upstream OpenTelemetry repository with some customizations. The {distro_name} is an extension of the https://opentelemetry.io/docs/languages/js[OpenTelemetry SDK for {language}]. With the Elastic distro you have access to all the features of the OpenTelemetry SDK for {language} plus: -* Potential access to SDK improvements and bug fixes contributed by the Elastic team _before_ the changes are available upstream in the OpenTelemetry JavaScript repositories. +* 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). // * Preconfigures the collection of tracing and metrics signals, applying some opinionated defaults, such as which sources are collected by default. From 5803e0e7c3169ff298ff01a352618578471a63d7 Mon Sep 17 00:00:00 2001 From: Colleen McGinnis Date: Thu, 1 Aug 2024 15:23:44 -0500 Subject: [PATCH 08/12] translate from asciidoc to markdown --- .../docs/configure.asciidoc | 151 ---------------- packages/opentelemetry-node/docs/configure.md | 120 ++++++++++++ .../docs/get-started.asciidoc | 171 ------------------ .../opentelemetry-node/docs/get-started.md | 134 ++++++++++++++ .../opentelemetry-node/docs/index.asciidoc | 17 -- packages/opentelemetry-node/docs/index.md | 7 + .../opentelemetry-node/docs/intro.asciidoc | 55 ------ packages/opentelemetry-node/docs/intro.md | 40 ++++ .../docs/{metrics.asciidoc => metrics.md} | 34 ++-- .../docs/release-status.asciidoc | 9 - .../opentelemetry-node/docs/release-status.md | 5 + .../docs/supported-technologies.asciidoc | 160 ---------------- .../docs/supported-technologies.md | 74 ++++++++ 13 files changed, 393 insertions(+), 584 deletions(-) delete mode 100644 packages/opentelemetry-node/docs/configure.asciidoc create mode 100644 packages/opentelemetry-node/docs/configure.md delete mode 100644 packages/opentelemetry-node/docs/get-started.asciidoc create mode 100644 packages/opentelemetry-node/docs/get-started.md delete mode 100644 packages/opentelemetry-node/docs/index.asciidoc create mode 100644 packages/opentelemetry-node/docs/index.md delete mode 100644 packages/opentelemetry-node/docs/intro.asciidoc create mode 100644 packages/opentelemetry-node/docs/intro.md rename packages/opentelemetry-node/docs/{metrics.asciidoc => metrics.md} (50%) delete mode 100644 packages/opentelemetry-node/docs/release-status.asciidoc create mode 100644 packages/opentelemetry-node/docs/release-status.md delete mode 100644 packages/opentelemetry-node/docs/supported-technologies.asciidoc create mode 100644 packages/opentelemetry-node/docs/supported-technologies.md diff --git a/packages/opentelemetry-node/docs/configure.asciidoc b/packages/opentelemetry-node/docs/configure.asciidoc deleted file mode 100644 index e19ed736..00000000 --- a/packages/opentelemetry-node/docs/configure.asciidoc +++ /dev/null @@ -1,151 +0,0 @@ -//// -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[] - -//// -✅ How users set configuration options -//// -[discrete] -[[configure-methods]] -=== Configuration method - -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. - -// ✅ 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 ). 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 -<>. -// 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 ----- - -//// -✅ 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. - -//// -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 - -The distro supports the following Elastic-specific options: - -(List config options) -//// - -//// -✅ List auth methods -//// -[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 - -// ✅ What is this -{observability-guide}/apm-secret-token.html[Secret tokens] are used to authorize requests to the APM Server. -// ✅ Why use this -Both the distro and APM Server must be configured with the same secret token for the request to be accepted. - -// ✅ How do you authenticate using this method? - -// tag::get-auth[] -You can find the values of these variables in Kibana's APM tutorial. -In Kibana: - -. Search for _APM Tutorial_ -. Scroll down to the _APM Agents_ section and select the *OpenTelemetry* tab -. The appropriate values for `OTEL_EXPORTER_OTLP_ENDPOINT` and -`OTEL_EXPORTER_OTLP_HEADERS` are shown there -+ -For example: -+ -[source,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" ----- -// end::get-auth[] - -[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 {observability-guide}/apm-api-key.html[APM agent key]. These are revocable API keys. - -// TODO: Why would you choose this method? -// Use this method only if it's enabled? - -// ✅ 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: diff --git a/packages/opentelemetry-node/docs/configure.md b/packages/opentelemetry-node/docs/configure.md new file mode 100644 index 00000000..b9b5b40f --- /dev/null +++ b/packages/opentelemetry-node/docs/configure.md @@ -0,0 +1,120 @@ + + +# Configuration + +> [!WARNING] +> The Elastic Distribution for 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). + + +## 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/). +The distro can be further configured using advanced settings when you need complete control of its behavior. + + +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 ). 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. + + +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 +``` + + +## Configuration options + +Because the Elastic Distribution for OpenTelemetry Node.js ("the distro") 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. + + + + +## Authentication methods + +When sending data to Elastic, there are two ways you can authenticate: using a secret token or using an APM agent key. + +### Use a secret token + + + +[Secret tokens](https://elastic.co/guide/en/observability/current/apm-secret-token.html) are used to authorize +requests to the APM Server. Both the distro and APM Server must be configured with the same secret token for +the request to be accepted. + + + +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" + ``` + +### Use an APM agent key (API key) + + +It is also possible to authenticate to an Elastic Observability endpoint using +an [APM agent key](https://elastic.co/guide/en/observability/current/apm-api-key.html). +These are revocable API keys. + + + + +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: + + +```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==" +``` diff --git a/packages/opentelemetry-node/docs/get-started.asciidoc b/packages/opentelemetry-node/docs/get-started.asciidoc deleted file mode 100644 index d62f15bf..00000000 --- a/packages/opentelemetry-node/docs/get-started.asciidoc +++ /dev/null @@ -1,171 +0,0 @@ -//// -Goal of this doc: -The user is able to successfully see data from their Node application make it to the Elastic UI via the Elastic Distribution for OpenTelemetry Node.js - -Assumptions we're comfortable making about the reader: -* They are familiar with Elastic -* They are sending data to Elastic -* They have Node and NPM installed -//// - -[[get-started]] -== Get started - -:language: Node.js -:distro_name: Elastic Distribution for OpenTelemetry {language} - -include::release-status.asciidoc[] - -This guide shows you how to use the Elastic Distribution for OpenTelemetry {language} ("the distro") -to instrument your {language} application and send OpenTelemetry data to an Elastic Observability deployment. - -This doc will guide you through the minimal configuration options to get the Elastic distro set up in your application. -You do _not_ need any existing experience with OpenTelemetry to set up the Elastic distro initially. -If you need more control over your configuration after getting set up, you can learn more in https://opentelemetry.io/docs/languages/js[OpenTelemetry SDK documentation]. - -[NOTE] -==== -As an OpenTelemetry SDK, the distro supports sending data to any OpenTelemetry protocol (OTLP) endpoint (https://opentelemetry.io/docs/collector/[OpenTelemetry Collector]), but this guide assumes you are sending data to Elastic. -==== - -//// -✅ What the user needs to know and/or do before they install the distro -//// -[discrete] -[[get-started-prerequisites]] -=== Prerequisites - -Before getting started, you'll need somewhere to send the gathered OpenTelemetry data, so it can be viewed and analyzed. This doc assumes you're using an https://www.elastic.co/observability[Elastic Observability] cloud deployment. You can use an existing one or set up a new one. - -[[elastic-observability-setup]] -[%collapsible] -.*Expand for setup instructions* -==== -This section shows how to create an https://www.elastic.co/observability[Elastic Observability] cloud deployment and get the data you need to configure the distro to send data to it. - -. Register at https://cloud.elastic.co/registration[cloud.elastic.co], if you haven't already. This supports starting **free trial**. -. After registering, click *Create deployment* at ``. -. Once that is created, click *Open* to visit your Kibana home page, e.g. `https://{DEPLOYMENT_NAME}.kb.{REGION}.cloud.es.io/app/home#/getting_started`. -==== - -//// -✅ How to install the distro -//// -[discrete] -[[get-started-install]] -=== Install - -//// -✅ Step-by-step instructions -//// -Install the `@elastic/opentelemetry-node` package: - -[source,sh] ----- -npm install --save @elastic/opentelemetry-node ----- - -The distro is a single package that includes all the OpenTelemetry JS packages -that are needed for most cases. - -// TODO: refer to advanced section of "start the SDK" when we have that doc. - -//// -✅ Start-to-finish operation -//// -[discrete] -[[get-started-send-data]] -=== Send data to Elastic - -After installing the distro, configure and initialize it to start -sending data to Elastic. - -//// -✅ Provide _minimal_ configuration/setup -//// -[discrete] -[[get-started-configure]] -==== Configure the distro - -//// -✅ Step-by-step instructions -//// -To configure the distro, at a minimum you'll need your Elastic Observability cloud deployment's OTLP endpoint and -authorization data to set the appropriate `OTLP_*` environment variables: - -include::configure.asciidoc[tag=minimal-options] - -include::configure.asciidoc[tag=get-auth] - -image::img/otlp-endpoint-settings.png[Kibana's APM tutorial showing OTel settings] - -For more information on all the available configuration options, refer to <>. - -//// -✅ Start sending data to Elastic -//// -[discrete] -[[get-started-initialization]] -==== Initialize the distro - -For the distro to automatically instrument modules used by your Node.js service, -it must be started before you `require` your service code's dependencies -- -for example, before `express` or `http` are loaded. - -//// -✅ Step-by-step instructions -//// -The recommended way to get the -distro started is by using the `-r, --require` Node.js -https://nodejs.org/api/cli.html#-r---require-module[CLI option]: - -[source,sh] ----- -node --require @elastic/opentelemetry-node my-service.js ----- - -The distro will automatically instrument popular modules (listed in <>) -used by your service, and send traces, metrics, and logs telemetry data (using -OTLP) to your configured observability backend. - -// TODO: link to a reference section on other ways to start the distro once we have those docs. - -//// -✅ What success looks like -//// -[discrete] -[[get-started-confirm]] -=== Confirm that the distro is working - -To confirm that the distro has successfully connected to Elastic: - -. Go to *Applications* → *Services*. -. You should see the name of the service to which you just added the distro. -It can take several minutes after initializing the distro for the service to show up in this list. -. Click on the name in the list to see trace data. -+ -NOTE: There may be no trace data to visualize unless you have _used_ your application since -initializing the distro. - -[TIP] -==== -Alternatively, if you are able to see the stdout from your service, you can look for an "INFO" level -log message, `start Elastic Distribution for OpenTelemetry Node.js`, at startup to confirm that the -distro is up and running. -==== - -//// -✅ What they should do next -//// -[discrete] -[[get-started-next-steps]] -=== Next steps - -* Learn how to configure the distro and browse all <>. -// TODO: Link to a more specific OpenTelemetry <-> Elastic Observability doc if/when it exists -* Learn more about viewing and interpreting APM data in the {observability-guide}/apm.html[Observability guide]. -* Have a question? Start a discussion thread on the https://discuss.elastic.co/tags/c/observability/apm/58/nodejs[Elastic Discuss forum]. -// TODO: Link to advanced usage when we have that doc - -:!language: -:!distro_name: diff --git a/packages/opentelemetry-node/docs/get-started.md b/packages/opentelemetry-node/docs/get-started.md new file mode 100644 index 00000000..e9eee40d --- /dev/null +++ b/packages/opentelemetry-node/docs/get-started.md @@ -0,0 +1,134 @@ + + +# Get started + +> [!WARNING] +> The Elastic Distribution for 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). + +This guide shows you how to use the Elastic Distribution for OpenTelemetry Node.js ("the distro") +to instrument your Node.js application and send OpenTelemetry data to an Elastic Observability deployment. + +This doc will guide you through the minimal configuration options to get the Elastic distro set up in your application. +You do _not_ need any existing experience with OpenTelemetry to set up the Elastic distro initially. +If you need more control over your configuration after getting set up, you can learn more in [OpenTelemetry SDK documentation](https://opentelemetry.io/docs/languages/js). + +> [!NOTE] +> As an OpenTelemetry SDK, the distro supports sending data to any OpenTelemetry protocol (OTLP) endpoint ([OpenTelemetry Collector](https://opentelemetry.io/docs/collector/)), but this guide assumes you are sending data to Elastic. + + +## Prerequisites + +Before getting started, you'll need somewhere to send the gathered OpenTelemetry data, so it can be viewed and analyzed. This doc assumes you're using an [Elastic Observability](https://www.elastic.co/observability) cloud deployment. You can use an existing one or set up a new one. + +
+Expand for setup instructions + +To create your first Elastic Observability deployment: + +1. Sign up for a [free Elastic Cloud trial](https://cloud.elastic.co/registration) or sign into an existing account. +1. Go to . +1. Click **Create deployment**. +1. When the deployment is ready, click **Open** to visit your Kibana home page (for example, `https://{DEPLOYMENT_NAME}.kb.{REGION}.cloud.es.io/app/home#/getting_started`). + +
+ + +## Install + + +Install the `@elastic/opentelemetry-node` package: + +```sh +npm install --save @elastic/opentelemetry-node +``` + +The distro is a single package that includes all the OpenTelemetry JS packages +that are needed for most cases. + + + + +## Send data to Elastic + +After installing the distro, configure and initialize it to start +sending data to Elastic. + + +### Configure the distro + + +To configure the distro, at a minimum you'll need your Elastic Observability cloud deployment's OTLP endpoint and +authorization data to set the appropriate `OTLP_*` environment variables: + +* `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. + +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" + ``` + +![Kibana's APM tutorial showing OTel settings](./img/otlp-endpoint-settings.png) + +For more information on all the available configuration options, refer to [Configuration](./configure.md). + + +### Initialize the distro + +For the distro to automatically instrument modules used by your Node.js service, +it must be started before you `require` your service code's dependencies -- +for example, before `express` or `http` are loaded. + + +The recommended way to get the +distro started is by using the `-r, --require` Node.js +[CLI option](https://nodejs.org/api/cli.html#-r---require-module): + +```sh +node --require @elastic/opentelemetry-node my-service.js +``` + +The distro will automatically instrument popular modules (listed in [Supported technologies](./supported-technologies.md)) +used by your service, and send traces, metrics, and logs telemetry data (using +OTLP) to your configured observability backend. + + + + +## Confirm that the distro is working + +To confirm that the distro has successfully connected to Elastic: + +1. Go to **APM** → **Services**. +1. You should see the name of the service to which you just added the distro. It can take several minutes after initializing the distro for the service to show up in this list. +1. Click on the name in the list to see trace data. + > ![NOTE] + > There may be no trace data to visualize unless you have _used_ your application since initializing the distro. + +> [!TIP] +> Alternatively, if you are able to see the stdout from your service, you can look for an "INFO" level log message, `start Elastic Distribution for OpenTelemetry Node.js`, at startup to confirm that the distro is up and running. + + +## Next steps + +* Learn how to configure the distro and browse all [configuration options](./configure.md). +* Learn more about viewing and interpreting APM data in the [Observability guide](https://elastic.co/guide/en/observability/current/apm.html). +* Have a question? Start a discussion thread on the [Elastic Discuss forum](https://discuss.elastic.co/tags/c/observability/apm/58/nodejs). + + diff --git a/packages/opentelemetry-node/docs/index.asciidoc b/packages/opentelemetry-node/docs/index.asciidoc deleted file mode 100644 index 53550b98..00000000 --- a/packages/opentelemetry-node/docs/index.asciidoc +++ /dev/null @@ -1,17 +0,0 @@ -include::{asciidoc-dir}/../../shared/versions/stack/current.asciidoc[] -include::{asciidoc-dir}/../../shared/attributes.asciidoc[] - -ifdef::env-github[] -NOTE: For the best reading experience, -please view this documentation at https://www.elastic.co/guide/en/apm/open-telemetry/nodejs[elastic.co] -endif::[] - -= Elastic Distribution for OpenTelemetry Node.js - -ifndef::env-github[] -include::./intro.asciidoc[] -include::./get-started.asciidoc[] -include::./configure.asciidoc[] -include::./supported-technologies.asciidoc[] -include::./metrics.asciidoc[] -endif::[] diff --git a/packages/opentelemetry-node/docs/index.md b/packages/opentelemetry-node/docs/index.md new file mode 100644 index 00000000..343a4630 --- /dev/null +++ b/packages/opentelemetry-node/docs/index.md @@ -0,0 +1,7 @@ +# Elastic Distribution for OpenTelemetry .NET + +* [Introduction](./intro.md) +* [Get started](./get-started.md) +* [Configuration](./configure.md) +* [Supported technologies](./supported-technologies.md) +* [Metrics](./metrics.md) diff --git a/packages/opentelemetry-node/docs/intro.asciidoc b/packages/opentelemetry-node/docs/intro.asciidoc deleted file mode 100644 index f28919fb..00000000 --- a/packages/opentelemetry-node/docs/intro.asciidoc +++ /dev/null @@ -1,55 +0,0 @@ -//// -Goal of this doc: -Provide all the information a user needs to determine if the product is a good enough fit for their use case to merit further exploration - -Assumptions we're comfortable making about the reader: -* They are familiar with Elastic -* They are familiar with OpenTelemetry -//// - -[[intro]] -== Elastic Distribution for OpenTelemetry Node.js - -++++ -Introduction -++++ - -:language: Node.js -:distro_name: Elastic Distribution for OpenTelemetry {language} - -include::release-status.asciidoc[] - -//// -✅ 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? -//// -A _distribution_ is a customized version of an upstream OpenTelemetry repository with some customizations. The {distro_name} is an extension of the https://opentelemetry.io/docs/languages/js[OpenTelemetry SDK for {language}]. With the Elastic distro you have access to all the features of the OpenTelemetry SDK for {language} plus: - -* 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). -// * Preconfigures the collection of tracing and metrics signals, applying some opinionated defaults, such as which sources are collected by default. - -NOTE: For more details about OpenTelemetry distributions in general, visit the https://opentelemetry.io/docs/concepts/distributions[OpenTelemetry documentation]. - -//// -✅ 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. - -After you start sending data to Elastic, use an {observability-guide}/index.html[Elastic Observability] deployment -- hosted on Elastic Cloud or on-premises -- to monitor your applications, create alerts, and quickly identify root causes of service issues. - -//// -✅ What they should do next -//// -*Ready to try out the distro?* Follow the step-by-step instructions in <>. - -:!language: -:!distro_name: diff --git a/packages/opentelemetry-node/docs/intro.md b/packages/opentelemetry-node/docs/intro.md new file mode 100644 index 00000000..d4301b08 --- /dev/null +++ b/packages/opentelemetry-node/docs/intro.md @@ -0,0 +1,40 @@ + + +# Introduction + +> [!WARNING] +> The Elastic Distribution for 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 for OpenTelemetry Node.js ("the distro") is a Node.js package that provides: + +* An easy way to instrument your application with OpenTelemetry. +* Configuration defaults for best usage. + + + +A _distribution_ is a customized version of an upstream OpenTelemetry repository with some customizations. The Elastic Distribution for OpenTelemetry Node.js is an extension of the [OpenTelemetry SDK for Node.js](https://opentelemetry.io/docs/languages/js). With the Elastic distro you have access to all the features of the OpenTelemetry SDK for Node.js plus: + +* 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). + + +> [!NOTE] +> For more details about OpenTelemetry distributions in general, visit the [OpenTelemetry documentation](https://opentelemetry.io/docs/concepts/distributions). + + +Use the distro to start the OpenTelemetry SDK with your Node.js application to automatically capture tracing data, performance metrics, and logs. Traces, metrics, and logs are sent to any OTLP collector you choose. + +After you start sending data to Elastic, use an [Elastic Observability](https://www.elastic.co/guide/en/observability/current/index.html) deployment — hosted on Elastic Cloud or on-premises — to monitor your applications, create alerts, and quickly identify root causes of service issues. + + +**Ready to try out the distro?** Follow the step-by-step instructions in [Get started](./get-started.md). diff --git a/packages/opentelemetry-node/docs/metrics.asciidoc b/packages/opentelemetry-node/docs/metrics.md similarity index 50% rename from packages/opentelemetry-node/docs/metrics.asciidoc rename to packages/opentelemetry-node/docs/metrics.md index 1bb6d9dc..80e06364 100644 --- a/packages/opentelemetry-node/docs/metrics.asciidoc +++ b/packages/opentelemetry-node/docs/metrics.md @@ -1,4 +1,4 @@ -//// + -[[metrics]] -== Metrics +# Metrics -:language: Node.js -:distro_name: Elastic Distribution for OpenTelemetry {language} +> [!WARNING] +> The Elastic Distribution for 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). -include::release-status.asciidoc[] - -[discrete] -[[metrics-enabled-by-default]] -=== Enabled by default +## Enabled by default In this distribution metrics are enabled by default and sent to the endpoint configured by you. If you wish to disable metrics you can by setting the env variable `ELASTIC_OTEL_METRICS_DISABLED` to the string `true`. -[source,sh] ----- +```sh export OTEL_EXPORTER_OTLP_ENDPOINT="${ELASTIC_APM_SERVER_URL}" export OTEL_EXPORTER_OTLP_HEADERS="Authorization=Bearer ${ELASTIC_APM_SECRET_TOKEN}" export ELASTIC_OTEL_METRICS_DISABLED=true node -r @elastic/opentelemetry-node/start.js my-app.js ----- +``` -[discrete] -[[metrics-advanced-configuration]] -=== Advanced configuration +## Advanced configuration You can tune how often metrics data is exported to the endpoint and the max time -to export data you can use the env vars already defined in https://opentelemetry.io/docs/specs/otel/configuration/sdk-environment-variables/#periodic-exporting-metricreader[the spec]. +to export data you can use the env vars already defined in [the spec](https://opentelemetry.io/docs/specs/otel/configuration/sdk-environment-variables/#periodic-exporting-metricreader). -[discrete] -[[metrics-host-metrics]] -=== Host metrics +## Host metrics The Elastic Distribution for OpenTelemetry Node.js also gathers metrics from the host machine with `@opentelemetry/host-metrics` pacakge. diff --git a/packages/opentelemetry-node/docs/release-status.asciidoc b/packages/opentelemetry-node/docs/release-status.asciidoc deleted file mode 100644 index ba2eef62..00000000 --- a/packages/opentelemetry-node/docs/release-status.asciidoc +++ /dev/null @@ -1,9 +0,0 @@ -.Alpha release -[WARNING] -==== -The {distro_name} 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 https://github.com/elastic/elastic-otel-node/issues[opening a GitHub issue] or starting a discussion thread on the https://discuss.elastic.co/tags/c/observability/apm/58/nodejs[Elastic Discuss forum]. -==== diff --git a/packages/opentelemetry-node/docs/release-status.md b/packages/opentelemetry-node/docs/release-status.md new file mode 100644 index 00000000..1776c0e8 --- /dev/null +++ b/packages/opentelemetry-node/docs/release-status.md @@ -0,0 +1,5 @@ + +> [!WARNING] +> The Elastic Distribution for 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). diff --git a/packages/opentelemetry-node/docs/supported-technologies.asciidoc b/packages/opentelemetry-node/docs/supported-technologies.asciidoc deleted file mode 100644 index 175b15ab..00000000 --- a/packages/opentelemetry-node/docs/supported-technologies.asciidoc +++ /dev/null @@ -1,160 +0,0 @@ -//// -Goal of this doc: -??? - -Assumptions we're comfortable making about the reader: -- ??? -- ??? -- ??? -//// - -[[supported-technologies]] -== Supported technologies - -:language: Node.js -:distro_name: Elastic Distribution for OpenTelemetry {language} - -include::release-status.asciidoc[] - -[discrete] -[[supported-technologies-elastic-stack-versions]] -=== Elastic Stack versions - -The Elastic Distribution for OpenTelemetry Node.js ("the distro") sends data -via OpenTelemetry protocol (OTLP). Since version 7.14, Elastic Observability -https://www.elastic.co/blog/native-opentelemetry-support-in-elastic-observability[supports OTLP natively]. - -Note that OpenTelemetry support is being improved in the 8.x versions of the -Elastic Stack, so it is strongly recommended to be using a recent 8.x version. - -[discrete] -[[supported-technologies-nodejs-versions]] -=== Node.js versions - -// tag::node-version[] -The Elastic Distribution for OpenTelemety Node.js supports Node.js v14 and later. -This follows from the https://github.com/open-telemetry/opentelemetry-js#supported-runtimes[OpenTelemetry JS supported runtimes]. -// end::node-version[] - -[discrete] -[[instrumentations]] -=== Instrumentations - -[%header] -|=== -| Name | Packages instrumented | Reference - -| `@opentelemetry/instrumentation-aws-sdk` -| `aws-sdk` v2 and `@aws-sdk/client-*` v3 -| https://github.com/open-telemetry/opentelemetry-js-contrib/tree/main/plugins/node/opentelemetry-instrumentation-aws-sdk#readme[README] - -| `@opentelemetry/instrumentation-bunyan` -| `bunyan` version range `^1.0.0` -| https://github.com/open-telemetry/opentelemetry-js-contrib/tree/main/plugins/node/opentelemetry-instrumentation-bunyan#readme[README] - -| `@opentelemetry/instrumentation-express` -| `express` version range `^4.0.0` -| https://github.com/open-telemetry/opentelemetry-js-contrib/tree/main/plugins/node/opentelemetry-instrumentation-express#readme[README] - -| `@opentelemetry/instrumentation-fastify` -| `fastify` version range `>=3 <5` -| https://github.com/open-telemetry/opentelemetry-js-contrib/tree/main/plugins/node/opentelemetry-instrumentation-fastify#readme[README] - -| `@opentelemetry/instrumentation-generic-pool` -| `generic-pool` version range `2 - 2.3, ^2.4, >=3` -| https://github.com/open-telemetry/opentelemetry-js-contrib/tree/main/plugins/node/opentelemetry-instrumentation-generic-pool#readme[README] - -| `@opentelemetry/instrumentation-grpc` -| `@grpc/grpc-js` version range `^1.0.0` -| https://github.com/open-telemetry/opentelemetry-js/tree/main/experimental/packages/opentelemetry-instrumentation-grpc#readme[README] - -| `@opentelemetry/instrumentation-hapi` -| `@hapi/hapi >=17.0.0 <21` -| https://github.com/open-telemetry/opentelemetry-js-contrib/tree/main/plugins/node/opentelemetry-instrumentation-hapi#readme[README] - -| `@opentelemetry/instrumentation-http` -| `http` module for Node.js `>=14` -| https://github.com/open-telemetry/opentelemetry-js/tree/main/experimental/packages/opentelemetry-instrumentation-http#readme[README] - -| `@opentelemetry/instrumentation-ioredis` -| `ioredis` version range `>=2 <6` -| https://github.com/open-telemetry/opentelemetry-js-contrib/tree/main/plugins/node/opentelemetry-instrumentation-ioredis#readme[README] - -| `@opentelemetry/instrumentation-knex` -| `knex` version range `>=0.10.0` -| https://github.com/open-telemetry/opentelemetry-js-contrib/tree/main/plugins/node/opentelemetry-instrumentation-knex#readme[README] - -| `@opentelemetry/instrumentation-koa` -| `koa` version range `^2.0.0` -| https://github.com/open-telemetry/opentelemetry-js-contrib/tree/main/plugins/node/opentelemetry-instrumentation-koa#readme[README] - -| `@opentelemetry/instrumentation-lru-memoizer` -| `lru-memoizer` version range `>=1.3 <3` -| https://github.com/open-telemetry/opentelemetry-js-contrib/tree/main/plugins/node/instrumentation-lru-memoizer#readme[README] - -| `@opentelemetry/instrumentation-memcached` -| `memcached` version range `>=2.2` -| https://github.com/open-telemetry/opentelemetry-js-contrib/tree/main/plugins/node/opentelemetry-instrumentation-memcached#readme[README] - -| `@opentelemetry/instrumentation-mongodb` -| `mongodb` version range `>=3.3 <7` -| https://github.com/open-telemetry/opentelemetry-js-contrib/tree/main/plugins/node/opentelemetry-instrumentation-mongodb#readme[README] - -| `@opentelemetry/instrumentation-nestjs-core` -| `@nestjs/core` version range `>=4.0.0` -| https://github.com/open-telemetry/opentelemetry-js-contrib/tree/main/plugins/node/opentelemetry-instrumentation-nestjs-core#readme[README] - -| `@opentelemetry/instrumentation-net` -| `net` module for Node.js `>=14` -| https://github.com/open-telemetry/opentelemetry-js-contrib/tree/main/plugins/node/opentelemetry-instrumentation-net#readme[README] - -| `@opentelemetry/instrumentation-pino` -| `pino` version range `>=5.14.0 <10` -| https://github.com/open-telemetry/opentelemetry-js-contrib/tree/main/plugins/node/opentelemetry-instrumentation-pino#readme[README] - -| `@opentelemetry/instrumentation-pg` -| `pg` version range `>=8 <9` -| https://github.com/open-telemetry/opentelemetry-js-contrib/tree/main/plugins/node/opentelemetry-instrumentation-pg#readme[README] - -| `@opentelemetry/instrumentation-redis-4` -| `redis` version range `^4.0.0` -| https://github.com/open-telemetry/opentelemetry-js-contrib/tree/main/plugins/node/opentelemetry-instrumentation-redis-4#readme[README] - -| `@opentelemetry/instrumentation-restify` -| `restify` version range `>=4.0.0 <12` -| https://github.com/open-telemetry/opentelemetry-js-contrib/tree/main/plugins/node/opentelemetry-instrumentation-restify#readme[README] - -| `@opentelemetry/instrumentation-router` -| `router` version range `1` -| https://github.com/open-telemetry/opentelemetry-js-contrib/tree/main/plugins/node/opentelemetry-instrumentation-router#readme[README] - -| `@opentelemetry/instrumentation-socket.io` -| `socket.io` version range `2, >=3 <5` -| https://github.com/open-telemetry/opentelemetry-js-contrib/tree/main/plugins/node/instrumentation-socket.io#readme[README] - -| `@opentelemetry/instrumentation-tedious` -| `tedious` version range `>=1.11.0 <=15` -| https://github.com/open-telemetry/opentelemetry-js-contrib/tree/main/plugins/node/instrumentation-tedious#readme[README] - -| `@opentelemetry/instrumentation-undici` -| `undici` version range `>=5.12.0` -| https://github.com/open-telemetry/opentelemetry-js-contrib/tree/main/plugins/node/instrumentation-undici#readme[README] - -| `@opentelemetry/instrumentation-winston` -| `winston` version range `>1 <4` -| https://github.com/open-telemetry/opentelemetry-js-contrib/tree/main/plugins/node/opentelemetry-instrumentation-winston#readme[README] -|=== - -[discrete] -[[supported-technologies-esm]] -=== ECMAScript Modules (ESM) - -This Distro includes *limited and experimental* support for instrumenting https://nodejs.org/api/esm.html#modules-ecmascript-modules[ECMAScript module imports], i.e. modules that are loaded via `import ...` statements and `import('...')` (dynamic import). - -// TODO: add this to the above paragraph once we have an esm.md doc: -// See the [ECMAScript module support](./esm.md) document for details. - -Limitations: - -* For Node.js `>=20.6.0 || >=18.19.0`, support for hooking `import`s is automatically enabled. For earlier versions of Node.js, you must manually enable the `import`-hook via the `--experimental-loader=@elastic/opentelemetry-node/hook.mjs` option, e.g.: `node --experimental-loader=@elastic/opentelemetry-node/hook.mjs --require=@elastic/opentelemetry-node app.js`. -* Currently only a subset of instrumentations support ESM: `express`, `ioredis`, `koa`, `pg`, `pino`. See https://github.com/open-telemetry/opentelemetry-js-contrib/issues/1942[this OpenTelemetry JS tracking issue] for progress. diff --git a/packages/opentelemetry-node/docs/supported-technologies.md b/packages/opentelemetry-node/docs/supported-technologies.md new file mode 100644 index 00000000..df678462 --- /dev/null +++ b/packages/opentelemetry-node/docs/supported-technologies.md @@ -0,0 +1,74 @@ + + +# Supported technologies + +> [!WARNING] +> The Elastic Distribution for 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). + +## Elastic Stack versions + +The Elastic Distribution for OpenTelemetry Node.js ("the distro") sends data +via OpenTelemetry protocol (OTLP). Since version 7.14, Elastic Observability +[supports OTLP natively](https://www.elastic.co/blog/native-opentelemetry-support-in-elastic-observability). + +Note that OpenTelemetry support is being improved in the 8.x versions of the +Elastic Stack, so it is strongly recommended to be using a recent 8.x version. + +## Node.js versions + +The Elastic Distribution for OpenTelemety Node.js supports Node.js v14 and later. +This follows from the [OpenTelemetry JS supported runtimes](https://github.com/open-telemetry/opentelemetry-js#supported-runtimes). + +## Instrumentations + +| Name | Packages instrumented | Reference | +|---|---|---| +| `@opentelemetry/instrumentation-aws-sdk` | `aws-sdk` v2 and `@aws-sdk/client-*` v3 | [README](https://github.com/open-telemetry/opentelemetry-js-contrib/tree/main/plugins/node/opentelemetry-instrumentation-aws-sdk#readme) | +| `@opentelemetry/instrumentation-bunyan` | `bunyan` version range `^1.0.0` | [README](https://github.com/open-telemetry/opentelemetry-js-contrib/tree/main/plugins/node/opentelemetry-instrumentation-bunyan#readme) | +| `@opentelemetry/instrumentation-express` | `express` version range `^4.0.0` | [README](https://github.com/open-telemetry/opentelemetry-js-contrib/tree/main/plugins/node/opentelemetry-instrumentation-express#readme) | +| `@opentelemetry/instrumentation-fastify` | `fastify` version range `>=3 <5` | [README](https://github.com/open-telemetry/opentelemetry-js-contrib/tree/main/plugins/node/opentelemetry-instrumentation-fastify#readme) | +| `@opentelemetry/instrumentation-generic-pool` | `generic-pool` version range `2 - 2.3, ^2.4, >=3` | [README](https://github.com/open-telemetry/opentelemetry-js-contrib/tree/main/plugins/node/opentelemetry-instrumentation-generic-pool#readme) | +| `@opentelemetry/instrumentation-grpc` | `@grpc/grpc-js` version range `^1.0.0` | [README](https://github.com/open-telemetry/opentelemetry-js/tree/main/experimental/packages/opentelemetry-instrumentation-grpc#readme) | +| `@opentelemetry/instrumentation-hapi` | `@hapi/hapi >=17.0.0 <21` | [README](https://github.com/open-telemetry/opentelemetry-js-contrib/tree/main/plugins/node/opentelemetry-instrumentation-hapi#readme) | +| `@opentelemetry/instrumentation-http` | `http` module for Node.js `>=14` | [README](https://github.com/open-telemetry/opentelemetry-js/tree/main/experimental/packages/opentelemetry-instrumentation-http#readme) | +| `@opentelemetry/instrumentation-ioredis` | `ioredis` version range `>=2 <6` | [README](https://github.com/open-telemetry/opentelemetry-js-contrib/tree/main/plugins/node/opentelemetry-instrumentation-ioredis#readme) | +| `@opentelemetry/instrumentation-knex` | `knex` version range `>=0.10.0` | [README](https://github.com/open-telemetry/opentelemetry-js-contrib/tree/main/plugins/node/opentelemetry-instrumentation-knex#readme) | +| `@opentelemetry/instrumentation-koa` | `koa` version range `^2.0.0` | [README](https://github.com/open-telemetry/opentelemetry-js-contrib/tree/main/plugins/node/opentelemetry-instrumentation-koa#readme) | +| `@opentelemetry/instrumentation-lru-memoizer` | `lru-memoizer` version range `>=1.3 <3` | [README](https://github.com/open-telemetry/opentelemetry-js-contrib/tree/main/plugins/node/instrumentation-lru-memoizer#readme) | +| `@opentelemetry/instrumentation-memcached` | `memcached` version range `>=2.2` | [README](https://github.com/open-telemetry/opentelemetry-js-contrib/tree/main/plugins/node/opentelemetry-instrumentation-memcached#readme) | +| `@opentelemetry/instrumentation-mongodb` | `mongodb` version range `>=3.3 <7` | [README](https://github.com/open-telemetry/opentelemetry-js-contrib/tree/main/plugins/node/opentelemetry-instrumentation-mongodb#readme) | +| `@opentelemetry/instrumentation-nestjs-core` | `@nestjs/core` version range `>=4.0.0` | [README](https://github.com/open-telemetry/opentelemetry-js-contrib/tree/main/plugins/node/opentelemetry-instrumentation-nestjs-core#readme) | +| `@opentelemetry/instrumentation-net` | `net` module for Node.js `>=14` | [README](https://github.com/open-telemetry/opentelemetry-js-contrib/tree/main/plugins/node/opentelemetry-instrumentation-net#readme) | +| `@opentelemetry/instrumentation-pino` | `pino` version range `>=5.14.0 <10` | [README](https://github.com/open-telemetry/opentelemetry-js-contrib/tree/main/plugins/node/opentelemetry-instrumentation-pino#readme) | +| `@opentelemetry/instrumentation-pg` | `pg` version range `>=8 <9` | [README](https://github.com/open-telemetry/opentelemetry-js-contrib/tree/main/plugins/node/opentelemetry-instrumentation-pg#readme) | +| `@opentelemetry/instrumentation-redis-4` | `redis` version range `^4.0.0` | [README](https://github.com/open-telemetry/opentelemetry-js-contrib/tree/main/plugins/node/opentelemetry-instrumentation-redis-4#readme) | +| `@opentelemetry/instrumentation-restify` | `restify` version range `>=4.0.0 <12` | [README](https://github.com/open-telemetry/opentelemetry-js-contrib/tree/main/plugins/node/opentelemetry-instrumentation-restify#readme) | +| `@opentelemetry/instrumentation-router` | `router` version range `1` | [README](https://github.com/open-telemetry/opentelemetry-js-contrib/tree/main/plugins/node/opentelemetry-instrumentation-router#readme) | +| `@opentelemetry/instrumentation-socket.io` | `socket.io` version range `2, >=3 <5` | [README](https://github.com/open-telemetry/opentelemetry-js-contrib/tree/main/plugins/node/instrumentation-socket.io#readme) | +| `@opentelemetry/instrumentation-tedious` | `tedious` version range `>=1.11.0 <=15` | [README](https://github.com/open-telemetry/opentelemetry-js-contrib/tree/main/plugins/node/instrumentation-tedious#readme) | +| `@opentelemetry/instrumentation-undici` | `undici` version range `>=5.12.0` | [README](https://github.com/open-telemetry/opentelemetry-js-contrib/tree/main/plugins/node/instrumentation-undici#readme) | +| `@opentelemetry/instrumentation-winston` | `winston` version range `>1 <4` | [README](https://github.com/open-telemetry/opentelemetry-js-contrib/tree/main/plugins/node/opentelemetry-instrumentation-winston#readme) | + +## ECMAScript Modules (ESM) + +This Distro includes **limited and experimental** support for instrumenting [ECMAScript module imports](https://nodejs.org/api/esm.html#modules-ecmascript-modules), i.e. modules that are loaded via `import ...` statements and `import('...')` (dynamic import). + + + +Limitations: + +* For Node.js `>=20.6.0 || >=18.19.0`, support for hooking `import`s is automatically enabled. For earlier versions of Node.js, you must manually enable the `import`-hook via the `--experimental-loader=@elastic/opentelemetry-node/hook.mjs` option, e.g.: `node --experimental-loader=@elastic/opentelemetry-node/hook.mjs --require=@elastic/opentelemetry-node app.js`. +* Currently only a subset of instrumentations support ESM: `express`, `ioredis`, `koa`, `pg`, `pino`. See [this OpenTelemetry JS tracking issue](https://github.com/open-telemetry/opentelemetry-js-contrib/issues/1942) for progress. From b15d16383d360db09bbc32c952436081637adb67 Mon Sep 17 00:00:00 2001 From: Colleen McGinnis Date: Fri, 2 Aug 2024 17:07:46 -0500 Subject: [PATCH 09/12] add links to docs in readme --- README.md | 6 ++++++ packages/opentelemetry-node/docs/get-started.md | 5 +++-- packages/opentelemetry-node/docs/release-status.md | 5 ----- 3 files changed, 9 insertions(+), 7 deletions(-) delete mode 100644 packages/opentelemetry-node/docs/release-status.md diff --git a/README.md b/README.md index c6559e1b..18f76ddb 100644 --- a/README.md +++ b/README.md @@ -6,3 +6,9 @@ and working with OpenTelemetry. Primarily that includes Elastic Distribution for OpenTelemetry Node.js. It may also include other Elastic-authored instrumentations or other utilities. +## Read the docs + +* [Get started](./get-started.md) +* [Configuration](./configure.md) +* [Supported technologies](./supported-technologies.md) +* [Metrics](./metrics.md) diff --git a/packages/opentelemetry-node/docs/get-started.md b/packages/opentelemetry-node/docs/get-started.md index e9eee40d..a52a3613 100644 --- a/packages/opentelemetry-node/docs/get-started.md +++ b/packages/opentelemetry-node/docs/get-started.md @@ -118,8 +118,9 @@ To confirm that the distro has successfully connected to Elastic: 1. Go to **APM** → **Services**. 1. You should see the name of the service to which you just added the distro. It can take several minutes after initializing the distro for the service to show up in this list. 1. Click on the name in the list to see trace data. - > ![NOTE] - > There may be no trace data to visualize unless you have _used_ your application since initializing the distro. + +> ![NOTE] +> There may be no trace data to visualize unless you have _used_ your application since initializing the distro. > [!TIP] > Alternatively, if you are able to see the stdout from your service, you can look for an "INFO" level log message, `start Elastic Distribution for OpenTelemetry Node.js`, at startup to confirm that the distro is up and running. diff --git a/packages/opentelemetry-node/docs/release-status.md b/packages/opentelemetry-node/docs/release-status.md deleted file mode 100644 index 1776c0e8..00000000 --- a/packages/opentelemetry-node/docs/release-status.md +++ /dev/null @@ -1,5 +0,0 @@ - -> [!WARNING] -> The Elastic Distribution for 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). From 6dc97288312fe4d6ad5ce6ecd62194d74fa3fd05 Mon Sep 17 00:00:00 2001 From: Colleen McGinnis Date: Tue, 13 Aug 2024 16:48:20 -0500 Subject: [PATCH 10/12] merge intro and README content, link to docs from README, adjust for github audience --- README.md | 7 +- packages/opentelemetry-node/README.md | 89 ++++++------------- packages/opentelemetry-node/docs/configure.md | 63 ++++++------- .../opentelemetry-node/docs/get-started.md | 13 +-- packages/opentelemetry-node/docs/index.md | 7 -- packages/opentelemetry-node/docs/intro.md | 40 --------- packages/opentelemetry-node/docs/metrics.md | 19 +--- .../docs/supported-technologies.md | 17 +--- 8 files changed, 63 insertions(+), 192 deletions(-) delete mode 100644 packages/opentelemetry-node/docs/index.md delete mode 100644 packages/opentelemetry-node/docs/intro.md diff --git a/README.md b/README.md index 18f76ddb..6eea2e47 100644 --- a/README.md +++ b/README.md @@ -6,9 +6,4 @@ and working with OpenTelemetry. Primarily that includes Elastic Distribution for OpenTelemetry Node.js. It may also include other Elastic-authored instrumentations or other utilities. -## Read the docs - -* [Get started](./get-started.md) -* [Configuration](./configure.md) -* [Supported technologies](./supported-technologies.md) -* [Metrics](./metrics.md) +[**Read the Elastic Distribution for OpenTelemetry Node.js docs →**](./packages/opentelemetry-node/README.md) diff --git a/packages/opentelemetry-node/README.md b/packages/opentelemetry-node/README.md index 839aeea3..84b781d6 100644 --- a/packages/opentelemetry-node/README.md +++ b/packages/opentelemetry-node/README.md @@ -1,83 +1,46 @@ # Elastic Distribution for 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 for 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 for OpenTelemetry Node.js (the distro) 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 the Elastic distro 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.asciidoc#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. + + -# Usage +Use the distro to start the OpenTelemetry SDK with your Node.js application to automatically capture tracing data, performance metrics, and logs. The distro 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 the distro?** 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/get-started.asciidoc#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/get-started.asciidoc) for more details. - - -# Documentation - -- [Getting Started](./docs/get-started.asciidoc) -- [Supported Technologies](./docs/supported-technologies.asciidoc) -- [Metrics](./docs/metrics.asciidoc) - - -# 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). \ No newline at end of file diff --git a/packages/opentelemetry-node/docs/configure.md b/packages/opentelemetry-node/docs/configure.md index b9b5b40f..29158cf8 100644 --- a/packages/opentelemetry-node/docs/configure.md +++ b/packages/opentelemetry-node/docs/configure.md @@ -9,10 +9,7 @@ Assumptions we're comfortable making about the reader: # Configuration -> [!WARNING] -> The Elastic Distribution for 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). +Configure the Elastic Distribution for OpenTelemetry Node.js (the distro) to send data to Elastic. ## Configuration method @@ -45,7 +42,7 @@ export OTEL_SERVICE_NAME=my-service ## Configuration options -Because the Elastic Distribution for OpenTelemetry Node.js ("the distro") 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. +Because the Elastic Distribution for OpenTelemetry Node.js (the distro) 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. ## Authentication methods -When sending data to Elastic, there are two ways you can authenticate: using a secret token or using an APM agent key. - -### Use a secret token - - - -[Secret tokens](https://elastic.co/guide/en/observability/current/apm-secret-token.html) are used to authorize -requests to the APM Server. Both the distro and APM Server must be configured with the same secret token for -the request to be accepted. - - - -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" - ``` +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) - -It is also possible to authenticate to an Elastic Observability endpoint using -an [APM agent key](https://elastic.co/guide/en/observability/current/apm-api-key.html). -These are revocable API keys. - - + +[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. To create and manage APM Agent keys in Kibana: @@ -118,3 +90,22 @@ different auth schema (`ApiKey` rather than `Bearer`). For example: 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 + + +[Secret tokens](https://elastic.co/guide/en/observability/current/apm-secret-token.html) are used to authorize +requests to the APM Server. Both the distro and APM Server must be configured with the same secret token for +the request to be accepted. + + +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" + ``` diff --git a/packages/opentelemetry-node/docs/get-started.md b/packages/opentelemetry-node/docs/get-started.md index a52a3613..eb4400af 100644 --- a/packages/opentelemetry-node/docs/get-started.md +++ b/packages/opentelemetry-node/docs/get-started.md @@ -10,17 +10,12 @@ Assumptions we're comfortable making about the reader: # Get started -> [!WARNING] -> The Elastic Distribution for 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). - -This guide shows you how to use the Elastic Distribution for OpenTelemetry Node.js ("the distro") +This guide shows you how to use the Elastic Distribution for OpenTelemetry Node.js (the distro) to instrument your Node.js application and send OpenTelemetry data to an Elastic Observability deployment. -This doc will guide you through the minimal configuration options to get the Elastic distro set up in your application. -You do _not_ need any existing experience with OpenTelemetry to set up the Elastic distro initially. -If you need more control over your configuration after getting set up, you can learn more in [OpenTelemetry SDK documentation](https://opentelemetry.io/docs/languages/js). +**Already familiar with OpenTelemetry?** It's an explicit goal of this distribution to introduce _no new concepts_ outside those defined by the wider OpenTelemetry community. + +**New to OpenTelemetry?** This section will guide you through the _minimal_ configuration options to get the distro set up in your application. You do _not_ need any existing experience with OpenTelemetry to set up the distro initially. If you need more control over your configuration after getting set up, you can learn more in the [OpenTelemetry documentation](https://opentelemetry.io/docs/languages/js). > [!NOTE] > As an OpenTelemetry SDK, the distro supports sending data to any OpenTelemetry protocol (OTLP) endpoint ([OpenTelemetry Collector](https://opentelemetry.io/docs/collector/)), but this guide assumes you are sending data to Elastic. diff --git a/packages/opentelemetry-node/docs/index.md b/packages/opentelemetry-node/docs/index.md deleted file mode 100644 index 343a4630..00000000 --- a/packages/opentelemetry-node/docs/index.md +++ /dev/null @@ -1,7 +0,0 @@ -# Elastic Distribution for OpenTelemetry .NET - -* [Introduction](./intro.md) -* [Get started](./get-started.md) -* [Configuration](./configure.md) -* [Supported technologies](./supported-technologies.md) -* [Metrics](./metrics.md) diff --git a/packages/opentelemetry-node/docs/intro.md b/packages/opentelemetry-node/docs/intro.md deleted file mode 100644 index d4301b08..00000000 --- a/packages/opentelemetry-node/docs/intro.md +++ /dev/null @@ -1,40 +0,0 @@ - - -# Introduction - -> [!WARNING] -> The Elastic Distribution for 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 for OpenTelemetry Node.js ("the distro") is a Node.js package that provides: - -* An easy way to instrument your application with OpenTelemetry. -* Configuration defaults for best usage. - - - -A _distribution_ is a customized version of an upstream OpenTelemetry repository with some customizations. The Elastic Distribution for OpenTelemetry Node.js is an extension of the [OpenTelemetry SDK for Node.js](https://opentelemetry.io/docs/languages/js). With the Elastic distro you have access to all the features of the OpenTelemetry SDK for Node.js plus: - -* 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). - - -> [!NOTE] -> For more details about OpenTelemetry distributions in general, visit the [OpenTelemetry documentation](https://opentelemetry.io/docs/concepts/distributions). - - -Use the distro to start the OpenTelemetry SDK with your Node.js application to automatically capture tracing data, performance metrics, and logs. Traces, metrics, and logs are sent to any OTLP collector you choose. - -After you start sending data to Elastic, use an [Elastic Observability](https://www.elastic.co/guide/en/observability/current/index.html) deployment — hosted on Elastic Cloud or on-premises — to monitor your applications, create alerts, and quickly identify root causes of service issues. - - -**Ready to try out the distro?** Follow the step-by-step instructions in [Get started](./get-started.md). diff --git a/packages/opentelemetry-node/docs/metrics.md b/packages/opentelemetry-node/docs/metrics.md index 80e06364..e8704417 100644 --- a/packages/opentelemetry-node/docs/metrics.md +++ b/packages/opentelemetry-node/docs/metrics.md @@ -1,23 +1,10 @@ - + # Metrics -> [!WARNING] -> The Elastic Distribution for 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). - ## Enabled by default -In this distribution metrics are enabled by default and sent to the endpoint +In the Elastic Distribution for Node.js (the distro) metrics are enabled by default and sent to the endpoint configured by you. If you wish to disable metrics you can by setting the env variable `ELASTIC_OTEL_METRICS_DISABLED` to the string `true`. @@ -36,4 +23,4 @@ to export data you can use the env vars already defined in [the spec](https://op ## Host metrics The Elastic Distribution for OpenTelemetry Node.js also gathers metrics from the -host machine with `@opentelemetry/host-metrics` pacakge. +host machine with `@opentelemetry/host-metrics` package. diff --git a/packages/opentelemetry-node/docs/supported-technologies.md b/packages/opentelemetry-node/docs/supported-technologies.md index 54be9b12..564ab4b3 100644 --- a/packages/opentelemetry-node/docs/supported-technologies.md +++ b/packages/opentelemetry-node/docs/supported-technologies.md @@ -1,23 +1,10 @@ - + # Supported technologies -> [!WARNING] -> The Elastic Distribution for 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). - ## Elastic Stack versions -The Elastic Distribution for OpenTelemetry Node.js ("the distro") sends data +The Elastic Distribution for OpenTelemetry Node.js (the distro) sends data via OpenTelemetry protocol (OTLP). Since version 7.14, Elastic Observability [supports OTLP natively](https://www.elastic.co/blog/native-opentelemetry-support-in-elastic-observability). From c8a6adab3948f61efc45f4d2fb6d4af23d7ddf0d Mon Sep 17 00:00:00 2001 From: Colleen McGinnis Date: Wed, 14 Aug 2024 08:42:08 -0500 Subject: [PATCH 11/12] update naming (docs files) --- README.md | 6 +-- packages/opentelemetry-node/README.md | 12 +++--- packages/opentelemetry-node/docs/configure.md | 16 ++++---- .../opentelemetry-node/docs/get-started.md | 40 +++++++++---------- packages/opentelemetry-node/docs/metrics.md | 4 +- .../docs/supported-technologies.md | 2 +- 6 files changed, 40 insertions(+), 40 deletions(-) diff --git a/README.md b/README.md index 6eea2e47..b5d047ed 100644 --- a/README.md +++ b/README.md @@ -1,9 +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 for OpenTelemetry Node.js docs →**](./packages/opentelemetry-node/README.md) +[**Read the Elastic Distribution of OpenTelemetry Node.js docs →**](./packages/opentelemetry-node/README.md) diff --git a/packages/opentelemetry-node/README.md b/packages/opentelemetry-node/README.md index 84b781d6..82825ac3 100644 --- a/packages/opentelemetry-node/README.md +++ b/packages/opentelemetry-node/README.md @@ -1,16 +1,16 @@ -# Elastic Distribution for OpenTelemetry Node.js +# Elastic Distribution of OpenTelemetry Node.js > [!WARNING] -> The Elastic Distribution for 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. +> 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 for OpenTelemetry Node.js (the distro) 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. +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. > [!NOTE] > For more details about OpenTelemetry distributions in general, visit the [OpenTelemetry documentation](https://opentelemetry.io/docs/concepts/distributions). -With the Elastic distro you have access to all the features of the OpenTelemetry SDK for Node.js plus: +With EDOT Node.js you have access to all the features of the OpenTelemetry SDK for Node.js plus: * 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. @@ -18,9 +18,9 @@ With the Elastic distro you have access to all the features of the OpenTelemetry -Use the distro to start the OpenTelemetry SDK with your Node.js application to automatically capture tracing data, performance metrics, and logs. The distro 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). +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). -**Ready to try out the distro?** Follow the step-by-step instructions in [Get started](./docs/get-started.md). +**Ready to try out EDOT Node.js?** Follow the step-by-step instructions in [Get started](./docs/get-started.md). ## Install diff --git a/packages/opentelemetry-node/docs/configure.md b/packages/opentelemetry-node/docs/configure.md index 29158cf8..2f39541d 100644 --- a/packages/opentelemetry-node/docs/configure.md +++ b/packages/opentelemetry-node/docs/configure.md @@ -9,20 +9,20 @@ Assumptions we're comfortable making about the reader: # Configuration -Configure the Elastic Distribution for OpenTelemetry Node.js (the distro) to send data to Elastic. +Configure the Elastic Distribution of OpenTelemetry Node.js (EDOT Node.js) to send data to Elastic. ## 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/). -The distro can be further configured using advanced settings when you need complete control of its behavior. +EDOT Node.js can be further configured using advanced settings when you need complete control of its behavior. -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. +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. -The distro will send telemetry data via OpenTelemetry's protocol (OTLP) to the +EDOT Node.js will send telemetry data via OpenTelemetry's protocol (OTLP) to the configured endpoint (by default it sends to ). The endpoint can be changed by setting the following environment vars: @@ -42,7 +42,7 @@ export OTEL_SERVICE_NAME=my-service ## Configuration options -Because the Elastic Distribution for OpenTelemetry Node.js (the distro) 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. +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. @@ -95,7 +95,7 @@ export OTEL_EXPORTER_OTLP_HEADERS="Authorization=ApiKey TkpXUkx...dVZGQQ==" [Secret tokens](https://elastic.co/guide/en/observability/current/apm-secret-token.html) are used to authorize -requests to the APM Server. Both the distro and APM Server must be configured with the same secret token for +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. diff --git a/packages/opentelemetry-node/docs/get-started.md b/packages/opentelemetry-node/docs/get-started.md index eb4400af..99450dc3 100644 --- a/packages/opentelemetry-node/docs/get-started.md +++ b/packages/opentelemetry-node/docs/get-started.md @@ -1,6 +1,6 @@ + ## Prerequisites Before getting started, you'll need somewhere to send the gathered OpenTelemetry data, so it can be viewed and analyzed. This doc assumes you're using an [Elastic Observability](https://www.elastic.co/observability) cloud deployment. You can use an existing one or set up a new one. @@ -37,7 +37,7 @@ To create your first Elastic Observability deployment: - + ## Install @@ -47,7 +47,7 @@ Install the `@elastic/opentelemetry-node` package: npm install --save @elastic/opentelemetry-node ``` -The distro is a single package that includes all the OpenTelemetry JS packages +EDOT Node.js is a single package that includes all the OpenTelemetry JS packages that are needed for most cases. @@ -55,14 +55,14 @@ that are needed for most cases. ## Send data to Elastic -After installing the distro, configure and initialize it to start +After installing EDOT Node.js, configure and initialize it to start sending data to Elastic. -### Configure the distro +### Configure EDOT Node.js -To configure the distro, at a minimum you'll need your Elastic Observability cloud deployment's OTLP endpoint and +To configure EDOT Node.js, at a minimum you'll need your Elastic Observability cloud deployment's OTLP endpoint and authorization data to set the appropriate `OTLP_*` environment variables: * `OTEL_EXPORTER_OTLP_ENDPOINT`: The full URL of the endpoint where data will be sent. @@ -84,9 +84,9 @@ In Kibana: For more information on all the available configuration options, refer to [Configuration](./configure.md). -### Initialize the distro +### Initialize EDOT Node.js -For the distro to automatically instrument modules used by your Node.js service, +For EDOT Node.js to automatically instrument modules used by your Node.js service, it must be started before you `require` your service code's dependencies -- for example, before `express` or `http` are loaded. @@ -99,31 +99,31 @@ distro started is by using the `-r, --require` Node.js node --require @elastic/opentelemetry-node my-service.js ``` -The distro will automatically instrument popular modules (listed in [Supported technologies](./supported-technologies.md)) +EDOT Node.js will automatically instrument popular modules (listed in [Supported technologies](./supported-technologies.md)) used by your service, and send traces, metrics, and logs telemetry data (using OTLP) to your configured observability backend. - + -## Confirm that the distro is working +## Confirm that EDOT Node.js is working -To confirm that the distro has successfully connected to Elastic: +To confirm that EDOT Node.js has successfully connected to Elastic: 1. Go to **APM** → **Services**. -1. You should see the name of the service to which you just added the distro. It can take several minutes after initializing the distro for the service to show up in this list. +1. You should see the name of the service to which you just added EDOT Node.js. It can take several minutes after initializing EDOT Node.js for the service to show up in this list. 1. Click on the name in the list to see trace data. > ![NOTE] -> There may be no trace data to visualize unless you have _used_ your application since initializing the distro. +> There may be no trace data to visualize unless you have _used_ your application since initializing EDOT Node.js. > [!TIP] -> Alternatively, if you are able to see the stdout from your service, you can look for an "INFO" level log message, `start Elastic Distribution for OpenTelemetry Node.js`, at startup to confirm that the distro is up and running. +> Alternatively, if you are able to see the stdout from your service, you can look for an "INFO" level log message, `start Elastic Distribution of OpenTelemetry Node.js`, at startup to confirm that EDOT Node.js is up and running. ## Next steps -* Learn how to configure the distro and browse all [configuration options](./configure.md). +* Learn how to configure EDOT Node.js and browse all [configuration options](./configure.md). * Learn more about viewing and interpreting APM data in the [Observability guide](https://elastic.co/guide/en/observability/current/apm.html). * Have a question? Start a discussion thread on the [Elastic Discuss forum](https://discuss.elastic.co/tags/c/observability/apm/58/nodejs). diff --git a/packages/opentelemetry-node/docs/metrics.md b/packages/opentelemetry-node/docs/metrics.md index e8704417..9eead766 100644 --- a/packages/opentelemetry-node/docs/metrics.md +++ b/packages/opentelemetry-node/docs/metrics.md @@ -4,7 +4,7 @@ ## Enabled by default -In the Elastic Distribution for Node.js (the distro) metrics are enabled by default and sent to the endpoint +In the Elastic Distribution for Node.js (EDOT Node.js) metrics are enabled by default and sent to the endpoint configured by you. If you wish to disable metrics you can by setting the env variable `ELASTIC_OTEL_METRICS_DISABLED` to the string `true`. @@ -22,5 +22,5 @@ to export data you can use the env vars already defined in [the spec](https://op ## Host metrics -The Elastic Distribution for OpenTelemetry Node.js also gathers metrics from the +EDOT Node.js also gathers metrics from the host machine with `@opentelemetry/host-metrics` package. diff --git a/packages/opentelemetry-node/docs/supported-technologies.md b/packages/opentelemetry-node/docs/supported-technologies.md index 564ab4b3..29a91d1b 100644 --- a/packages/opentelemetry-node/docs/supported-technologies.md +++ b/packages/opentelemetry-node/docs/supported-technologies.md @@ -4,7 +4,7 @@ ## Elastic Stack versions -The Elastic Distribution for OpenTelemetry Node.js (the distro) sends data +The Elastic Distribution of OpenTelemetry Node.js (EDOT Node.js) sends data via OpenTelemetry protocol (OTLP). Since version 7.14, Elastic Observability [supports OTLP natively](https://www.elastic.co/blog/native-opentelemetry-support-in-elastic-observability). From e9ebf7a50cd88e35b3fa9cfcc7e2203763910865 Mon Sep 17 00:00:00 2001 From: Colleen McGinnis Date: Wed, 14 Aug 2024 08:42:51 -0500 Subject: [PATCH 12/12] update naming (non-docs files) --- CONTRIBUTING.md | 2 +- packages/mockotlpserver/share/k8s/README.md | 6 +++--- packages/opentelemetry-node/CHANGELOG.md | 2 +- packages/opentelemetry-node/NOTICE.md | 2 +- packages/opentelemetry-node/lib/elastic-node-sdk.js | 2 +- packages/opentelemetry-node/package.json | 2 +- 6 files changed, 8 insertions(+), 8 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 20ac048c..e7acfc3a 100644 --- a/CONTRIBUTING.md +++ b/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, diff --git a/packages/mockotlpserver/share/k8s/README.md b/packages/mockotlpserver/share/k8s/README.md index f908914d..7ba08087 100644 --- a/packages/mockotlpserver/share/k8s/README.md +++ b/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 > example-app-manual@1.0.0 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 diff --git a/packages/opentelemetry-node/CHANGELOG.md b/packages/opentelemetry-node/CHANGELOG.md index 1598b7c7..584d7e74 100644 --- a/packages/opentelemetry-node/CHANGELOG.md +++ b/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). diff --git a/packages/opentelemetry-node/NOTICE.md b/packages/opentelemetry-node/NOTICE.md index 4e0500e1..86fbe15f 100644 --- a/packages/opentelemetry-node/NOTICE.md +++ b/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 diff --git a/packages/opentelemetry-node/lib/elastic-node-sdk.js b/packages/opentelemetry-node/lib/elastic-node-sdk.js index 16470d76..076c4a00 100644 --- a/packages/opentelemetry-node/lib/elastic-node-sdk.js +++ b/packages/opentelemetry-node/lib/elastic-node-sdk.js @@ -156,7 +156,7 @@ class ElasticNodeSDK extends NodeSDK { runtime: `Node.js ${process.version}`, }, }, - 'start Elastic Distribution for OpenTelemetry Node.js' + 'start Elastic Distribution of OpenTelemetry Node.js' ); super.start(); diff --git a/packages/opentelemetry-node/package.json b/packages/opentelemetry-node/package.json index e0ddfe2e..868f588a 100644 --- a/packages/opentelemetry-node/package.json +++ b/packages/opentelemetry-node/package.json @@ -2,7 +2,7 @@ "name": "@elastic/opentelemetry-node", "version": "0.3.0", "type": "commonjs", - "description": "Elastic Distribution for OpenTelemetry Node.js", + "description": "Elastic Distribution of OpenTelemetry Node.js", "publishConfig": { "access": "public", "provenance": true