# OpenTelemetry AdonisJS Instrumentation for Node.js

[![NPM Published Version][npm-img]][npm-url]
[![Apache License][license-image]][license-image]

This module provides automatic instrumentation for the [AdonisJS framework][pkg-web-url] module, which may be loaded using the [`@opentelemetry/sdk-trace-node`](https://github.com/open-telemetry/opentelemetry-js/tree/main/packages/opentelemetry-sdk-trace-node) package.

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

## Installation

```bash
npm install --save @revai-care/instrumentation-adonisjs-6
```

## Usage

OpenTelemetry AdonisJS Instrumentation allows the user to automatically collect trace data from the request handlers, middleware, and error handling within AdonisJS applications, and export them to the backend of choice.

To load the AdonisJS instrumentation, specify it in the registerInstrumentations configuration.

```
const { NodeTracerProvider } = require('@opentelemetry/sdk-trace-node');
const { AdonisInstrumentation } = require('@my-company/instrumentation-adonisjs');
const { registerInstrumentations } = require('@opentelemetry/instrumentation');

const provider = new NodeTracerProvider();
provider.register();

registerInstrumentations({
  instrumentations: [
    new AdonisInstrumentation(),
  ],
});
```

## Emitted Spans

| Name                            | `adonisjs.type`     | Description                                         | Included attributes                               |
| ------------------------------- | ------------------- | --------------------------------------------------- | ------------------------------------------------- |
| `request handler - <route>`     | `request_handler`   | Traces the execution of a request handler.          | `http.*`, `adonisjs.namespace`, `adonisjs.method` |
| `middleware - <middlewareName>` | `middleware`        | Traces the execution of middleware.                 | `http.*`, `adonisjs.namespace`, `adonisjs.method` |
| `ExceptionHandler.report`       | `exception_handler` | Traces the error reporting by the ExceptionHandler. | `http.*`, `adonisjs.namespace`, `adonisjs.method` |

## Semantic Conventions

This package uses @opentelemetry/semantic-conventions version 1.27+, which implements Semantic Convention Version 1.7.0.

## Semantic conventions

This package uses `@opentelemetry/semantic-conventions` version `1.22+`, which implements Semantic Convention [Version 1.7.0](https://github.com/open-telemetry/opentelemetry-specification/blob/v1.7.0/semantic_conventions/README.md)

Attributes collected:

| Attribute            | Short Description                                             |
| -------------------- | ------------------------------------------------------------- |
| `component`\*        | "@adonisjs/core"                                              |
| `adonisjs.version`\* | Version of instrumented `@adonisjs/core` package              |
| `adonisjs.type`\*    | See [AdonisType](./src/enums/AdonisType.ts)                   |
| `adonisjs.namespace` | Class name of the handler or middleware.                      |
| `adonisjs.method`    | Name of the method executed within the handler or middleware. |
| `http.method`        | HTTP method                                                   |
| `http.url`           | Full request URL                                              |
| `http.route`         | Route assigned to handler. Ex: `/users/:id`                   |
| `http.path`          | Route pattern. Ex: `/users/:id`                               |

\* included in all of the spans.

## Useful links

- For more information on OpenTelemetry, visit: <https://opentelemetry.io/>
- For more about OpenTelemetry JavaScript: <https://github.com/open-telemetry/opentelemetry-js>