Skip to content

Commit b7103d5

Browse files
trentmtrentm
authored
docs: README refresh and docs update (#157)
Refs: #152
1 parent 68af5a7 commit b7103d5

File tree

6 files changed

+254
-109
lines changed

6 files changed

+254
-109
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: 56 additions & 75 deletions
Original file line numberDiff line numberDiff line change
@@ -1,103 +1,84 @@
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
149

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:
18-
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).
22+
```sh
23+
# 1. install
24+
npm install --save @elastic/opentelemetry-node
5325

26+
# 2. configure via OTEL_ envvars, for example:
27+
export OTEL_EXPORTER_OTLP_ENDPOINT=https://{your-otlp-endpoint.example.com}
28+
export OTEL_EXPORTER_OTLP_HEADERS="Authorization={authorization-information}"
29+
export OTEL_SERVICE_NAME=my-service
5430

55-
### Elastic Observability endpoint
31+
# 3. start
32+
node -r @elastic/opentelemetry-node my-service.js
33+
```
5634

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
35+
If using an [Elastic Observability deployment](./docs/getting-started.md#elastic-observability-setup)
36+
to which to send telemetry data, the `OTEL_EXPORTER_*` settings will look
37+
something like:
6038

6139
```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
40+
export OTEL_EXPORTER_OTLP_ENDPOINT=https://{deployment-name}.apm.{cloud-region}.cloud.es.io
41+
export OTEL_EXPORTER_OTLP_HEADERS="Authorization=Bearer {deployment-secret-token}"
6542
```
6643

67-
Or if using an API key, then:
44+
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)))
45+
used by your service, and send trace, metrics, and logs telemetry data (using
46+
OTLP) to your configured observability backend.
6847

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-
```
48+
The Distro can be configured via `OTEL_*` environment variables, per the
49+
[OpenTelemetry Environment Variable spec](https://opentelemetry.io/docs/specs/otel/configuration/sdk-environment-variables/).
7450

51+
See the [Getting Started guide](./docs/getting-started.md) for more details.
7552

76-
### mockotlpserver endpoint
7753

78-
TODO: move this out to dev docs
54+
# Documentation
7955

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:
56+
- [Getting Started](./docs/getting-started.md)
57+
- [Supported Technologies](./docs/supported-technologies.md)
58+
- [Metrics](./docs/metrics.md)
8359

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-
```
9160

92-
Now running an application with this SDK will send to the mock endpoint, which
93-
prints out any received telemetry data, for example:
61+
# Why this distribution?
9462

95-
```sh
96-
cd elastic-otel-node/examples
97-
node -r @elastic/opentelemetry-node simple-http-request.js
98-
```
63+
As mentioned above, this Distro is a wrapper around the [OpenTelemetry Node
64+
SDK (`@opentelemetry/sdk-node`)](https://github.com/open-telemetry/opentelemetry-js/tree/main/experimental/packages/opentelemetry-sdk-node). So why the separate package?
65+
A few reasons:
66+
67+
- With this separate package we hope to experiment with making it easier to get
68+
started with OpenTelemetry instrumentation in Node.js services. For example,
69+
`@elastic/opentelemetry-node` includes a number of OTel packages as dependencies,
70+
so the user only needs to install/update a single package -- at least for the
71+
default use case. This is similar to the OTel
72+
`@opentelemetry/auto-instrumentations-node` package.
9973

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

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

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

0 commit comments

Comments
 (0)