Koa.js - ApiTraffic

Installation

Install the Koa.js integration package:

npm install @apitraffic/koa

yarn add @apitraffic/koa

pnpm add @apitraffic/koa

Node 18+ required

Basic Setup

Add ApiTraffic middleware to your Koa.js application:

const Koa = require('koa');
const apiTraffic = require('@apitraffic/koa');

const app = new Koa();

// Add ApiTraffic middleware
app.use(apiTraffic({
  token: process.env.API_TRAFFIC_TOKEN,
  bucket: process.env.API_TRAFFIC_BUCKET
}));

// Your existing routes
app.use(async (ctx, next) => {
  if (ctx.path === '/api/users') {
    ctx.body = { users: [] };
  } else {
    await next();
  }
});

app.listen(3000);

Configuration Options

app.use(apiTraffic({
  token: 'your-api-token',           // Required
  bucket: 'your-bucket-id',          // Required
  ingestHost: 'ingest.apitraffic.io', // Optional
  apiHost: 'api.apitraffic.io',       // Optional
  interceptOutbound: true,            // Optional: Monitor outbound requests
  debug: false                        // Optional: Enable debug logging
}));

Configuration Table

Option	Environment Variable	Required	Type	Description
`token`	`API_TRAFFIC_TOKEN`	Yes	String	Ingest token from your ApiTraffic account
`bucket`	`API_TRAFFIC_BUCKET`	Yes	String	Bucket ID for data organization
`interceptOutbound`	`API_TRAFFIC_INTERCEPT_OUTBOUND`	No	Boolean	Monitor outbound HTTP requests (default: true)
`debug`	`API_TRAFFIC_DEBUG`	No	Boolean	Enable debug logging (default: false)

Advanced Usage

Custom Tagging

Add custom tags to requests for better organization and searchability:

const Router = require('@koa/router');
const router = new Router();

router.get('/api/users/:id', async (ctx) => {
  // Add custom tags
  apiTraffic.tag('user_id', ctx.params.id);
  apiTraffic.tag('endpoint', 'get_user');
  apiTraffic.tag('version', 'v1');
  
  const user = await getUserById(ctx.params.id);
  ctx.body = { user };
});

app.use(router.routes());

Request Tracing

Add trace messages for debugging and monitoring:

router.post('/api/users', async (ctx) => {
  apiTraffic.trace('Starting user creation process');
  
  try {
    const user = await createUser(ctx.request.body);
    apiTraffic.trace('User created successfully');
    ctx.body = user;
  } catch (error) {
    apiTraffic.trace(`User creation failed: ${error.message}`);
    throw error;
  }
});

Error Handling

ApiTraffic automatically captures errors, but you can add additional context:

app.on('error', (err, ctx) => {
  // Add error context
  apiTraffic.tag('error_type', err.name);
  apiTraffic.trace(`Error occurred: ${err.message}`);
  
  console.error('Server error:', err);
});

// Error handling middleware
app.use(async (ctx, next) => {
  try {
    await next();
  } catch (err) {
    ctx.status = err.statusCode || err.status || 500;
    ctx.body = { error: 'Internal Server Error' };
    ctx.app.emit('error', err, ctx);
  }
});

Environment Variables

Configure using environment variables:

.env

API_TRAFFIC_TOKEN=your-api-token
API_TRAFFIC_BUCKET=your-bucket-id
API_TRAFFIC_INGEST_HOST=ingest.apitraffic.io
API_TRAFFIC_API_HOST=api.apitraffic.io
API_TRAFFIC_INTERCEPT_OUTBOUND=true
API_TRAFFIC_DEBUG=false

Middleware Order

Place ApiTraffic middleware early in your middleware stack:

const Koa = require('koa');
const bodyParser = require('koa-bodyparser');
const cors = require('@koa/cors');
const apiTraffic = require('@apitraffic/koa');

const app = new Koa();

// Error handling middleware (first)
app.use(async (ctx, next) => {
  try {
    await next();
  } catch (err) {
    ctx.status = 500;
    ctx.body = { error: 'Internal Server Error' };
  }
});

// CORS middleware
app.use(cors());

// Body parser middleware
app.use(bodyParser());

// ApiTraffic middleware (after body parsing)
app.use(apiTraffic({
  token: process.env.API_TRAFFIC_TOKEN,
  bucket: process.env.API_TRAFFIC_BUCKET
}));

// Your application routes
app.use(router.routes());

TypeScript Support

The package includes TypeScript definitions:

import Koa from 'koa';
import apiTraffic from '@apitraffic/koa';

const app = new Koa();

app.use(apiTraffic({
  token: process.env.API_TRAFFIC_TOKEN!,
  bucket: process.env.API_TRAFFIC_BUCKET!,
  interceptOutbound: true
}));

With Koa Router

Using ApiTraffic with @koa/router:

const Koa = require('koa');
const Router = require('@koa/router');
const apiTraffic = require('@apitraffic/koa');

const app = new Koa();
const router = new Router();

// Add ApiTraffic middleware
app.use(apiTraffic({
  token: process.env.API_TRAFFIC_TOKEN,
  bucket: process.env.API_TRAFFIC_BUCKET
}));

// Define routes
router.get('/api/users', async (ctx) => {
  apiTraffic.tag('endpoint', 'list_users');
  ctx.body = { users: [] };
});

router.post('/api/users', async (ctx) => {
  apiTraffic.tag('endpoint', 'create_user');
  apiTraffic.trace('Creating new user');
  
  const user = await createUser(ctx.request.body);
  ctx.body = user;
});

app.use(router.routes());
app.use(router.allowedMethods());

Security Features

Data Redaction

ApiTraffic automatically redacts sensitive data based on your account settings. No code changes required - configure redaction rules in your ApiTraffic dashboard.

Request Exclusions

Exclude specific endpoints from monitoring by configuring exclusion rules in your ApiTraffic account. Common exclusions include:

Health check endpoints
Static asset requests
Internal monitoring endpoints

Troubleshooting

Middleware not capturing requests

Ensure ApiTraffic middleware is placed before your route handlers and after body parsing middleware.

Missing environment variables

Verify that API_TRAFFIC_TOKEN and API_TRAFFIC_BUCKET are set in your environment.

Outbound requests not being tracked

Set interceptOutbound: true in your configuration to enable outbound request monitoring.

Context not available in routes

Make sure you’re using async/await syntax and that ApiTraffic middleware is properly registered.

Debug Mode

Enable debug mode to see detailed logging:

app.use(apiTraffic({
  token: process.env.API_TRAFFIC_TOKEN,
  bucket: process.env.API_TRAFFIC_BUCKET,
  debug: true
}));

Sample Application

A complete working example is available in the GitHub repository.

Next Steps

Dashboard

View your API traffic data and analytics

Workflow Engine

Create automated workflows based on your API data

​Installation

​Basic Setup

​Configuration Options

​Configuration Table

​Advanced Usage

​Custom Tagging

​Request Tracing

​Error Handling

​Environment Variables

​Middleware Order

​TypeScript Support

​With Koa Router

​Security Features

​Data Redaction

​Request Exclusions

​Troubleshooting

​Debug Mode

​Sample Application

​Next Steps

Dashboard

Workflow Engine

Installation

Basic Setup

Configuration Options

Configuration Table

Advanced Usage

Custom Tagging

Request Tracing

Error Handling

Environment Variables

Middleware Order

TypeScript Support

With Koa Router

Security Features

Data Redaction

Request Exclusions

Troubleshooting

Debug Mode

Sample Application

Next Steps