Skip to content

Commit

Permalink
feat(auto-instrumentations-node): Add "@opentelemetry/auto-instrument…
Browse files Browse the repository at this point in the history
…ations-node/register" for an agent-like experience (open-telemetry#1400)

* feat(auto-instrumentation-agent): added intrumentation-agent package

* feat(auto-instrumentation-agent): added api peer dependency

* feat(auto-instrumentation-agent): updated test

* feat(auto-instrumentation-agent): updated release please config

* feat(auto-instrumentation-agent): updated .release-please-manifest

* feat(auto-instrumentation-agent): updated test timeout

* feat(auto-instrumentation-agent): removed timeout, added pretest script

* feat(auto-instrumentation-agent): moved agent to auto-instrumentations-node

* feat(auto-instrumentation-agent): reverted release please config

* feat(auto-instrumentation-agent): updated README.md

* feat(auto-instrumentation-agent): added env variable for resource detector configuration

* feat(auto-instrumentation-agent): removed no-process-exit

* feat(auto-instrumentation-agent): removed pretest script

* feat(auto-instrumentation-agent): fixed lint issues

* feat(auto-instrumentation-agent): updated register test

* feat(auto-instrumentation-agent): fixed typo in test

* feat(auto-instrumentation-agent): using env instead of export

* feat(auto-instrumentation-agent): updated eslint.config.js

* feat(auto-instrumentation-agent): updated test

* feat(auto-instrumentation-agent): using language specific env var name

* feat(auto-instrumentation-agent): updated README.md

* feat(auto-instrumentation-agent): updated dependencies

* feat(auto-instrumentation-agent): fixed detector test

* feat(auto-instrumentation-agent): added comment to test app

* feat(auto-instrumentation-agent): small refactor

* feat(auto-instrumentation-agent): updated log messages

* feat(auto-instrumentation-agent): added missing aws detectors

* feat(auto-instrumentation-agent): updated tests

* feat(auto-instrumentation-agent): updated getResourceDetectorsFromEnv()

* feat(auto-instrumentation-agent): revert unnecessary changes

* feat(auto-instrumentation-agent): added reference to supported instrumentations

* feat(auto-instrumentation-agent): added reference to env var spec

* feat(auto-instrumentation-agent): added reference node documentation

* feat(auto-instrumentation-agent): added note for unsupported config

* feat(auto-instrumentation-agent): added note to the debug section

* feat(auto-instrumentation-agent): moved opentelemetry/api to regular dependency

* feat(auto-instrumentation-agent): fixed lint issue

* feat(auto-instrumentation-agent): re-added peer dep

* feat(auto-instrumentation-agent): re-added api dev dep

* feat(auto-instrumentation-agent): fixed lint issue

* feat(auto-instrumentation-agent): fixed lint issue

* feat(auto-instrumentation-agent): updated README.md

* feat(auto-instrumentation-agent): added exporters reference in README.md

* feat(auto-instrumentation-agent): updated debug notes

* feat(auto-instrumentation-agent): updated installation section to include the api dependency

* feat(auto-instrumentation-agent): reordered aws resource detectors

* feat(auto-instrumentation-agent): removed process.exit(0)

* feat(auto-instrumentation-agent): reordered aws resource detectors

* feat(auto-instrumentation-agent): replaced type any with actual types

* feat(auto-instrumentation-agent): updated utils test

* feat(auto-instrumentation-agent): updated register test

* feat(auto-instrumentation-agent): updated README.md

* feat(auto-instrumentation-agent): updated shutdown logs

* feat(auto-instrumentation-agent): fixed sinon issue
  • Loading branch information
samimusallam authored May 1, 2023
1 parent b5b951e commit 2d8e2b8
Show file tree
Hide file tree
Showing 7 changed files with 343 additions and 5 deletions.
87 changes: 85 additions & 2 deletions metapackages/auto-instrumentations-node/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -3,17 +3,97 @@
[![NPM Published Version][npm-img]][npm-url]
[![Apache License][license-image]][license-url]

This module provides a simple way to initialize multiple Node instrumentations.
## About

