From Zero to Observability in 15 Minutes

In this tutorial, we'll take a vanilla Express API from zero observability to full traces, metrics, and structured logs in about 15 minutes. By the end, you'll be able to see every request flowing through your system.

Prerequisites

You'll need Node.js 18+, an aiAxonIQ account (free tier works), and a basic Express app. If you don't have one, scaffold one with npx create-express-app my-api.

Step 1: Install the SDK

aiAxonIQ is OpenTelemetry-native, so you instrument with the standard OTel packages — no proprietary agent:

npm install @opentelemetry/sdk-node \
  @opentelemetry/auto-instrumentations-node \
  @opentelemetry/exporter-trace-otlp-http

Step 2: Configure the SDK

Create a file called instrumentation.ts (or .js) at the root of your project — this must be loaded before anything else. Point the OTLP exporter at aiAxonIQ and pass your license key as a header:

import { NodeSDK } from '@opentelemetry/sdk-node';
import { getNodeAutoInstrumentations } from '@opentelemetry/auto-instrumentations-node';
import { OTLPTraceExporter } from '@opentelemetry/exporter-trace-otlp-http';

const sdk = new NodeSDK({
  serviceName: 'my-api',
  traceExporter: new OTLPTraceExporter({
    url: 'https://ingest.aiaxoniq.com/v1/traces',
    headers: { 'x-license-key': process.env.AIAXONIQ_LICENSE_KEY! },
  }),
  instrumentations: [getNodeAutoInstrumentations()],
});

sdk.start();

Step 3: Load it first

Update your start script in package.json to require the instrumentation file before your main entry:

{
  "scripts": {
    "start": "node --require ./instrumentation.js src/index.js"
  }
}

Step 4: Run and verify

Start your server, make a few requests, and open your aiAxonIQ dashboard. You should see traces appearing within about 30 seconds.

That's it. No code changes to your application logic required — the auto-instrumentation handles Express, HTTP clients, database calls, and more automatically.