@xtreamsrl/node-instrumentation
v1.1.1
Published
An utility to help with a Node.js apps instrumentation.
Downloads
437
Readme
@xtreamsrl/node-instrumentation
This package exposes a utility function to instrument your Node.js application and a method decorator to wrap your class methods in custom spans.
Installation
npm install @xtreamsrl/node-instrumentation
Usage
The following code snippet shows a basic usage of the instrument
function:
// app.ts
import { instrument } from '@xtreamsrl/node-instrumentation';
import { HttpInstrumentation } from '@opentelemetry/instrumentation-http';
import { ExpressInstrumentation } from '@opentelemetry/instrumentation-express';
instrument({
serviceName: 'my-service',
serviceVersion: '0.0.1',
enableInstrumentationDebugLogging: false,
instrumentations: [
new ExpressInstrumentation(),
new HttpInstrumentation(),
],
exporter: process.env.ENV === 'prod'
? new ProdExporter()
: new LocalExporter(),
});
// All other imports must be done after the instrument function call!
import * as AllOtherImoport from './all-other-staff';
Please note that the
instrument
function must be called before any other import statement in your application. The reason for this is that the opentelemetry instrumentation plugins must be imported before the underlying instrumented modules.
The configuration above will instrument your application with the ExpressInstrumentation
and HttpInstrumentation
plugins and will export the spans using the ProdExporter
or LocalExporter
depending on the ENV
environment variable.
That is a basic and mockup configuration, you can find more information about the available configuration options in the following section.
Configuration
The instrument
function accepts a configuration object with the following properties:
serviceName
The name of the service that is being instrumented. This will be used as the service.name
attribute on all spans.
You can use the project name defined in your package.json
file.
serviceVersion
The version of the service that is being instrumented. This will be used as the service.version
attribute on all spans.
You can use the project version defined in your package.json
file.
enableInstrumentationDebugLogging
Whether to enable debug logging for the node-instrumentation plugins. This is useful to debug issues with the node-instrumentation plugins.
node-instrumentationDebugLoggingLevel
The log level to use for the node-instrumentation plugins. Must be provided if enableInstrumentationDebugLogging
is set to true
.
node-instrumentations
An array of node-instrumentation plugins that will be used to instrument your application. The node-instrumentation plugins must implement the InstrumentationBase
interface from the @opentelemetry/node-instrumentation
package.
It is required. If provided as an empty array no node-instrumentation plugin will be used and the application will not be instrumented.
exporter
The exporter that will be used to export the spans. The exporter must implement the SpanExporter
interface from the @opentelemetry/sdk-trace-base
package.
sampler
The sampler that will be used to sample the spans. The sampler must implement the Sampler
interface from the @opentelemetry/api
package. Optional, if not provided the AlwaysOnSampler
will be used.
Environment Configuration
Setting the following environment variables will override the configuration options:
DISABLE_TRACING
If set to true
the node-instrumentation will be disabled application wide.
Span Decorator
import { Span } from '@xtreamsrl/node-instrumentation';
import { Controller, Get } from '@nestjs/common';
@Controller('api')
export class PetController {
@Span('Custom Span')
@Get('custom-span')
customSpan() {
return this.doSomething();
}
@Span('Nested Span')
private async doSomething() {
return { message: 'Hello World!' };
}
}
The code snippet above will create a custom span with the name Custom Span
. The span will be created when the customSpan
method is called and will be ended when the method returns.
The Span decorator supports nested spans, in the example above the doSomething
method will be wrapped in a span with the name Nested Span
that will be child of the Custom Span
span.
Build
Run nx build node-instrumentation
to build the package.
Run unit tests
Run nx test node-instrumentation
to execute the unit tests via Jest.
Linting
Run nx lint node-instrumentation
to execute the lint via ESLint.
Versioning
Export the GH_TOKEN
environment variable with your GitHub token with at least the repo
scope:
export GH_TOKEN=<YOUR_PERSONAL_GH_TOKEN>
Then run the following command:
lerna version
The GH_TOKEN
is needed to push the version commit and tag to the remote repository and to create the release on GitHub.
For general information about the versioning process, please refer to the root Readme Versioning section.
Publishing
Update your local .npmrc
file to include the following lines:
@xtreamsrl:registry=https://registry.npmjs.org/
//registry.npmjs.org/:_authToken=${NPM_TOKEN}
The ${NPM_TOKEN}
placeholder is a npm personal access token publish permissions on the @xtreamsrl
organization.
It can be treated as placeholder to replace with the actual token value, or you can set it as an environment variable:
export NPM_TOKEN=<YOUR_PERSONAL_NPM_TOKEN>
Then run the following command:
npm run lerna-publish