SDK configuration reference

This page lists every setting the ApiTraffic Node SDK reads, with its type, default and effect, and the functions you can call from your request-handling code. It applies to @apitraffic/node and to the per-framework packages (@apitraffic/express, @apitraffic/fastify, @apitraffic/koa, @apitraffic/hapi), which accept the same options. The Strapi plugin takes them through its plugin configuration; see Strapi.

Most applications need only two values, API_TRAFFIC_TOKEN and API_TRAFFIC_BUCKET. Everything that decides what is captured, redacted or blocked is set in your ApiTraffic account and delivered to the SDK, not configured here.

Where settings come from #

The SDK combines three sources:

1. Options you pass in code, to apitraffic.express({...}), apitraffic.fastify({...}) and the other framework calls.
2. API_TRAFFIC_* environment variables, read when the SDK starts.
3. Settings delivered from your ApiTraffic account: redaction rules, exclusions, the firewall policy, APM capture switches and host telemetry. The SDK loads them on startup and receives changes in real time, without a restart.

Precedence #

For every option in the tables below: an option passed in code wins over its environment variable, which wins over the built-in default. You can mix the two, for example the token from the environment and debug in code.

A few settings follow a different rule, and each is called out in its table:

How values are parsed #

Options that switch something on or off, and numeric limits, accept strings as well as booleans and numbers, so { captureSpans: process.env.CAPTURE_SPANS } works:

• Switches accept true/false, yes/no, on/off or 1/0, in any case.
• Byte caps and counts must be whole numbers greater than 0. captureStackDepth may be 0.
• Sample rates are numbers from 0 to 1.
• A blank value ("", spaces, or null) counts as not provided, so the environment variable, then the default, applies. A blank never means 0 or off (except for interceptOutbound).
• An invalid value ("abc", -5, 1.5 for a rate) is reported once on the console and ignored, and the next source applies.

Warning: debug and strict are not parsed from strings in code: pass true or false. API_TRAFFIC_DEBUG turns debug logging on only when it is exactly true (any case); 1 or yes do not.

Credentials and connection #

The SDK warns once if apiHost or ingestHost is plain http:// and not this machine, because the token and captured requests would cross the network unencrypted.

Proxies. Delivery to ApiTraffic honors the standard HTTPS_PROXY, HTTP_PROXY, ALL_PROXY and NO_PROXY environment variables (in upper or lower case).

Capture #

Bodies that cannot be captured safely - nested more than 256 levels deep, unreadable, or not processable by your redaction rules - are replaced with a [body not captured: …] placeholder and the rest of the request is still sent. A request whose redaction cannot be completed at all is dropped, never sent unredacted.

Delivery #

Delivery limits (timeouts, queue size, circuit breaker) are fixed; they are described in If ApiTraffic is unreachable.

Spans and APM #

These options control the spans recorded inside each request: database, cache, queue and outbound work from the APM bridge, and your own spans from span() and startSpan(). Set them on the framework call or with their environment variables.

Options for the APM preload #

register() (and node -r @apitraffic/node/register, which calls it) takes its own options, from the call or from these environment variables. The switches above that it shares (captureSpans, captureStatements, captureStatementParams, captureRedisKeys, captureCallSite, captureStackDepth, maxSpanMetaBytes, debug) read the same variables.

What the default instrumentation set covers, and how to use APM with an OpenTelemetry setup of your own, is in Set up APM.

Firewall options #

With @apitraffic/node the firewall is always mounted and runs once your account has a live policy. These local controls exist mainly as overrides and kill switches.

app.use(apitraffic.express({
  waf: {
    onEvent: (event) => logger.warn({ waf: event }, 'firewall event')
  }
}));

Warning: offlineWafMode: 'closed' is the only setting with which an ApiTraffic outage can stop your application serving traffic: a server that starts while ApiTraffic is unreachable, with no cached or pinned copy of your policy, refuses every request. If you use it, commit offline definitions. See If ApiTraffic is unreachable.

Offline definitions #

See Offline definitions.

Server labels #

These variables label each server on the Servers page and on the requests it serves. The SDK checks each list in order and uses the first variable that is set, so common platform variables work without extra setup.

A service version must be at most 64 characters of letters, digits, ., _, + and -; a commit must be 7 to 40 hexadecimal characters. Other values are ignored.

Settings from your ApiTraffic account #

These are configured in ApiTraffic and reach every connected server within seconds of a change. None of them needs a restart or a deploy.

Per-request APIs #

Call these from code that runs while a request is being handled: route handlers, middleware after ApiTraffic, and anything they call, including across await. Each one attaches to the request in progress. Outside a request they do nothing, and none of them ever throws into your code.

They are exported by @apitraffic/node and by each framework package. Import them from the package you installed:

const apitraffic = require('@apitraffic/node');   // or '@apitraffic/express', and so on

Tag a request #

tag(key, value) attaches a searchable key-value pair, for example a customer or tenant ID, so you can find every request for that customer in the request log.

apitraffic.tag('customerId', String(req.user.id));
apitraffic.tag('plan', req.user.plan);

• key is 1 to 64 characters: a letter first, then letters, digits, _, . or -. Keys starting with waf., redaction., apitraffic. or at. are reserved.
• value is a string, number or boolean; numbers and booleans are stored as text. Values longer than 255 characters are cut to 255. null or undefined adds no tag.
• A request holds at most 32 tag keys. Setting an existing key again replaces its value and does not count twice.
• A tag that breaks a rule is dropped and counted in Settings → Dimensions, never thrown into your handler. See the tag rules.

Trace a code path #

trace(message) records a timestamped note on the request, a console log you can read in production:

apitraffic.trace('cart total exceeded the free-shipping threshold');

Each message is a string of at most 255 characters, and a request keeps at most 250 of them.

Time your own work #

span(type, name, fn, meta?) runs fn, times it and records it as a span on the request’s waterfall. It returns exactly what fn returns, works with synchronous functions and promises, and re-throws fn’s error unchanged after marking the span failed. time() is the same function under another name.

const rates = await apitraffic.span('http.out', 'tax lookup', () => taxClient.rates(cart), {
  host: 'api.acme-tax.example'
});

startSpan(type, name, meta?) is for work that does not fit one function. It returns a handle; call end() once when the work finishes:

const span = apitraffic.startSpan('queue', 'publish order.created');
try {
  await queue.publish('order.created', order);
  span.end();
} catch (error) {
  span.end({ ok: false, meta: { error: error.code } });
  throw error;
}

• type is one of db.query, redis, cache, http.out, queue, rpc, graphql or custom.
• meta is an object of extra detail, redacted and capped at maxSpanMetaBytes. setMeta(meta) on a handle adds to it before end().
• end({ ok: false }) marks the span failed. Calling end() again does nothing.
• With captureSpans off, spans are not recorded and the function still runs.

Read the request context #

getRequestManager() returns the object holding the current request’s tags, traces and spans, or undefined outside a request. getContext() returns the SDK’s context store for the current request, or undefined outside one. Most applications never need either; prefer tag, trace and span.

Process-level functions #

Related #

• Node SDK: Install and register the SDK for your framework.

• Outbound requests: What is captured for the calls your app makes.

• APM capture settings: The bucket switches that control what spans carry.

• If ApiTraffic is unreachable: Delivery limits and what happens during an outage.