Skip to content

Commit

Permalink
docs: update README with v5 changes
Browse files Browse the repository at this point in the history
  • Loading branch information
@overbit
overbit committed Feb 29, 2024
1 parent 48fb7cd commit 2eec4fb
Showing 1 changed file with 169 additions and 78 deletions.
247 changes: 169 additions & 78 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -110,7 +110,8 @@ export class AppModule {}
<li><code>@opentelemetry/instrumentation-dns</code> and <code>@opentelemetry/instrumentation-net</code> have been disabled to reduce noise</li>
<li> <code>@opentelemetry/instrumentation-http</code> ignores common health check endpoints and creates span with name <code>"HTTP_METHOD PATH"</code> </li>
<li><code>@opentelemetry/instrumentation-fs</code>ignores operations on files under <code>node_modules</code></li>
<li><code>@opentelemetry/instrumentation-express</code>ignores operations on files under <code>node_modules</code></li>
<li><code>@opentelemetry/instrumentation-express</code> has been disabled to reduce noise</li>
<li><code>@opentelemetry/instrumentation-graphql</code> has been configured to fit with nestjs (mergeItems: true, ignoreResolveSpans: true, ignoreTrivialResolveSpans: true) </li>
</td>
<tr>
<td> spanProcessor </td>
Expand All @@ -124,28 +125,45 @@ export class AppModule {}
</tr>
</table>