This module provides a way to auto instrument any Node application to capture telemetry from a number of popular libraries and frameworks.
You can export the telemetry data in a variety of formats. Exporters, samplers, and more can be configured via [environment variables][env-var-url].
The net result is the ability to gather telemetry data from a Node application without any code changes.

This module also provides a simple way to manually initialize multiple Node instrumentations for use with the OpenTelemetry SDK.

Compatible with OpenTelemetry JS API and SDK `1.0+`.

## Installation

```bash
npm install --save @opentelemetry/api
npm install --save @opentelemetry/auto-instrumentations-node
```

## Usage
## Usage: Auto Instrumentation

This module includes auto instrumentation for all supported instrumentations and [all available data exporters][exporter-url].
It provides a completely automatic, out-of-the-box experience.
Please see the [Supported Instrumentations](#supported-instrumentations) section for more information.

Enable auto instrumentation by requiring this module using the [--require flag][require-url]:

```shell
node --require '@opentelemetry/auto-instrumentations-node/register' app.js
```

If your Node application is encapsulated in a complex run script, you can also set it via an environment variable before running Node.

```shell
env NODE_OPTIONS="--require @opentelemetry/auto-instrumentations-node/register"
```

The module is highly configurable using environment variables.
Many aspects of the auto instrumentation's behavior can be configured for your needs, such as resource detectors, exporter choice, exporter configuration, trace context propagation headers, and much more.
Instrumentation configuration is not yet supported through environment variables. Users that require instrumentation configuration must initialize OpenTelemetry programmatically.

```shell
export OTEL_TRACES_EXPORTER="otlp"
export OTEL_EXPORTER_OTLP_PROTOCOL="http/protobuf"
export OTEL_EXPORTER_OTLP_COMPRESSION="gzip"
export OTEL_EXPORTER_OTLP_TRACES_ENDPOINT="https://your-endpoint"
export OTEL_EXPORTER_OTLP_HEADERS="x-api-key=your-api-key"
export OTEL_EXPORTER_OTLP_TRACES_HEADERS="x-api-key=your-api-key"
export OTEL_RESOURCE_ATTRIBUTES="service.namespace=my-namespace"
export OTEL_NODE_RESOURCE_DETECTORS="env,host,os"
export OTEL_SERVICE_NAME="client"
export NODE_OPTIONS="--require @opentelemetry/auto-instrumentations-node/register"
node app.js
```

By default, all SDK resource detectors are used, but you can use the environment variable OTEL_NODE_RESOURCE_DETECTORS to enable only certain detectors, or completely disable them:

- `env`
- `host`
- `os`
- `process`
- `container`
- `alibaba`
- `aws`
- `gcp`
- `all` - enable all resource detectors
- `none` - disable resource detection

For example, to enable only the `env`, `host` detectors:

```shell
export OTEL_NODE_RESOURCE_DETECTORS="env,host"
```

To enable logging for troubleshooting, set the log level by setting the `OTEL_LOG_LEVEL` environment variable to one of the following:

- `none`
- `error`
- `warn`
- `info`
- `debug`
- `verbose`
- `all`

The default level is `info`.

Notes:

- In a production environment, it is recommended to set `OTEL_LOG_LEVEL`to `info`.
- Logs are always sent to console, no matter the environment, or debug level.
- Debug logs are extremely verbose. Enable debug logging only when needed. Debug logging negatively impacts the performance of your application.

## Usage: Instrumentation Initialization

OpenTelemetry Meta Packages for Node automatically loads instrumentations for Node builtin modules and common packages.

Expand Down Expand Up @@ -100,3 +180,6 @@ APACHE 2.0 - See [LICENSE][license-url] for more information.
[license-image]: https://img.shields.io/badge/license-Apache_2.0-green.svg?style=flat
[npm-url]: https://www.npmjs.com/package/@opentelemetry/auto-instrumentations-node
[npm-img]: https://badge.fury.io/js/%40opentelemetry%2Fauto-instrumentations-node.svg
[env-var-url]: https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/configuration/sdk-environment-variables.md#general-sdk-configuration
[exporter-url]: https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/configuration/sdk-environment-variables.md#otlp-exporter
[require-url]: https://nodejs.org/api/cli.html#-r---require-module
16 changes: 13 additions & 3 deletions metapackages/auto-instrumentations-node/package.json
Original file line number Diff line number Diff line change
Expand Up @@ -13,6 +13,10 @@
},
"main": "build/src/index.js",
"types": "build/src/index.d.ts",
"exports": {
".": "./build/src/index.js",
"./register": "./build/src/register.js"
},
"repository": "open-telemetry/opentelemetry-js-contrib",
"scripts": {
"clean": "rimraf build/*",
Expand All @@ -30,10 +34,10 @@
"url": "https://github.com/open-telemetry/opentelemetry-js-contrib/issues"
},
"peerDependencies": {
"@opentelemetry/api": "^1.3.0"
"@opentelemetry/api": "^1.4.1"
},
"devDependencies": {
"@opentelemetry/api": "^1.3.0",
"@opentelemetry/api": "^1.4.1",
"@types/mocha": "7.0.2",
"@types/node": "18.11.7",
"@types/sinon": "10.0.2",
Expand Down Expand Up @@ -82,6 +86,12 @@
"@opentelemetry/instrumentation-router": "^0.32.2",
"@opentelemetry/instrumentation-socket.io": "^0.33.2",
"@opentelemetry/instrumentation-tedious": "^0.5.2",
"@opentelemetry/instrumentation-winston": "^0.31.2"
"@opentelemetry/instrumentation-winston": "^0.31.2",
"@opentelemetry/resource-detector-alibaba-cloud": "^0.27.4",
"@opentelemetry/resource-detector-aws": "^1.2.2",
"@opentelemetry/resource-detector-container": "^0.2.2",
"@opentelemetry/resource-detector-gcp": "^0.28.0",
"@opentelemetry/resources": "^1.12.0",
"@opentelemetry/sdk-node": "^0.38.0"
}
}
48 changes: 48 additions & 0 deletions metapackages/auto-instrumentations-node/src/register.ts
Original file line number Diff line number Diff line change
@@ -0,0 +1,48 @@
/*
* Copyright The OpenTelemetry Authors
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* https://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
import * as opentelemetry from '@opentelemetry/sdk-node';
import { diag, DiagConsoleLogger } from '@opentelemetry/api';
import {
getNodeAutoInstrumentations,
getResourceDetectorsFromEnv,
} from './utils';

diag.setLogger(
new DiagConsoleLogger(),
opentelemetry.core.getEnv().OTEL_LOG_LEVEL
);

const sdk = new opentelemetry.NodeSDK({
instrumentations: getNodeAutoInstrumentations(),
resourceDetectors: getResourceDetectorsFromEnv(),
});

try {
sdk.start();
diag.info('OpenTelemetry automatic instrumentation started successfully');
} catch (error) {
diag.error(
'Error initializing OpenTelemetry SDK. Your application is not instrumented and will not produce telemetry',
error
);
}

process.on('SIGTERM', () => {
sdk
.shutdown()
.then(() => diag.debug('OpenTelemetry SDK terminated'))
.catch(error => diag.error('Error terminating OpenTelemetry SDK', error));
});
74 changes: 74 additions & 0 deletions metapackages/auto-instrumentations-node/src/utils.ts
Original file line number Diff line number Diff line change
Expand Up @@ -54,6 +54,34 @@ import { SocketIoInstrumentation } from '@opentelemetry/instrumentation-socket.i
import { TediousInstrumentation } from '@opentelemetry/instrumentation-tedious';
import { WinstonInstrumentation } from '@opentelemetry/instrumentation-winston';

import { alibabaCloudEcsDetector } from '@opentelemetry/resource-detector-alibaba-cloud';
import {
awsBeanstalkDetector,
awsEc2Detector,
awsEcsDetector,
awsEksDetector,
awsLambdaDetector,
} from '@opentelemetry/resource-detector-aws';
import { containerDetector } from '@opentelemetry/resource-detector-container';
import { gcpDetector } from '@opentelemetry/resource-detector-gcp';
import {
Detector,
DetectorSync,
envDetectorSync,
hostDetectorSync,
osDetectorSync,
processDetectorSync,
} from '@opentelemetry/resources';

const RESOURCE_DETECTOR_CONTAINER = 'container';
const RESOURCE_DETECTOR_ENVIRONMENT = 'env';
const RESOURCE_DETECTOR_HOST = 'host';
const RESOURCE_DETECTOR_OS = 'os';
const RESOURCE_DETECTOR_PROCESS = 'process';
const RESOURCE_DETECTOR_ALIBABA = 'alibaba';
const RESOURCE_DETECTOR_AWS = 'aws';
const RESOURCE_DETECTOR_GCP = 'gcp';

const InstrumentationMap = {
'@opentelemetry/instrumentation-amqplib': AmqplibInstrumentation,
'@opentelemetry/instrumentation-aws-lambda': AwsLambdaInstrumentation,
Expand Down Expand Up @@ -136,3 +164,49 @@ export function getNodeAutoInstrumentations(

return instrumentations;
}

export function getResourceDetectorsFromEnv(): Array<Detector | DetectorSync> {
const resourceDetectors = new Map<
string,
Detector | DetectorSync | Detector[]
>([
[RESOURCE_DETECTOR_CONTAINER, containerDetector],
[RESOURCE_DETECTOR_ENVIRONMENT, envDetectorSync],
[RESOURCE_DETECTOR_HOST, hostDetectorSync],
[RESOURCE_DETECTOR_OS, osDetectorSync],
[RESOURCE_DETECTOR_PROCESS, processDetectorSync],
[RESOURCE_DETECTOR_ALIBABA, alibabaCloudEcsDetector],
[RESOURCE_DETECTOR_GCP, gcpDetector],
[
RESOURCE_DETECTOR_AWS,
[
awsEc2Detector,
awsEcsDetector,
awsEksDetector,
awsBeanstalkDetector,
awsLambdaDetector,
],
],
]);

const resourceDetectorsFromEnv =
process.env.OTEL_NODE_RESOURCE_DETECTORS?.split(',') ?? ['all'];

if (resourceDetectorsFromEnv.includes('all')) {
return [...resourceDetectors.values()].flat();
}

if (resourceDetectorsFromEnv.includes('none')) {
return [];
}

return resourceDetectorsFromEnv.flatMap(detector => {
const resourceDetector = resourceDetectors.get(detector);
if (!resourceDetector) {
diag.error(
`Invalid resource detector "${detector}" specified in the environment variable OTEL_NODE_RESOURCE_DETECTORS`
);
}
return resourceDetector || [];
});
}
44 changes: 44 additions & 0 deletions metapackages/auto-instrumentations-node/test/register.test.ts
Original file line number Diff line number Diff line change
@@ -0,0 +1,44 @@
/*
* Copyright The OpenTelemetry Authors
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* https://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
import { promisify } from 'util';
import * as childProcess from 'child_process';
import * as assert from 'assert';

const exec = promisify(childProcess.exec);

describe('Register', function () {
this.timeout(5000);
it('can load auto instrumentation from command line', async () => {
process.env.OTEL_NODE_RESOURCE_DETECTORS = 'none';
process.env.OTEL_TRACES_EXPORTER = 'console';

const { stdout } = await exec(
'node --require ./build/src/register.js ./test/test-app/app.js'
);

assert.ok(
stdout.includes(
'OpenTelemetry automatic instrumentation started successfully'
)
);

//Check a span has been generated for the GET request done in app.js
assert.ok(stdout.includes("name: 'GET'"));

delete process.env.OTEL_NODE_RESOURCE_DETECTORS;
delete process.env.OTEL_TRACES_EXPORTER;
});
});
29 changes: 29 additions & 0 deletions metapackages/auto-instrumentations-node/test/test-app/app.js
Original file line number Diff line number Diff line change
@@ -0,0 +1,29 @@
/*
* Copyright The OpenTelemetry Authors
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* https://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/

//Used in register.test.ts to mimic a JS app.
const http = require('http');

const options = {
hostname: 'example.com',
port: 80,
path: '/',
method: 'GET'
};

const req = http.request(options);

req.end();
Loading

0 comments on commit 2d8e2b8

Please sign in to comment.