Skip to content

Commit 00adc1c

Browse files
trentmtrentm
committed
docs: README refresh and docs update
Refs: #152
1 parent 59ab85b commit 00adc1c

File tree

6 files changed

+240
-112
lines changed

6 files changed

+240
-112
lines changed

‎DEVELOPMENT.md

Lines changed: 85 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,85 @@
1+
This document contains informal notes to help developers of the Elastic APM
2+
Node.js agent. Developers should feel free to aggressively weed out obsolete
3+
notes. For structured developer and contributing *rules and guidelines*, see
4+
[CONTRIBUTING.md](./CONTRIBUTING.md).
5+
6+
7+
### mockotlpserver OTLP endpoint
8+
9+
For local development, it can be useful to have an OTLP endpoint that is local,
10+
and can show the exact details of data being sent by the OTel SDK. The
11+
[mockotlpserver package](./packages/mockotlpserver/) in this repository
12+
provides a CLI tool for this.
13+
14+
```sh
15+
git clone https://github.com/elastic/elastic-otel-node.git
16+
cd elastic-otel-node/
17+
npm ci
18+
cd packages/mockotlpserver
19+
npm start -- --help # mockotlpserver CLI options
20+
npm start
21+
```
22+
23+
This starts a service listening on the default OTLP/gRPC and OTLP/HTTP ports.
24+
It will print received OTLP request data. By default it shows a raw print of
25+
the protobuf request, e.g.:
26+
27+
```
28+
ExportTraceServiceRequest {
29+
resourceSpans: [
30+
ResourceSpans {
31+
scopeSpans: [
32+
ScopeSpans {
33+
spans: [
34+
Span {
35+
attributes: [
36+
KeyValue { key: 'http.url', value: AnyValue { stringValue: 'http://localhost:3000/' } },
37+
...
38+
name: 'GET',
39+
kind: 2,
40+
...
41+
```
42+
43+
and a "summary" compact representation of the request, e.g.:
44+
45+
```
46+
------ trace 802356 (2 spans) ------
47+
span f06b1a "GET" (15.5ms, SPAN_KIND_CLIENT, GET http://localhost:3000/ -> 200)
48+
+9ms `- span 226bf7 "GET" (4.2ms, SPAN_KIND_SERVER, GET http://localhost:3000/ -> 200)
49+
```
50+
51+
Try it with:
52+
53+
```sh
54+
cd elastic-otel-node/examples
55+
node -r @elastic/opentelemetry-node simple-http-request.js
56+
```
57+
58+
See [the mockotlpserver README](./packages/mockotlpserver#readme) for more details.
59+
60+
61+
# Logging tips
62+
63+
## logging
64+
65+
`OTEL_LOG_LEVEL=verbose` will turn on the most verbose-level logging in the SDK,
66+
including enabling the core OpenTelemetry `diag` logger messages.
67+
68+
This distro's logging is currently in the JSON format used by the
69+
[`luggite`](https://github.com/trentm/node-luggite) library. It be somewhat
70+
pretty-formatted via the [`pino-pretty` tool](https://github.com/pinojs/pino-pretty):
71+
72+
OTEL_LOG_LEVEL=verbose node myapp.js | pino-pretty
73+
74+
One of the important libs in the SDK is [require-in-the-middle](https://github.com/elastic/require-in-the-middle)
75+
for intercepting `require(...)` statements for monkey-patching. You can get
76+
debug output from it via:
77+
78+
DEBUG=require-in-the-middle
79+
80+
And don't forget the node core [`NODE_DEBUG` and `NODE_DEBUG_NATIVE`](https://nodejs.org/api/all.html#cli_node_debug_module)
81+
environment variables:
82+
83+
NODE_DEBUG=*
84+
NODE_DEBUG_NATIVE=*
85+

‎packages/opentelemetry-node/README.md

Lines changed: 48 additions & 78 deletions
Original file line numberDiff line numberDiff line change
@@ -1,103 +1,73 @@
1-
# Elastic OpenTelemetry Node.js Distribution
1+
# Elastic OpenTelemetry Distribution for Node.js
22

3-
This is the Elastic OpenTelemetry Node.js Distribution. It is a light wrapper
4-
around the OpenTelemetry Node SDK that makes it easier to get started using
5-
OpenTelemetry in your Node.js applications, especially if you are using [Elastic
6-
Observability](https://www.elastic.co/observability) as your observability
7-
solution.
3+
This is the Elastic OpenTelemetry Distribution for Node.js (the "Distro").
4+
It is a light wrapper around the OpenTelemetry Node SDK that makes it easier to
5+
get started using OpenTelemetry in your Node.js applications, especially if you
6+
are using [Elastic Observability](https://www.elastic.co/observability) as your
7+
observability solution.
88

9-
# Current status
10-
11-
Pre-alpha
12-
13-
# Install
14-
15-
Eventually this will be `npm install @elastic/opentelemetry-node`.
16-
However, while still in early development, this package is not yet published
17-
to npm, so you'll need to access it via git:
189

19-
git clone https://github.com/elastic/elastic-otel-node.git
20-
cd elastic-otel-node/
21-
npm ci
22-
23-
and then install the package sub-directory:
10+
# Current status
2411

25-
npm install .../elastic-otel-node/packages/opentelemetry-node
12+
The current release is **alpha**, and not yet recommended for production use.
13+
We welcome your feedback! You can reach us either on the [issue tracker](https://github.com/elastic/elastic-otel-node/issues)
14+
or on [Elastic's Discuss forum](https://discuss.elastic.co/tags/c/observability/apm/58/nodejs).
2615

27-
(TODO: update ^^ once published to npm.)
16+
Some limitations / notes:
17+
- 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.md#instrumentations).
2818

2919

3020
# Usage
3121

32-
To start the SDK, it must be loaded before any of your application code. The
33-
recommended way to do that is via Node.js's [`-r, --require`
34-
option](https://nodejs.org/api/all.html#all_cli_-r---require-module):
35-
36-
node -r @elastic/opentelemetry-node my-app.js
37-
38-
TODO: Link to coming user guide for related topics: ES module support, configuration reference, starting the SDK via
39-
40-
41-
# Configuring your telemetry endpoint
42-
43-
By default the SDK will send telemetry data via OpenTelemetry's protocol (OTLP)
44-
to the configured endpoint (by default it sends to <http://localhost:4317>):
45-
46-
OTEL_EXPORTER_OTLP_ENDPOINT=... \
47-
OTEL_EXPORTER_OTLP_HEADERS=... \
48-
node -r @elastic/opentelemetry-node my-app.js
49-
50-
You can send to any OTLP endpoint, for example: an [OTel Collector](https://opentelemetry.io/docs/collector/),
51-
or directly to an Elastic Observability deployment. Since version 7.14, Elastic
52-
[supports OTLP natively](https://www.elastic.co/blog/native-opentelemetry-support-in-elastic-observability).
53-
22+
# 1. install
23+
npm install --save @elastic/opentelemetry-node
5424

55-
### Elastic Observability endpoint
25+
# 2. configure via OTEL_ envvars, for example:
26+
export OTEL_EXPORTER_OTLP_ENDPOINT=https://{your-otlp-endpoint.example.com}
27+
export OTEL_EXPORTER_OTLP_HEADERS="Authorization=Bearer {your-Elastic-secret-token}"
28+
export OTEL_SERVICE_NAME=my-service
5629

57-
First, you will need an Elastic APM deployment. See: https://www.elastic.co/guide/en/apm/guide/current/apm-quick-start.html
58-
You will need two pieces of information: the APM **server URL** (this is the OTLP endpoint) and your APM **secret code** (or **API key** if using API keys).
59-
Then configure your
30+
# 3. start
31+
node -r @elastic/opentelemetry-node my-service.js
6032

61-
```sh
62-
export OTEL_EXPORTER_OTLP_ENDPOINT="${ELASTIC_APM_SERVER_URL}"
63-
export OTEL_EXPORTER_OTLP_HEADERS="Authorization=Bearer ${ELASTIC_APM_SECRET_TOKEN}"
64-
node -r @elastic/opentelemetry-node my-app.js
65-
```
33+
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)))
34+
used by your service, and send trace, metrics, and logs telemetry data (using
35+
OTLP) to your configured observability backend.
6636

67-
Or if using an API key, then:
37+
The Distro can be configured via `OTEL_*` environment variables, per the
38+
[OpenTelemetry Environment Variable spec](https://opentelemetry.io/docs/specs/otel/configuration/sdk-environment-variables/).
6839

69-
```sh
70-
export OTEL_EXPORTER_OTLP_ENDPOINT="${ELASTIC_APM_SERVER_URL}"
71-
export OTEL_EXPORTER_OTLP_HEADERS="Authorization=ApiKey ${ELASTIC_APM_API_KEY}"
72-
node -r @elastic/opentelemetry-node my-app.js
73-
```
40+
See the [Getting Started guide](./docs/getting-started.md) for more details.
7441

7542

76-
### mockotlpserver endpoint
43+
# Documentation
7744

78-
TODO: move this out to dev docs
45+
- [Getting Started](./docs/getting-started.md)
46+
- [Supported Technologies](./docs/supported-technologies.md)
47+
- [Metrics](./docs/metrics.md)
7948

80-
If you don't yet have an OTLP endpoint setup and just want to see the SDK
81-
working, you can run a *mock* OTLP server locally with the `mockotlpserver`
82-
utility in this repository:
8349

84-
```sh
85-
git clone https://github.com/elastic/elastic-otel-node.git
86-
cd elastic-otel-node/
87-
npm ci
88-
cd packages/mockotlpserver
89-
npm start
90-
```
50+
# Why this distribution?
9151

92-
Now running an application with this SDK will send to the mock endpoint, which
93-
prints out any received telemetry data, for example:
52+
As mentioned above, this Distro is a wrapper around the [OpenTelemetry Node
53+
SDK (`@opentelemetry/sdk-node`)](https://github.com/open-telemetry/opentelemetry-js/tree/main/experimental/packages/opentelemetry-sdk-node). So why the separate package?
54+
A few reasons:
9455

95-
```sh
96-
cd elastic-otel-node/examples
97-
node -r @elastic/opentelemetry-node simple-http-request.js
98-
```
56+
- With this separate package we hope to experiment with making it easier to get
57+
started with OpenTelemetry instrumentation in Node.js services. For example,
58+
`@elastic/opentelemetry-node` includes a number of OTel packages as dependencies,
59+
so the user only needs to install/update a single package -- at least for the
60+
default use case. This is similar to the OTel
61+
`@opentelemetry/auto-instrumentations-node` package.
9962

100-
See [the mockotlpserver README](../mockotlpserver#readme) for more details.
63+
- Having a separate package will sometimes allow us to iterate more quickly with
64+
changes in SDK behavior. However, our plan is to upstream any improvements to
65+
the OpenTelemetry JS repositories.
10166

67+
- Should it be necessary, having a separate package would allow us to more
68+
quickly release a fix for a particular issue required by a customer of ours.
10269

70+
- Providing an eventual easy migration path for customers of our current
71+
non-OpenTelemetry-based [Node.js APM agent](https://github.com/elastic/apm-agent-nodejs)
72+
to this SDK may be made easier by having our own package entry point.
10373

‎packages/opentelemetry-node/docs/getting-started.md

Lines changed: 94 additions & 28 deletions
Original file line numberDiff line numberDiff line change
@@ -1,9 +1,10 @@
11
# Introduction
22

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
3+
The Elastic OpenTelemetry Distribution for Node.js (the "Distro") is a Node.js
4+
package that provides:
5+
6+
- an easy way to instrument your application with OpenTelemetry, and
7+
- configuration defaults for best usage.
78

89
Use the Distro to start the OpenTelemetry SDK with your Node.js application to automatically
910
capture tracing data, performance metrics, and logs. Traces, metrics, and logs are sent
@@ -16,45 +17,110 @@ and quickly identify root causes of service issues.
1617

1718
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/).
1819

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-
2420
## Installation
2521

2622
```sh
2723
npm install --save @elastic/opentelemetry-node
2824
```
2925

30-
## Initialization
26+
The Distro is a single package that includes all the OpenTelemetry JS packages
27+
that are needed for most cases.
28+
29+
<!-- TODO: refer to advanced section of "start the SDK" when we have that doc. -->
30+
31+
## Configuration
32+
33+
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)
34+
and other OpenTelemetry JS packages. It is typically configured with `OTEL_*`
35+
environment variables defined by the OpenTelemetry spec. The most common
36+
configuration settings are `OTEL_EXPORTER_OTLP_*` to set the endpoint for
37+
sending data and `OTEL_SERVICE_NAME` to identify your service.
38+
39+
The Distro will send telemetry data via OpenTelemetry's protocol (OTLP) to the
40+
configured endpoint (by default it sends to <http://localhost:4317>). The
41+
endpoint can be changed by setting the following environment vars:
3142

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.
43+
- `OTEL_EXPORTER_OTLP_ENDPOINT`: full URL of the endpoint where to send the data
44+
- `OTEL_EXPORTER_OTLP_HEADERS`: Comma-separated list of `key=value` pairs which
45+
will be added to the headers of every request. Typically this is used for
46+
authentication information.
3447

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).
48+
For example, to send telemetry data to your Elastic Observability deployment you
49+
might start the application like this:
3750

3851
```sh
39-
node --require @elastic/opentelemetry-node app.js
52+
export OTEL_EXPORTER_OTLP_ENDPOINT=https://{your-otlp-endpoint.example.com}
53+
export OTEL_EXPORTER_OTLP_HEADERS="Authorization=Bearer {your-Elastic-secret-token}"
54+
export OTEL_SERVICE_NAME=my-service
4055
```
4156

42-
## Configuration
57+
If you don't have an Elastic Observability deployment or don't have the
58+
endpoint and auth data for your deployment, see the [Elastic Observability setup](#elastic-observability-setup)
59+
section below.
4360

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:
61+
## Initialization
4762

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.
63+
For the Distro to automatically instrument modules used by your Node.js service,
64+
it must be started before your service code `require`s its dependencies --
65+
e.g. before `express`, `http`, etc. are loaded. The recommended way to get the
66+
Distro started is by using the `-r, --require` Node.js
67+
[CLI option](https://nodejs.org/api/cli.html#-r---require-module).
5168

69+
```sh
70+
node --require @elastic/opentelemetry-node my-service.js
71+
```
5272

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
73+
<!-- TODO: link to a reference section on other ways to start the Distro once we have those docs. -->
5574

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
75+
76+
# Elastic Observability setup
77+
78+
You'll need somewhere to send the gathered OpenTelemetry data, so it can be
79+
viewed and analyzed. The `@elastic/opentelemetry-node` package supports sending
80+
to any OTLP endpoint (e.g. an OpenTelemetry collector instance). This section
81+
shows create an [Elastic Observability](https://www.elastic.co/observability)
82+
cloud deployment and get the data you need to configure the Distro to send
83+
data to it.
84+
85+
1. Register at [cloud.elastic.co](https://cloud.elastic.co/registration), if you haven't already. This supports starting **free trial**.
86+
87+
2. After registering, click "Create deployment" at <https://cloud.elastic.co/home>. 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+
89+
To configure the Distro you'll need the deployment's OTLP endpoint and
90+
authorization data to set the appropriate `OTLP_*` environment variables. You
91+
can find these in Kibana's APM tutorial.
92+
93+
![Kibana's APM tutorial showing OTel settings](./img/otlp-endpoint-settings.png)
94+
95+
3. In Kibana:
96+
97+
- search for "APM Tutorial",
98+
- scroll down to the "APM Agents" section and select the "OpenTelemetry" tab,
99+
- the appropriate values for `OTEL_EXPORTER_OTLP_ENDPOINT` and
100+
`OTEL_EXPORTER_OTLP_HEADERS` are shown there.
101+
102+
For example:
103+
104+
```
105+
export OTEL_EXPORTER_OTLP_ENDPOINT=https://my-deployment.apm.us-west1.gcp.cloud.es.io
106+
export OTEL_EXPORTER_OTLP_HEADERS="Authorization=Bearer P....l"
107+
```
108+
109+
Use these environment variables in the [Configuration](#configuration) step
110+
above to configure the Distro.
111+
112+
## Authenticate using an APM Agent key (API key)
113+
114+
It is also possible to authenticate to an Elastic Observability endpoint using
115+
an "APM Agent key". These are revocable API keys. To create and manage
116+
APM Agent keys, see the "Agent Keys" tab in "APM Settings" in Kibana.
117+
118+
[!Kibana's APM Agent Keys section](./img/kibana-apm-agent-keys.png)
119+
120+
When using an APM Agent key, the `OTEL_EXPORTER_OTLP_HEADERS` is set using a
121+
different auth schema (`ApiKey` rather than `Bearer`). For example:
122+
123+
```
124+
export OTEL_EXPORTER_OTLP_ENDPOINT=https://my-deployment.apm.us-west1.gcp.cloud.es.io
125+
export OTEL_EXPORTER_OTLP_HEADERS="Authorization=ApiKey TkpXUkx...dVZGQQ=="
60126
```

‎packages/opentelemetry-node/docs/img/kibana-apm-agent-keys.png

280 KB
Loading

‎packages/opentelemetry-node/docs/img/otlp-endpoint-settings.png

671 KB
Loading

0 commit comments

Comments
 (0)