|
| 1 | +# Introduction |
| 2 | + |
| 3 | +This is the Elastic OpenTelemetry Distribution for Node.js (the "Distro"). It is |
| 4 | +a Node.js package that provides: |
| 5 | +- easy way to instrument your application with OpenTelemetry |
| 6 | +- configuration defaults for best usage |
| 7 | + |
| 8 | +Use the Distro to start the OpenTelemetry SDK with your Node.js application to automatically |
| 9 | +capture tracing data, performance metrics, and logs. Traces, metrics, and logs are sent |
| 10 | +to any OTLP collector you choose. Use an [Elastic Observability](https://www.elastic.co/observability) |
| 11 | +deployment -- hosted in Elastic's cloud or on-premises -- to monitor your applications, create alerts, |
| 12 | +and quickly identify root causes of service issues. |
| 13 | + |
| 14 | + |
| 15 | +# Getting Started |
| 16 | + |
| 17 | +This getting started guide will show how to use this 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/). |
| 18 | + |
| 19 | +An Elastic Observability deployment includes an OTLP endpoint to receive data. That data is processed and stored in Elasticsearch, and Kibana provides a web interface to visualize and analyze the date. If you do not already have |
| 20 | +a deployment to use, follow [this Quick Start guide](https://www.elastic.co/blog/getting-started-with-elastic-cloud) |
| 21 | +to create a free trial on Elastic's cloud. From this deployment you will need |
| 22 | +the APM **`serverUrl`** and a configured **`apmAgentKey`** to use for configuring the SDK distribution. |
| 23 | + |
| 24 | +## Installation |
| 25 | + |
| 26 | +```sh |
| 27 | +npm install --save @elastic/opentelemetry-node |
| 28 | +``` |
| 29 | + |
| 30 | +## Initialization |
| 31 | + |
| 32 | +It’s important that the agent is started before you require **any** other modules |
| 33 | +in your Node.js application - i.e. before express, http, etc. |
| 34 | + |
| 35 | +The preferred way to get the SDK started is by using the `--require` |
| 36 | +Node.js [CLI option](https://nodejs.org/api/cli.html#-r---require-module). |
| 37 | + |
| 38 | +```sh |
| 39 | +node --require @elastic/opentelemetry-node app.js |
| 40 | +``` |
| 41 | + |
| 42 | +## Configuration |
| 43 | + |
| 44 | +By default the SDK will send telemetry data via OpenTelemetry's protocol (OTLP) |
| 45 | +to the configured endpoint (by default it sends to <http://localhost:4317>). The |
| 46 | +endpoint configuration can be changed by setting the following environment vars: |
| 47 | + |
| 48 | +- `OTEL_EXPORTER_OTLP_ENDPOINT`: full URL of the endpoint where to send the data. |
| 49 | +- `OTEL_EXPORTER_OTLP_HEADERS`: coma separated list of `key=value` pairs which will |
| 50 | + be added to the headers of every request. |
| 51 | + |
| 52 | + |
| 53 | +As an example if you want to send telemetry data to your Elastic's APM deployment you |
| 54 | +may start the application like this |
| 55 | + |
| 56 | +```sh |
| 57 | +export OTEL_EXPORTER_OTLP_ENDPOINT="https://apm-server-url.co" |
| 58 | +export OTEL_EXPORTER_OTLP_HEADERS="Authorization=ApiKey VnVhQ2ZHY0JDZGJr..." |
| 59 | +node -r @elastic/opentelemetry-node/start.js my-app.js |
| 60 | +``` |
0 commit comments