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 apitoolkit-adonis @opentelemetry/api  @opentelemetry/auto-instrumentations-node

Open Telemetery 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.

# Specifies the endpoint URL for the OpenTelemetry collector.
export OTEL_EXPORTER_OTLP_ENDPOINT="http://otelcol.apitoolkit.io:4317"
# Specifies the name of the service.
export OTEL_SERVICE_NAME=""
# Adds your API KEY to the resource.
export OTEL_RESOURCE_ATTRIBUTES=at-project-key="z6BJfZVEOSozztMfhqZsGTpG9DiXT9Weurvk1bpe9mwF8orB"
# Specifies the protocol to use for the OpenTelemetry exporter.
export OTEL_EXPORTER_OTLP_PROTOCOL="grpc"

export NODE_OPTIONS="--require @opentelemetry/auto-instrumentations-node/register"
npm run dev

Setup APIToolkit Adonis Middleware For HTTP Request Monitoring

APIToolkit Adonis Middleware is a middleware that can be used to monitor HTTP requests. It is a wrapper around the Express.js middleware and provides additional functionalities on top of the open telemetry instrumentation which creates a custom span for each request capturing details about the request including request and response bodies.

First configure the apitoolkit-adonis sdk by running the following command:

node ace configure apitoolkit-adonis

Then, create an apitoolkit.js|ts file in the /conf directory and export the defineConfig object with some properties like so:

import { defineConfig } from "apitoolkit-adonis";
import axios from "axios";

export default defineConfig({
  captureResponseBody: true,
  serviceName: "my-service",
  monitorAxios: axios, // Optional: Use this to monitor all axios requests from your server
});

Then, register the middleware by adding the apitoolkit-adonis client to your global middleware list in the start/kernel.js|ts file like so:

import server from "@adonisjs/core/services/server";
import APIToolkit from "apitoolkit-adonis";

const client = new APIToolkit();

server.use([
  () => import("#middleware/container_bindings_middleware"),
  () => import("#middleware/force_json_response_middleware"),
  () => import("@adonisjs/cors/cors_middleware"),
  () => client.middleware(),
]);

Quick overview of the configuration parameters

An object with the following optional fields can be passed to the defineConfig function in conf/apitoolkit.ts to configure it:

Error Reporting

With APItoolkit, you can track and report different unhandled or uncaught errors, API issues, and anomalies at different parts of your application. This will help you associate more detail and context from your backend with any failing customer request.

To report errors, you need to first enable asyncLocalStorage in your AdonisJS project by setting useAsyncLocalStorage to true in your config/app.js|ts file, like so:

export const http = defineConfig({
  useAsyncLocalStorage: true,
  // Other configs...
});

Then, use the reportError() function in your application's exception handler, passing in the error argument, to report all uncaught errors and service exceptions that happened during a request, like so:

import { HttpContext, ExceptionHandler } from "@adonisjs/core/http";
import { reportError } from "apitoolkit-adonis";

export default class HttpExceptionHandler extends ExceptionHandler {
  async handle(error: unknown, ctx: HttpContext) {
    return super.handle(error, ctx);
  }

  async report(error: unknown, ctx: HttpContext) {
    // Automatically report all uncaught errors to APItoolkit
    reportError(error);
    return super.report(error, ctx);
  }
}

Manual Error Reporting

You can also manually report errors to APIToolkit by calling the reportError() function, passing in the error argument, like so:

import router from "@adonisjs/core/services/router";
import { reportError } from "apitoolkit-adonis";
router.get("/", async () => {
  try {
    throw new Error("something went wrong");
    return res.data;
  } catch (error) {
    // report the error to APIToolkit
    reportError(error);
    return { message: "something went wrong" };
  }
});

Monitoring Axios requests

APIToolkit supports monitoring outgoing HTTP requests made using libraries like Axios. This can be done either globally or on a per-request basis.

Global monitoring

To monitor all outgoing Axios requests globally, you can use the monitorAxios option when initializing the APIToolkit client.

import { defineConfig } from "apitoolkit-adonis";
import axios from "axios";

export default defineConfig({
  captureResponseBody: true,
  serviceName: "my-service",
  monitorAxios: axios, // Optional: Use this to monitor all axios requests from your server
});

By adding monitorAxios to config, all axios requests in your server will be monitored by APIToolkit.

Per-request monitoring

To monitor a specific Axios request, you can use the observeAxios function provided by the SDK.

import router from "@adonisjs/core/services/router";
import { observeAxios } from "apitoolkit-adonis";
import axios from "axios";
router.get("/", async () => {
  const res = await observeAxios({
    urlWildcard: "/todos/:todoId",
  }).get("https://jsonplaceholder.typicode.com/todos/1");
  return res.data;
});

The urlWildcard parameter is used for urls that contain dynamic path parameters. This helps APIToolkit to identify request to the same endpoint but with different parameters.

All observeAxios options

Below is the full list of options for the observeAxios function:

Example

import router from "@adonisjs/core/services/router";
import { observeAxios } from "apitoolkit-adonis";
import axios from "axios";
router.get("/", async () => {
  const res = await observeAxios({
    axiosInstance: axios,
    urlWildcard: "/todos/:todoId"
    redactHeaders: ["Authorization"],
    redactResponseBody: ["$.credit_card_number"],
    redactRequestBody: ["$.password"]
  }).get("https://jsonplaceholder.typicode.com/todos/1");
  return res.data;
});