@apitraffic/koa
Advanced tools
ApiTraffic helps engineering teams save development time so they can ship features faster.
Once you’ve integrated the ApiTraffic SDK into your application, each request/response will be sent to the ApiTraffic, processed, and will then appear within your desired bucket.
From within your ApiTraffic account you will see real-time requests to your API, API analytics, the load size of the response, etc.
Visit our knowledgebase for the complete documentation.
Data can be redacted either before it leaves your server or once it arrives to ApiTraffic for processing. Data redaction settings do not require any code changes as all configuration is done within your ApiTraffic account and pushed down to each connected server.
Learn more about redacting data.
Exclusions can be configured in cases where certain endpoints should not be logged. Like data redactions (above), no integration specific changes are required to exclude request that match a certain criteria.
Learn more about excluding requests.
Most applications should install
@apitraffic/nodeinstead. It is one package for every Node framework, with the firewall and APM bridge included, and every feature enabled from your ApiTraffic account rather than in code. This package remains published and supported — use it when you want the smallest possible install and are happy to add the firewall and APM yourself.
npm i @apitraffic/koa --save
IMPORTANT: Node 20+ required.
const apiTraffic = require('@apitraffic/koa');
// register the middleware before your routes...
app.use(apiTraffic.middleware());
There are two different methods for configuring the ApiTraffic SDK:
apiTraffic.middleware() functionThese methods are not mutually exclusive, if for whatever reason you need to set some as parameters and some as environment variables, it is ok they can be mixed.
If the same variable is set in both places, the parameters that are passed in will always supersede the environment variables.
| Function Param | Environment Variable | Required | Type | Details |
|---|---|---|---|---|
| token | API_TRAFFIC_TOKEN | Yes | String | Ingest token provided from your ApiTraffic account. |
| bucket | API_TRAFFIC_BUCKET | Yes | String | The bucket the data should be sent to when ingested. |
| interceptOutbound | API_TRAFFIC_INTERCEPT_OUTBOUND | No | Boolean | If outbound requests should be intercepted. (Default: true) |
| debug | API_TRAFFIC_DEBUG | No | Boolean | Log SDK activity to the console. Set the environment variable to true to enable it. (Default: false) |
The options are typed. ApiTrafficOptions lists every option above and the rest
of the base SDK's (captureSpans, maxBodyBytes, …); a value of the wrong type is
a compile error, and keys it does not list are still passed through.
import type { ApiTrafficOptions } from '@apitraffic/koa';
const options: ApiTrafficOptions = { debug: process.env.NODE_ENV !== 'production' };
app.use(apiTraffic.middleware(options));
Additional context can be added to requests via the tag() and trace() functions provided by the ApiTraffic SDK.
Tagging allows requests to be searchable by any number of tags that have been added to requests. For example, requests can be tagged by account or user ids which would then allow your team to view all API reqeusts for a specific account/person. There is no limit to the number of tags that can be added.
// include this in any file that needs tagging capabilities.
const apiTraffic = require('@apitraffic/koa');
// use the tag function.
apiTraffic.tag("key", "value");
It's console.log for production! Traces can easily be added to identify a specific code path or if data needs to be surfaced to help troubleshooting efforts.
// include this in any file that needs tracing capabilities.
const apiTraffic = require('@apitraffic/koa');
// use the trace function.
apiTraffic.trace("Whatever value that needs to be traced.");
The embeddable request log authenticates with a short-lived JWT that locks in the bucket, the filters and the request detail tabs the embed may show. It is minted on your server with an Administrator API token, set as API_TRAFFIC_EMBED_TOKEN (the ingest token the SDK reports with cannot mint embed tokens), and this package mints it:
const apiTraffic = require('@apitraffic/koa');
const { token, expiresAt } = await apiTraffic.embedToken({
// Structured filters are serialized safely; never paste a value into a criteria string.
filters: { tags: { customerId: 'cus_123' } },
ttl: 900
});
The host, bucket and account come from the SDK you already configured and the token from API_TRAFFIC_EMBED_TOKEN, so a call names only what is specific to this embed. Every option is documented on the embed page.
Unlike the rest of the SDK, this call rejects rather than going quiet: a token has one useful outcome, so a failure is a 500 on your own route instead of a broken embed with nothing to explain it.
API_TRAFFIC_EMBED_TOKEN is a read credential. An Administrator API token can mint embed tokens for any bucket in its account, with any filters or none, so whoever holds it can read all of the account's captured traffic. Keep it in a secret store (never in client-side code, images or a repository), and rotate it immediately if it may have been exposed.
A working sample has been provided in this repository. View the README for the sample application for details on how to run it.
To get started: Star & watch this repository to stay updated on the latest changes.
Follow us on our Blog and on X.
Chat with the ApiTraffic team and other memebers on Discord and follow our tutorials and other videos on YouTube.
Here are some ways you can help improve ApiTraffic:
FAQs
KOA plugin for sending request data to ApiTraffic.
The npm package @apitraffic/koa receives a total of 216 weekly downloads. As such, @apitraffic/koa popularity was classified as not popular.
We found that @apitraffic/koa demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 1 open source maintainer collaborating on the project.
Security News
/Application Security
A practical guide to securing GitHub Actions against supply chain attacks, covering malicious pull requests, credential theft, dependency risks, and release pipelines.
Security News
Composer 2.11 adds dependency cooldowns, joining package managers that delay new releases to reduce supply chain risks while allowing urgent security updates.
Threat Research
/Security News
Cursor removed a malicious Claude Code 2.1.313 extension from its marketplace. Socket examines registry records and the initial claims about its distribution.