`OpenTelemetryModule.forRoot()` takes [OpenTelemetryModuleConfig](https://github.com/MetinSeylan/Nestjs-OpenTelemetry/blob/main/src/OpenTelemetryModuleConfig.ts#L25) as a parameter, this type is inherited by [NodeSDKConfiguration](https://github.com/open-telemetry/opentelemetry-js/blob/745bd5c34d3961dc73873190adc763747e5e026d/experimental/packages/opentelemetry-sdk-node/src/types.ts#:~:text=NodeSDKConfiguration) so you can use same OpenTelemetry SDK parameter.
`Tracing.init()` takes [TracingConfig](https://github.com/amplication/opentelemetry-nestjs/blob/main/src/TracingConfig.interface.ts#L3) as a parameter, this type is inherited by [NodeSDKConfiguration](https://github.com/open-telemetry/opentelemetry-js/blob/745bd5c34d3961dc73873190adc763747e5e026d/experimental/packages/opentelemetry-sdk-node/src/types.ts#:~:text=NodeSDKConfiguration) so you can use same OpenTelemetry SDK parameter.

`OpenTelemetryModule.forRoot()` takes [OpenTelemetryModuleConfig](https://github.com/amplication/opentelemetry-nestjs/blob/main/src/OpenTelemetryModuleConfig.interface.ts#L5)
---

## Distributed Tracing

Simple setup with Zipkin exporter, including with default trace instrumentations.
Simple setup with Otel exporter, including with default trace instrumentations.

The setup consists of two main changes in the `main.ts` (to initialise the provider) and in the nestjs app module.


```ts
import { OpenTelemetryModule } from '@amplication/opentelemetry-nestjs';
// main.ts
// at the very top of the file
import { Tracing } from "@amplication/opentelemetry-nestjs";
import { ZipkinExporter } from '@opentelemetry/exporter-zipkin';
import { SimpleSpanProcessor } from '@opentelemetry/sdk-trace-base';

Tracing.init({
serviceName: "my-service",
spanProcessor: new SimpleSpanProcessor(
new ZipkinExporter({
url: 'your-zipkin-url',
}),
),
});

import { NestFactory } from "@nestjs/core";

// ....
```

```ts
import { OpenTelemetryModule } from '@amplication/opentelemetry-nestjs';

@Module({
imports: [
OpenTelemetryModule.forRoot({
spanProcessor: new SimpleSpanProcessor(
new ZipkinExporter({
url: 'your-zipkin-url',
}),
),
}),
OpenTelemetryModule.forRoot(),
],
})
export class AppModule {}
Expand Down Expand Up @@ -261,26 +279,18 @@ import {
PipeInjector,
ScheduleInjector,
} from '@amplication/opentelemetry-nestjs';
import { ZipkinExporter } from '@opentelemetry/exporter-zipkin';
import { SimpleSpanProcessor } from '@opentelemetry/sdk-trace-base';

@Module({
imports: [
OpenTelemetryModule.forRoot({
traceAutoInjectors: [
OpenTelemetryModule.forRoot([
ControllerInjector,
GuardInjector,
EventEmitterInjector,
ScheduleInjector,
PipeInjector,
LoggerInjector,
],
spanProcessor: new SimpleSpanProcessor(
new ZipkinExporter({
url: 'your-zipkin-url',
}),
),
}),
),
],
})
export class AppModule {}
Expand Down Expand Up @@ -337,63 +347,76 @@ const tracedInstance = TraceWrapper.trace(instance);
Simple setup with Prometheus exporter, you need install [@opentelemetry/exporter-prometheus](https://www.npmjs.com/package/@opentelemetry/exporter-prometheus)

```ts
import { OpenTelemetryModule } from '@amplication/opentelemetry-nestjs';
// main.ts
// at the very top of the file
import { Tracing } from "@amplication/opentelemetry-nestjs";
import { PrometheusExporter } from '@opentelemetry/exporter-prometheus';

@Module({
imports: [
OpenTelemetryModule.forRoot({
serviceName: 'nestjs-opentelemetry-example',
metricReader: new PrometheusExporter({
endpoint: 'metrics',
port: 9464,
}),
}),
],
})
export class AppModule {}
Tracing.init({
serviceName: 'nestjs-opentelemetry-example',
metricReader: new PrometheusExporter({
endpoint: 'metrics',
port: 9464,
}),
});

import { NestFactory } from "@nestjs/core";
// ....
```


Now you can access Prometheus exporter with auto collected metrics [http://localhost:9464/metrics](http://localhost:9464/metrics).
Also, you can find different exporters [here](https://opentelemetry.io/docs/js/exporters/)

---

## Examples

```ts
import { Module } from '@nestjs/common';
import type { OpenTelemetryModule } from '@amplication/opentelemetry-nestjs';
// main.ts
// at the very top of the file
import { Tracing } from "@amplication/opentelemetry-nestjs";
import { PrometheusExporter } from '@opentelemetry/exporter-prometheus';
import { PrometheusExporter } from '@opentelemetry/exporter-prometheus';
import { OTLPTraceExporter } from '@opentelemetry/exporter-trace-otlp-grpc';
import { SimpleSpanProcessor } from '@opentelemetry/sdk-trace-base';
import { CompositePropagator } from '@opentelemetry/core';
import { JaegerPropagator } from '@opentelemetry/propagator-jaeger';
import { B3InjectEncoding, B3Propagator } from '@opentelemetry/propagator-b3';

Tracing.init({
serviceName: 'myservice-opentelemetry-example',
metricReader: new PrometheusExporter({
endpoint: 'metrics',
port: 9464,
}),
spanProcessor: new BatchSpanProcessor(
new OTLPTraceExporter({
url: 'your-jaeger-url',
}),
),
textMapPropagator: new CompositePropagator({
propagators: [
new JaegerPropagator(),
new B3Propagator(),
new B3Propagator({
injectEncoding: B3InjectEncoding.MULTI_HEADER,
}),
],
}),
});

import { NestFactory } from "@nestjs/core";
// ....
```

```ts
// ... app.module.ts
import { Module } from '@nestjs/common';
import { OpenTelemetryModule } from '@amplication/opentelemetry-nestjs';

@Module({
imports: [
OpenTelemetryModule.forRoot({
serviceName: 'myservice-opentelemetry-example',
metricReader: new PrometheusExporter({
endpoint: 'metrics',
port: 9464,
}),
spanProcessor: new BatchSpanProcessor(
new OTLPTraceExporter({
url: 'your-jaeger-url',
}),
),
textMapPropagator: new CompositePropagator({
propagators: [
new JaegerPropagator(),
new B3Propagator(),
new B3Propagator({
injectEncoding: B3InjectEncoding.MULTI_HEADER,
}),
],
}),
}),
OpenTelemetryModule.forRoot(),
],
})
export class AppModule {}
Expand All @@ -406,11 +429,9 @@ For the integration with AWS X-Ray, follow the official instructions.
i.e.

```ts
import { Module } from '@nestjs/common';
import type {
OpenTelemetryModule,
OpenTelemetryModuleDefaultConfig,
} from '@amplication/opentelemetry-nestjs';
// main.ts
// at the very top of the file
import { Tracing } from "@amplication/opentelemetry-nestjs";
import { PrometheusExporter } from '@opentelemetry/exporter-prometheus';
import { OTLPTraceExporter } from '@opentelemetry/exporter-trace-otlp-grpc';
import { SimpleSpanProcessor } from '@opentelemetry/sdk-trace-base';
Expand All @@ -419,26 +440,96 @@ import { AWSXRayPropagator } from '@opentelemetry/propagator-aws-xray';
import { AWSXRayIdGenerator } from '@opentelemetry/id-generator-aws-xray';
import { AwsInstrumentation } from '@opentelemetry/instrumentation-aws-sdk';

Tracing.init({
serviceName: 'myservice-opentelemetry-example',
metricReader: new PrometheusExporter({
endpoint: 'metrics',
port: 9464,
}),
instrumentations: [
...OpenTelemetryModuleDefaultConfig.instrumentations,
new AwsInstrumentation({
suppressInternalInstrumentation: true,
sqsExtractContextPropagationFromPayload: true,
}),
],
idGenerator: new AWSXRayIdGenerator(),
spanProcessor: new BatchSpanProcessor(new OTLPTraceExporter({})),
textMapPropagator: new AWSXRayPropagator(),
});

import { NestFactory } from "@nestjs/core";
// ....
```

```ts
// ... app.module.ts
import { Module } from '@nestjs/common';
import { OpenTelemetryModule } from '@amplication/opentelemetry-nestjs';

@Module({
imports: [
OpenTelemetryModule.forRoot(),
],
})
export class AppModule {}
```


## Migrating to v5
In v5, the initialisation method for this library changed to support all the opentelemetry auto-instrumentation libraries like `@opentelemetry/instrumentation-graphql`.
In v4 some of them where not working due to the fact that they were imported after the targeting library, `graphql` lib in the case of `@opentelemetry/instrumentation-graphql`.

### v4
```ts
import { NestFactory } from "@nestjs/core";
// ....
```

```ts
// app.module.ts
import { OpenTelemetryModule } from '@amplication/opentelemetry-nestjs';
import { ControllerInjector } from '@amplication/opentelemetry-nestjs';

@Module({
imports: [
OpenTelemetryModule.forRoot({
serviceName: 'myservice-opentelemetry-example',
metricReader: new PrometheusExporter({
endpoint: 'metrics',
port: 9464,
}),
instrumentations: [
...OpenTelemetryModuleDefaultConfig.instrumentations,
new AwsInstrumentation({
suppressInternalInstrumentation: true,
sqsExtractContextPropagationFromPayload: true,
}),
],
idGenerator: new AWSXRayIdGenerator(),
spanProcessor: new BatchSpanProcessor(new OTLPTraceExporter({})),
textMapPropagator: new AWSXRayPropagator(),
serviceName: 'my-service',
spanProcessor: new SimpleSpanProcessor(),
traceAutoInjectors: [ControllerInjector],
}),
],
})
export class AppModule {}
```

### v5
```ts
// main.ts
// at the very top of the file
import { Tracing } from "@amplication/opentelemetry-nestjs";
import { SimpleSpanProcessor } from '@opentelemetry/sdk-trace-base';

Tracing.init({
serviceName: "my-service",
spanProcessor: new SimpleSpanProcessor(),
});

import { NestFactory } from "@nestjs/core";
// ....
```

```ts
// app.module.ts
import { OpenTelemetryModule } from '@amplication/opentelemetry-nestjs';
import { ControllerInjector } from "@amplication/opentelemetry-nestjs";

@Module({
imports: [
OpenTelemetryModule.forRoot([
ControllerInjector
]),
],
})
export class AppModule {}
```

0 comments on commit 2eec4fb

Please sign in to comment.