Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/jufab/opentelemetry-angular-interceptor

An Angular Module for easely deploying OpenTelemetry
https://github.com/jufab/opentelemetry-angular-interceptor

angular observability opentelemetry tracing

Last synced: 2 days ago
JSON representation

An Angular Module for easely deploying OpenTelemetry

Awesome Lists containing this project

README 

        
# OpenTelemetry Angular Interceptor



@jufab/opentelemetry-angular-interceptor is an Angular Library to deploy [OpenTelemetry](https://opentelemetry.io/) in your Angular application



This library uses [opentelemetry-js package](https://github.com/open-telemetry/opentelemetry-js)



**Use Angular >= 13.0.0**



More info : https://jufab.github.io/opentelemetry-angular-interceptor/



[![npm version](https://badge.fury.io/js/%40jufab%2Fopentelemetry-angular-interceptor.svg)](https://badge.fury.io/js/%40jufab%2Fopentelemetry-angular-interceptor)

[![codecov](https://codecov.io/gh/jufab/opentelemetry-angular-interceptor/branch/master/graph/badge.svg)](https://codecov.io/gh/jufab/opentelemetry-angular-interceptor)



## Table of contents



- [OpenTelemetry Angular Interceptor](#opentelemetry-angular-interceptor)

  - [Table of contents](#table-of-contents)

  - [Getting started](#getting-started)

    - [Content](#content)

    - [Installation](#installation)

    - [Configuration](#configuration)

      - [Example global Configuration](#example-global-configuration)

      - [Common Configuration](#common-configuration)

      - [BatchSpanProcessor Configuration](#batchspanprocessor-configuration)

      - [OpenTelemetry-collector Configuration](#opentelemetry-collector-configuration)

      - [Jaeger Propagator Configuration](#jaeger-propagator-configuration)

      - [Zipkin Exporter Configuration](#zipkin-exporter-configuration)

      - [B3 Propagator Configuration](#b3-propagator-configuration)

      - [Ignore URL Configuration](#ignore-url-configuration)

      - [External Configuration](#external-configuration)

    - [Angular module](#angular-module)

      - [Commons Module](#commons-module)

        - [Exporter module](#exporter-module)

        - [Propagator module](#propagator-module)

      - [Interceptor Module](#interceptor-module)

      - [Instrumentation Module](#instrumentation-module)

      - [Interceptor Module And Instrumentation Module](#interceptor-module-and-instrumentation-module)

      - [Injection token](#injection-token)

    - [(Optional) Logging in OtelColExporterModule](#optional-logging-in-otelcolexportermodule)

      - [NGXLogger](#ngxlogger)

    - [(Optional) Add span attributes during interception](#optional-add-span-attributes-during-interception)

  - [How it works](#how-it-works)

  - [Example](#example)

    - [Run](#run)

      - [Interceptor](#interceptor)

      - [Instrumentation](#instrumentation)

    - [\[Optional\] Result in OpenTelemetry-collector](#optional-result-in-opentelemetry-collector)

  - [Troubleshoot](#troubleshoot)

    - [Angular 10 Warning](#angular-10-warning)

    - [Other](#other)



## Getting started



### Content



This library offers two possibilities to use it in Angular App : 

- **Interceptor** : catch every external call with the HttpClient from angular

- **Instrumentation** : use instrumentation from opentelemetry-js with web plugins _(You need to install and configure it)_ like : 

  - [@opentelemetry/instrumentation-document-load](hhttps://github.com/open-telemetry/opentelemetry-js-contrib/tree/main/plugins/web/opentelemetry-instrumentation-document-load)

  - [@opentelemetry/instrumentation-fetch](https://github.com/open-telemetry/opentelemetry-js/tree/main/experimental/packages/opentelemetry-instrumentation-fetch)

  - [@opentelemetry/instrumentation-xml-http-request](https://github.com/open-telemetry/opentelemetry-js/tree/main/experimental/packages/opentelemetry-instrumentation-xml-http-request)

  - ...

  



### Installation



With npm :



```

npm i @jufab/opentelemetry-angular-interceptor

```



### Configuration



Use the "OpentelemetryConfig" interface to configure the Tracer



```typescript

export interface OpenTelemetryConfig {

  commonConfig: CommonCollectorConfig;

  batchSpanProcessorConfig?: BatchSpanProcessorConfig;

  otelcolConfig?: OtelCollectorConfig;

  jaegerPropagatorConfig?: JaegerPropagatorConfig;

  zipkinConfig?: ZipkinCollectorConfig;

  b3PropagatorConfig?: B3PropagatorConfig;

  ignoreUrls?: IgnoreUrlsConfig;

}

```



#### Example global Configuration



_From the interceptor-example_



```typescript

opentelemetryConfig: {

    commonConfig: {

      console: true, //(boolean) Display trace on console

      production: false, //(boolean) Send trace with BatchSpanProcessor (true) or SimpleSpanProcessor (false)

      logBody: true, //(boolean) true add body in a log, nothing otherwise

      serviceName: 'interceptor-example', //Service name send in trace

      resourceAttributes: { // extra resource attributes like service.namespace

        [ATTR_SERVICE_NAMESPACE]: 'namespace'

      },

      probabilitySampler: '0.7', //Samples a configurable percentage of traces, string value between '0' to '1'

      logLevel:DiagLogLevel.ALL //(Enum) DiagLogLevel is an Enum from @opentelemetry/api

    },

    batchSpanProcessorConfig: { //Only if production = true in commonConfig

      maxQueueSize: '2048', // The maximum queue size. After the size is reached spans are dropped.

      maxExportBatchSize: '512', // The maximum batch size of every export. It must be smaller or equal to maxQueueSize.

      scheduledDelayMillis: '5000', // The interval between two consecutive exports

      exportTimeoutMillis: '30000', // How long the export can run before it is cancelled

    },

    otelcolConfig: {

      url: 'http://localhost:4318/v1/traces', //URL of opentelemetry collector

    },

    jaegerPropagatorConfig: {

      customHeader: 'custom-header',

    }

  }

```



_From the instrumentation-example_



```typescript

backendApp.get('/api/config', (req,res) => {

  return res.status(200).send({

    commonConfig: {

      console: true, // Display trace on console

      production: true, // Send Trace with BatchSpanProcessor (true) or SimpleSpanProcessor (false)

      serviceName: 'instrumentation-example', // Service name send in trace

      resourceAttributes: { // extra resource attributes like service.namespace

        'service.namespace': 'namespace'

      },

      probabilitySampler: '0.75', // 75% sampling

      logLevel: 99 //ALL Log, DiagLogLevel is an Enum from @opentelemetry/api

    },

    otelcolConfig: {

      url: 'http://localhost:4318/v1/traces', // URL of opentelemetry collector

    }

  });

})



```



#### Common Configuration

 

 * console: (boolean) Display trace on console if true

 * production: (boolean)Send trace via BatchSpanProcessor (Async) or SimpleSpanProcessor (Sync) : It's recommend to use BatchSpanProcessor on Production.

 * serviceName: (string) Service name in your trace

 * resourceAttributes: list of extra resource attributes

 * probabilitySampler: (string) Samples a configurable percentage of traces, value between 0 to 1

 * logBody: (boolean) true add body in a log, nothing otherwise

 * logLevel: (DiagLogLevel) log level



#### BatchSpanProcessor Configuration



_This configuration applies if production is true in commonConfig._



* maxQueueSize: (string) The maximum queue size. After the size is reached spans are dropped.

* maxExportBatchSize: (string) The maximum batch size of every export. It must be smaller or equal to maxQueueSize.

* scheduledDelayMillis: (string) The interval between two consecutive exports

* exportTimeoutMillis: (string) How long the export can run before it is cancelled



#### OpenTelemetry-collector Configuration



* url: (string) url of opentelemetry collector (default : http://localhost:4318/v1/traces)

* headers: list of custom header (more info: https://github.com/open-telemetry/opentelemetry-js/tree/main/experimental/packages/exporter-trace-otlp-http)

* concurrencyLimit (string) : An optional limit on pending requests (more info : https://github.com/open-telemetry/opentelemetry-js/tree/main/experimental/packages/exporter-trace-otlp-http)

* timeoutMillis (string): Maximum time the OTLP exporter will wait for each batch export. The default value is 10000ms (more info : https://github.com/open-telemetry/opentelemetry-js/tree/main/experimental/packages/exporter-trace-otlp-http)



#### Jaeger Propagator Configuration



* customHeader: (string) custom header (more info : https://github.com/open-telemetry/opentelemetry-js/tree/main/packages/opentelemetry-propagator-jaeger)



#### Zipkin Exporter Configuration



* url: (string) url of zipkin collector (default : http://localhost:9411/api/v2/spans)

* headers: list of custom header (more info : https://github.com/open-telemetry/opentelemetry-js/tree/main/packages/opentelemetry-exporter-zipkin)



#### B3 Propagator Configuration



* multiHeader : (string) Single or Multi Header for b3propagator (default: multi). Value : 'O' (single), '1' (multi) (more info: https://github.com/open-telemetry/opentelemetry-js/tree/main/packages/opentelemetry-propagator-b3)



#### Ignore URL Configuration



* urls : (Array) URLs that partially match any regex in ignoreUrls will not be traced. In addition, URLs that are _exact matches_ of strings in ignoreUrls will also not be traced



#### External Configuration



Instrumentation example project have an external configuration to show how you can do it.



### Angular module



You need 3 modules to add to your application.



- [Exporter Module](#exporter-module) : to define type and export of traces.

- [Propagator Module](#propagator-module) : to define propagation in your HTTP header.

- Last Module, 2 choices :  

  - [OpenTelemetryInterceptorModule](#interceptor-module) : to activate interceptor in all your http call.

  - [OtelWebTracerModule](#instrumentation-module) : to activate instrumentation (you need a component to activate it, see [Component otel-instrumentation](#component-otel-instrumentation)).



#### Commons Module



You add this modules in your application module (generally app.module.ts)



##### Exporter module



There is 4 exporters:



* NoopSpanExporterModule : This a fake exporter

* OtelColExporterModule : OpenTelemetry exporter (more info : https://github.com/open-telemetry/opentelemetry-js/tree/main/experimental/packages/opentelemetry-exporter-trace-otlp-http)

* ConsoleSpanExporterModule : Console Exporter

* ZipkinExporterModule : Zipkin Exporter (more info : https://github.com/open-telemetry/opentelemetry-js/tree/main/packages/opentelemetry-exporter-zipkin)



##### Propagator module



there is 6 propagators (more info about propagator: https://github.com/open-telemetry/opentelemetry-js/tree/main/packages/opentelemetry-core)

* NoopHttpTextPropagatorModule : This is a fake propagator

* B3PropagatorModule : Use B3 propagator

* W3CTraceContextPropagatorModule : Use W3CTraceContext propagator

* JaegerHttpTracePropagatorModule : Use JaegerHttpPropagator (more info about this one: https://github.com/open-telemetry/opentelemetry-js/tree/main/packages/opentelemetry-propagator-jaeger)

* AwsXrayPropagatorModule : Use AWS X-Ray propagator

* CompositePropagatorModule : use all of the propagator



#### Interceptor Module



Just add OpenTelemetryInterceptorModule to insert Interceptor



```typescript

import { NgModule } from '@angular/core';

...

import { AppComponent } from './app.component';

import { HttpClientModule } from '@angular/common/http';

import { OpenTelemetryInterceptorModule, OtelColExporterModule, CompositePropagatorModule } from '@jufab/opentelemetry-angular-interceptor';

import { environment } from '../environments/environment';

...



@NgModule({

  declarations: [AppComponent, ...],

  imports: [

    ...

    HttpClientModule,

    //Insert module OpenTelemetryInterceptorModule with configuration, HttpClientModule is used for interceptor

    OpenTelemetryInterceptorModule.forRoot(environment.opentelemetryConfig),

    //Insert OtelCol exporter module

    OtelColExporterModule,

    //Insert propagator module

    CompositePropagatorModule,

    ...

  ],

  providers: [],

  bootstrap: [AppComponent],

})

export class AppModule {}

```



#### Instrumentation Module



Declare this OtelWebTracerModule to configure instrumentation.



You need to provide Web instrumentation on the `OTEL_INSTRUMENTATION_PLUGINS` token in providers section of NgModule



_Example in instrumentation-example project_



```typescript

...

import { OtelColExporterModule, CompositePropagatorModule, OtelWebTracerModule } from 'projects/opentelemetry-interceptor/src/public-api';

...



@NgModule({

  declarations: [AppComponent, ...],

  imports: [

    ...

    // OtelCol Exporter Module

    OtelColExporterModule,

    // Composite Propagator Module

    CompositePropagatorModule,

    // OtelWebTracerModule to configure instrumentation component.

    OtelWebTracerModule.forRoot(environment.openTelemetryConfig),

    ...

  ],

  providers: [

    {provide: OTEL_INSTRUMENTATION_PLUGINS, useValue: [new XMLHttpRequestInstrumentation()]}

  ],

  bootstrap: [AppComponent],

})

export class AppModule { }



```



*This module uses APP_INITIALIZER token to load instrumentation (multi:true). No component needs now*



#### Interceptor Module And Instrumentation Module



`Don't use them at the same time : you're going to have the same trace twice.`



#### Injection token



This library exposes injection token.

You can use them to override or customize. 



* OTEL_EXPORTER : token to inject an implementation of `IExporter`

* OTEL_PROPAGATOR : token to inject an implementation of `IPropagator`

* OTEL_CONFIG : token to inject an `OpenTelemetryConfig`

* OTEL_INSTRUMENTATION_PLUGINS : token to inject an `InstrumentationOption` array

* OTEL_LOGGER : more info in [(Optional) Logging in OtelColExporterModule](#optional-logging-in-otelcolexportermodule)

* OTEL_CUSTOM_SPAN : more infor in [(Optional) Add span attributes during interception](#optional-add-span-attributes-during-interception)



### (Optional) Logging in OtelColExporterModule



You can add a logger to the [OtelColExporterModule](projects/opentelemetry-interceptor/src/lib/services/exporter/otelcol/otelcol-exporter.module.ts) with the [OTEL_LOGGER](projects/opentelemetry-interceptor/src/lib/configuration/opentelemetry-config.ts) token.



You can use a custom logger which implements the [DiagLogger](https://open-telemetry.github.io/opentelemetry-js-api/enums/diagloglevel.html) in @opentelemetry/api.



Or, you can use an existing logger which implements the same functions (error, warn, info, debug) like [ngx-logger](https://www.npmjs.com/package/ngx-logger).



#### NGXLogger



You can use [ngx-logger](https://www.npmjs.com/package/ngx-logger).



In your [appModule](projects/example-app/src/app/app.module.ts), insert LoggerModule and configure it



```typescript

@NgModule({

  ...

  imports: [

    LoggerModule.forRoot(environment.loggerConfig),

  ]

  ...

```

And use OTEL_LOGGER token to inject NGXLogger

```typescript

@NgModule({

  ...

  providers: [

    ...

    { provide: OTEL_LOGGER, useExisting: NGXLogger }

    ...

  ]

```



Don't forget to set "logLevel" in [Common Configuration](#common-configuration) (Level must be the same between NGXLogger and common configuration)



> You can see an example in the [interceptor-example](#example).



### (Optional) Add span attributes during interception



_This option is only available for Interceptor Module_



Implement a [`CustomSpan`](projects/opentelemetry-interceptor/src/lib/interceptor/custom-span.interface.ts) and the method `add(span: Span, request: HttpRequest, response: HttpResponse | HttpErrorResponse): Span`



- span : Current span, you can set or get attributes

- request : Current request in interceptor

- response : Current response in interceptor 



Implement CustomSpan class like : 



```typescript

class CustomSpanImpl implements CustomSpan {

  add(span: Span, request: HttpRequest, response: HttpResponse | HttpErrorResponse): Span {

    span.setAttribute('mycustom.key', request.params + ";" + response.status);

    return span;

  }

}

```



Inject it in you App module with `OTEL_CUSTOM_SPAN` :



```typescript

@NgModule({

  ...

  providers: [

    ...

    { provide: OTEL_CUSTOM_SPAN, useClass: CustomSpanImpl }

    ...

  ]

```



> You can see an example in the [interceptor-example](#example).



## How it works



This library is based on [HttpClientModule](https://angular.io/api/common/http/HttpClientModule) and the [HTTP_INTERCEPTORS](https://angular.io/api/common/http/HTTP_INTERCEPTORS)



OpenTelemetryInterceptor implement an [HttpInterceptor](https://angular.io/api/common/http/HttpInterceptor) and the intercept method.



This implementation initialise a [WebTracerProvider](https://github.com/open-telemetry/opentelemetry-js/blob/main/packages/opentelemetry-web/src/WebTracerProvider.ts), create a [Span](https://open-telemetry.github.io/opentelemetry-js/interfaces/span.html) and add [header propagation](https://open-telemetry.github.io/opentelemetry-js/interfaces/textmappropagator.html) in the current call.



> The response body is adding by an event in span.



## Example



This project has two example Angular Application:



- [projects/interceptor-example](projects/interceptor-example)

- [projects/instrumentation-example](projects/instrumentation-example)



You can see how configure and insert all modules.



You can althought test __opentelemetry-angular-interceptor__ with this two applications.



### Run



#### Interceptor



To start this Interceptor example application, run command :



```

npm run start:complete-interceptor-example

```



and open the application at http://localhost:4200



#### Instrumentation



To start this Instrumentation example application, run command :



```

npm run start:complete-instrumentation-example

```



and open the application at http://localhost:4200



### [Optional] Result in OpenTelemetry-collector



If you want to see the result in a collector *, there's a docker-compose available in this project.



You can start it with this command :



```

docker-compose -f collector/docker-compose.yaml up -d

```



Go to the jaeger application (http://localhost:16686) to see result.



More info about the collector here : https://github.com/open-telemetry/opentelemetry-collector



> _* without an Agent or a Collector you can see an error in your browser about sending a "trace"._



## Troubleshoot



### Angular 10 Warning



```shell

WARNING in xxx/fesm2015/jufab-opentelemetry-angular-interceptor.js depends on '@opentelemetry/web'. CommonJS or AMD dependencies can cause optimization bailouts.

For more info see: https://angular.io/guide/build#configuring-commonjs-dependencies



WARNING in xxx/fesm2015/jufab-opentelemetry-angular-interceptor.js depends on '@opentelemetry/core'. CommonJS or AMD dependencies can cause optimization bailouts.

For more info see: https://angular.io/guide/build#configuring-commonjs-dependencies



WARNING in xxx/fesm2015/jufab-opentelemetry-angular-interceptor.js depends on '@opentelemetry/tracing'. CommonJS or AMD dependencies can cause optimization bailouts.

For more info see: https://angular.io/guide/build#configuring-commonjs-dependencies



WARNING in xxx/fesm2015/jufab-opentelemetry-angular-interceptor.js depends on '@opentelemetry/api'. CommonJS or AMD dependencies can cause optimization bailouts.

For more info see: https://angular.io/guide/build#configuring-commonjs-dependencies



WARNING in xxx/fesm2015/jufab-opentelemetry-angular-interceptor.js depends on '@opentelemetry/exporter-collector/build/src/platform/browser'. CommonJS or AMD dependencies can cause optimization bailouts.

For more info see: https://angular.io/guide/build#configuring-commonjs-dependencies

```



Add to your angular.json



```json

"options": {

  "allowedCommonJsDependencies": [

    "@opentelemetry/api",

    "@opentelemetry/exporter-collector",

    "@opentelemetry/exporter-zipkin",

    "@opentelemetry/tracing",

    "@opentelemetry/web",

    "@opentelemetry/core",

    "@opentelemetry/propagator-jaeger",

    "@opentelemetry/propagator-b3",

    "@opentelemetry/instrumentation",

    "@opentelemetry/instrumentation-xml-http-request",

    "@opentelemetry/instrumentation-document-load",

    "@opentelemetry/instrumentation-fetch",

    "@opentelemetry/context-zone-peer-dep"

  ],

```



### Other



|Error|Fix|

|-----|---|

|error TS2694: Namespace 'NodeJS' has no exported member 'Timeout'.|Need dependence @type/node >= 12.0.2|

|error TS1086: An accessor cannot be declared in an ambient context.|Need dependence typescript >= 3.6.0|