Skip to content

Latest commit

 

History

History
111 lines (82 loc) · 4.67 KB

configure.md

File metadata and controls

111 lines (82 loc) · 4.67 KB
Raw

Configuration

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. EDOT Node.js can be further configured using advanced settings when you need complete control of its behavior.

EDOT Node.js is typically configured with OTEL_* environment variables defined by the OpenTelemetry spec. Environment variables are read at startup and can be used to configure EDOT Node.js.

EDOT Node.js will send telemetry data via OpenTelemetry's protocol (OTLP) to the configured endpoint (by default it sends to http://localhost:4317). The endpoint can be changed by setting the following environment vars:

  • OTEL_EXPORTER_OTLP_ENDPOINT: The full URL of the endpoint where data will be sent.
  • OTEL_EXPORTER_OTLP_HEADERS: A comma-separated list of key=value pairs that will be added to the headers of every request. This is typically this is used for authentication information.

For example, to send telemetry data to your Elastic Observability deployment you might start the application like this:

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 EDOT Node.js is an extension of the OpenTelemetry Node.js SDK and other OpenTelemetry JavaScript packages, it supports OTEL_* environment variables per the OpenTelemetry Environment Variable spec.

Authentication methods

When sending data to Elastic, there are two ways you can authenticate: using an APM agent key or using a secret token.

Use an APM agent key (API key)

APM agent keys 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:

  1. Go to APM Settings.
  2. Select the Agent Keys tab.

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:

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 are used to authorize requests to the APM Server. Both EDOT Node.js and APM Server must be configured with the same secret token for the request to be accepted.

You can find the values of these variables in Kibana's APM tutorial. In Kibana:

  1. Search for APM Tutorial.
  2. Scroll down to the APM Agents section and select the OpenTelemetry tab.
  3. 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"