Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/pragmaticivan/nestjs-otel
OpenTelemetry (Tracing + Metrics) module for Nest framework (node.js) ðŸ”
https://github.com/pragmaticivan/nestjs-otel
hacktoberfest metrics nest nestjs nodejs observability opentelemetry prometheus typescript
Last synced: about 13 hours ago
JSON representation
OpenTelemetry (Tracing + Metrics) module for Nest framework (node.js) ðŸ”
- Host: GitHub
- URL: https://github.com/pragmaticivan/nestjs-otel
- Owner: pragmaticivan
- License: apache-2.0
- Created: 2021-06-25T13:45:39.000Z (over 3 years ago)
- Default Branch: main
- Last Pushed: 2024-10-01T02:16:05.000Z (4 months ago)
- Last Synced: 2024-10-29T15:19:25.975Z (3 months ago)
- Topics: hacktoberfest, metrics, nest, nestjs, nodejs, observability, opentelemetry, prometheus, typescript
- Language: TypeScript
- Homepage:
- Size: 3.79 MB
- Stars: 553
- Watchers: 8
- Forks: 49
- Open Issues: 17
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Funding: .github/FUNDING.yml
- License: LICENSE
Awesome Lists containing this project
README
# NestJS OpenTelemetry (OTEL)
[](https://www.npmjs.com/package/nestjs-otel)
## Description
[OpenTelemetry](https://opentelemetry.io/) module for [Nest](https://github.com/nestjs/nest).
## Questions
For questions and support please use the official [Discord channel](https://discord.gg/ju8C2zJgBJ).
## Why
Setting up observability metrics with nestjs requires multiple libraries and patterns. OpenTelemetry has support for multiple exporters and types of metrics such as Prometheus Metrics.
## Observability
Please read this [comprehensive whitepaper](https://github.com/cncf/tag-observability/blob/main/whitepaper.md) if that's your first time working with metrics, tracing, and logs.
## Examples
A full working examples are available. This includes a nestjs application fully integrated with prometheus, grafana, loki and tempo:
- [nestjs-otel-prom-grafana-tempo](https://github.com/pragmaticivan/nestjs-otel-prom-grafana-tempo )
## Installation
```bash
npm i nestjs-otel @opentelemetry/sdk-node --save
```
## Setup
Some peers dependencies are required when some configurations are enabled.
```
@opentelemetry/exporter-prometheus
```
1. Create tracing file (`tracing.ts`):
```ts
import {
CompositePropagator,
W3CTraceContextPropagator,
W3CBaggagePropagator,
} from '@opentelemetry/core';
import { BatchSpanProcessor } from '@opentelemetry/sdk-trace-base';
import { JaegerExporter } from '@opentelemetry/exporter-jaeger';
import { getNodeAutoInstrumentations } from '@opentelemetry/auto-instrumentations-node';
import { JaegerPropagator } from '@opentelemetry/propagator-jaeger';
import { B3InjectEncoding, B3Propagator } from '@opentelemetry/propagator-b3';
import { PrometheusExporter } from '@opentelemetry/exporter-prometheus';
import { NodeSDK } from '@opentelemetry/sdk-node';
import { AsyncLocalStorageContextManager } from '@opentelemetry/context-async-hooks';
import * as process from 'process';
const otelSDK = new NodeSDK({
metricReader: new PrometheusExporter({
port: 8081,
}),
spanProcessor: new BatchSpanProcessor(new JaegerExporter()),
contextManager: new AsyncLocalStorageContextManager(),
textMapPropagator: new CompositePropagator({
propagators: [
new JaegerPropagator(),
new W3CTraceContextPropagator(),
new W3CBaggagePropagator(),
new B3Propagator(),
new B3Propagator({
injectEncoding: B3InjectEncoding.MULTI_HEADER,
}),
],
}),
instrumentations: [getNodeAutoInstrumentations()],
});
export default otelSDK;
// You can also use the shutdown method to gracefully shut down the SDK before process shutdown
// or on some operating system signal.
process.on('SIGTERM', () => {
otelSDK
.shutdown()
.then(
() => console.log('SDK shut down successfully'),
err => console.log('Error shutting down SDK', err)
)
.finally(() => process.exit(0));
});
```
2. Import the metric file and start otel node SDK:
```ts
import otelSDK from './tracing';
import { NestFactory } from '@nestjs/core';
import { AppModule } from './app.module';
import { Logger } from 'nestjs-pino';
async function bootstrap() {
// Start SDK before nestjs factory create
await otelSDK.start();
const app = await NestFactory.create(AppModule);
app.useLogger(app.get(Logger));
await app.listen(3000);
}
bootstrap();
```
3. Configure nest-otel:
```ts
const OpenTelemetryModuleConfig = OpenTelemetryModule.forRoot({
metrics: {
hostMetrics: true, // Includes Host Metrics
apiMetrics: {
enable: true, // Includes api metrics
defaultAttributes: {
// You can set default labels for api metrics
custom: 'label',
},
ignoreRoutes: ['/favicon.ico'], // You can ignore specific routes (See https://docs.nestjs.com/middleware#excluding-routes for options)
ignoreUndefinedRoutes: false, //Records metrics for all URLs, even undefined ones
prefix: 'my_prefix', // Add a custom prefix to all API metrics
},
},
});
@Module({
imports: [OpenTelemetryModuleConfig],
})
export class AppModule {}
```
## Span Decorator
If you need, you can define a custom Tracing Span for a method. It works async or sync. Span takes its name from the parameter; but by default, it is the same as the method's name
```ts
import { Span } from 'nestjs-otel';
@Span('CRITICAL_SECTION')
async getBooks() {
return [`Harry Potter and the Philosopher's Stone`];
}
```
## Tracing Service
In case you need to access native span methods for special logics in the method block:
```ts
import { TraceService } from 'nestjs-otel';
@Injectable()
export class BookService {
constructor(private readonly traceService: TraceService) {}
@Span()
async getBooks() {
const currentSpan = this.traceService.getSpan(); // --> retrives current span, comes from http or @Span
await this.doSomething();
currentSpan.addEvent('event 1');
currentSpan.end(); // current span end
const span = this.traceService.startSpan('sub_span'); // start new span
span.setAttributes({ userId: 1 });
await this.doSomethingElse();
span.end(); // new span ends
return [`Harry Potter and the Philosopher's Stone`];
}
}
```
## Metric Service
[OpenTelemetry Metrics](https://www.npmjs.com/package/@opentelemetry/api) allow a user to collect data and export it to metrics backend like Prometheus.
```ts
import { MetricService } from 'nestjs-otel';
import { Counter } from '@opentelemetry/api';
@Injectable()
export class BookService {
private customMetricCounter: Counter;
constructor(private readonly metricService: MetricService) {
this.customMetricCounter = this.metricService.getCounter('custom_counter', {
description: 'Description for counter',
});
}
async getBooks() {
this.customMetricCounter.add(1);
return [`Harry Potter and the Philosopher's Stone`];
}
}
```
## Metric Decorators
### Metric Class Instances
If you want to count how many instance of a specific class has been created:
```ts
@OtelInstanceCounter() // It will generate a counter called: app_MyClass_instances_total.
export class MyClass {}
```
### Metric Class Method
If you want to increment a counter on each call of a specific method:
```ts
@Injectable()
export class MyService {
@OtelMethodCounter()
doSomething() {}
}
@Controller()
export class AppController {
@Get()
@OtelMethodCounter() // It will generate `app_AppController_doSomething_calls_total` counter.
doSomething() {
// do your stuff
}
}
```
### Metric Param Decorator
You have the following decorators:
- `@OtelCounter()`
- `@OtelUpDownCounter()`
- `@OtelHistogram()`
- `@OtelObservableGauge()`
- `@OtelObservableCounter()`
- `@OtelObservableUpDownCounter()`
Example of usage:
```ts
import { OtelCounter } from 'nestjs-otel';
import { Counter } from '@opentelemetry/api';
@Controller()
export class AppController {
@Get('/home')
home(
@OtelCounter('app_counter_1_inc', { description: 'counter 1 description' }) counter1: Counter
) {
counter1.add(1);
}
}
```
## API Metrics with Middleware
| Impl | Otel Metric | Prometheus Metric | Description | Metric Type |
| ---- | -------------------------------- | --------------------------------------- | ----------------------------------------- | ----------- |
| ✅ | http.server.request.count | http_server_request_count_total | Total number of HTTP requests. | Counter |
| ✅ | http.server.response.count | http_server_response_count_total | Total number of HTTP responses. | Counter |
| ✅ | http.server.abort.count | http_server_abort_count_total | Total number of data transfers aborted. | Counter |
| ✅ | http.server.duration | http_server_duration | The duration of the inbound HTTP request. | Histogram |
| ✅ | http.server.request.size | http_server_request_size | Size of incoming bytes. | Histogram |
| ✅ | http.server.response.size | http_server_response_size | Size of outgoing bytes. | Histogram |
| ✅ | http.server.response.success.count | http_server_response_success_count_total | Total number of all successful responses. | Counter |
| ✅ | http.server.response.error.count | http_server_response_error_count_total | Total number of server error responses. | Counter |
| ✅ | http.client.request.error.count | http_client_request_error_count_total | Total number of client error requests. | Counter |
## Prometheus Metrics
When `metricExporter` is defined in otel SDK with a `PrometheusExporter`it will start a new process on port `8081` (default port) and metrics will be available at `http://localhost:8081/metrics`.
## Using with a logger
### Pino with instrumentation
This approach uses otel instrumentation to automatically inject spanId and traceId.
```ts
import { PinoInstrumentation } from '@opentelemetry/instrumentation-pino';
const otelSDK = new NodeSDK({
instrumentations: [new PinoInstrumentation()],
});
```
### Pino with custom formatter
This approach uses the global trace context for injecting SpanId and traceId as a property of your structured log.
```ts
import Pino, { Logger } from 'pino';
import { LoggerOptions } from 'pino';
import { trace, context } from '@opentelemetry/api';
export const loggerOptions: LoggerOptions = {
formatters: {
log(object) {
const span = trace.getSpan(context.active());
if (!span) return { ...object };
const { spanId, traceId } = trace.getSpan(context.active())?.spanContext();
return { ...object, spanId, traceId };
},
},
};
export const logger: Logger = Pino(loggerOptions);
```
## Stargazers over time
[](https://starchart.cc/pragmaticivan/nestjs-otel)