AdonisJs Integration Guide

You can integrate your AdonisJs application with APIToolkit using OpenTelemetry. This allows you to send logs, metrics, and traces to APIToolkit for monitoring and analytics.

To get started, you'll need the OpenTelemetry Node.js library and some basic configuration.

Prerequisites

Ensure you have completed the first three steps of the onboarding guide.

Installation

Run the command below to install the API, SDK, and Instrumentation tools.


npm install --save @opentelemetry/api \
    @opentelemetry/auto-instrumentations-node

# Or

yarn add @opentelemetry/api @opentelemetry/auto-instrumentations-node

Configuration

This module is highly configurable by setting environment variables. So many aspects of the auto instrumentation’s behavior such as Resource detectors, Exporters, Trace context propagation headers, and many more can be configured based on your needs.

There are generally two ways to go about this from the command line:

Using the env keyword
Using the export keyword

For demonstration, I will be using the OpenSource AdonisJs project on GitHub as an example.

1. Using the `env` keyword

env OTEL_TRACES_EXPORTER=otlp \
    OTEL_EXPORTER_OTLP_ENDPOINT=http://otelcol.apitoolkit.io:4317 \
    OTEL_SERVICE_NAME=your-service-name \
    OTEL_LOGS_EXPORTER=otlp \
    OTEL_RESOURCE_ATTRIBUTES=at-project-key=z6BJfZVEOSozztMfhqZsGTpG9DiXT9Weurvk1bpe9mwF8orB \
    OTEL_EXPORTER_OTLP_PROTOCOL=grpc \
    OTEL_PROPAGATORS=baggage,tracecontext \
node --require @opentelemetry/auto-instrumentations-node/register
npm run dev

2. Using the `export` keyword

export OTEL_TRACES_EXPORTER="otlp"
export OTEL_EXPORTER_OTLP_ENDPOINT="http://otelcol.apitoolkit.io:4317"
export OTEL_NODE_RESOURCE_DETECTORS="env,host,os"
export OTEL_SERVICE_NAME="your-service-name"
export OTEL_RESOURCE_ATTRIBUTES=at-project-key="z6BJfZVEOSozztMfhqZsGTpG9DiXT9Weurvk1bpe9mwF8orB"
export OTEL_EXPORTER_OTLP_PROTOCOL="grpc"
export OTEL_PROPAGATORS="baggage,tracecontext"
export NODE_OPTIONS="--require @opentelemetry/auto-instrumentations-node/register"
npm run dev

If you are wondering what the difference is, it's this:

The first method, env sets them only for the immediate command execution.

The second method, exports, sets the variables globally for the current terminal session.

Quick overview of the configuration parameters

Attribute	Description
`OTEL_EXPORTER_OTLP_ENDPOINT`	Specifies the endpoint URL for the OpenTelemetry collector. In this case, it's set to "http://otelcol.apitoolkit.io:4317".
`OTEL_NODE_RESOURCE_DETECTORS`	Defines which resource detectors to use. Here, it's set to detect environment variables, host information, and operating system details.
`OTEL_SERVICE_NAME`	Sets the name of your service. You should replace "your-service-name" with the actual name of your service.
`OTEL_RESOURCE_ATTRIBUTES`	Specifies additional resource attributes. In this case, it's setting an API Toolkit project key.
`OTEL_EXPORTER_OTLP_PROTOCOL`	Defines the protocol used for exporting telemetry data. It's set to "grpc" (gRPC protocol).
`OTEL_PROPAGATORS`	Specifies which context propagators to use. Here, it's set to use both "baggage" and "tracecontext".
`NODE_OPTIONS`	Sets Node.js options. In this case, it's requiring the OpenTelemetry auto-instrumentation module for Node.js.

Tips

At the moment, only Traces are supported for environment variable configuration. See the open issues for Metrics and Logs to learn more.
By default, all SDK resource detectors are enabled. However, you can customize this by setting the OTEL_NODE_RESOURCE_DETECTORS environment variable to activate specific detectors or disable them entirely.