Skip to content

Latest commit

 

History

History
130 lines (91 loc) · 6.24 KB

get-started.md

File metadata and controls

130 lines (91 loc) · 6.24 KB
Raw

Get started

This guide shows you how to use the Elastic Distribution of OpenTelemetry Node.js (EDOT Node.js) to instrument your Node.js application and send OpenTelemetry data to an Elastic Observability deployment.

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 EDOT Node.js set up in your application. You do not need any existing experience with OpenTelemetry to set up EDOT Node.js initially. If you need more control over your configuration after getting set up, you can learn more in the OpenTelemetry documentation.

Note

As an OpenTelemetry SDK, EDOT Node.js supports sending data to any OpenTelemetry protocol (OTLP) endpoint (OpenTelemetry 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 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 or sign into an existing account.
  2. Go to https://cloud.elastic.co/home.
  3. Click Create deployment.
  4. 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:

npm install --save @elastic/opentelemetry-node

EDOT Node.js is a single package that includes all the OpenTelemetry JS packages that are needed for most cases.

Send data to Elastic

After installing EDOT Node.js, configure and initialize it to start sending data to Elastic.

Configure EDOT Node.js

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.
  • 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.
  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"

Kibana's APM tutorial showing OTel settings

For more information on all the available configuration options, refer to Configuration.

Initialize EDOT Node.js

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.

The recommended way to get the distro started is by using the -r, --require Node.js CLI option:

node --require @elastic/opentelemetry-node my-service.js

EDOT Node.js will automatically instrument popular modules (listed in Supported technologies) used by your service, and send traces, metrics, and logs telemetry data (using OTLP) to your configured observability backend.

Confirm that EDOT Node.js is working

To confirm that EDOT Node.js has successfully connected to Elastic:

  1. Go to APM → Services.
  2. 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.
  3. 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 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 of OpenTelemetry Node.js, at startup to confirm that EDOT Node.js is up and running.

Next steps