Axiom
Overview

Axiom transport for Winston logger

Prerequisites#

Install SDK#

To install the SDK, run the following:

npm install @axiomhq/winston

Import the Axiom transport for Winston#

import { WinstonTransport as AxiomTransport } from '@axiomhq/winston';

Create a Winston logger instance#

const logger = winston.createLogger({
    level: 'info',
    format: winston.format.json(),
    defaultMeta: { service: 'user-service' },
    transports: [
        // You can pass an option here. If you don’t, the transport is configured automatically
        // using environment variables like `AXIOM_DATASET` and `AXIOM_TOKEN`
        new AxiomTransport({
            dataset: 'DATASET_NAME',
            token: 'API_TOKEN',
        }),
    ],
});

Replace API_TOKEN with the Axiom API token you have generated. For added security, store the API token in an environment variable.

Replace DATASET_NAME with the name of the Axiom dataset where you send your data.

After setting up the Axiom transport for Winston, use the logger as usual:

logger.log({
    level: 'info',
    message: 'Logger successfully setup',
});

Error, exception, and rejection handling#

To log errors, use the winston.format.errors formatter. For example:

import winston from 'winston';
import { WinstonTransport as AxiomTransport } from '@axiomhq/winston';
const { combine, errors, stack } = winston.format;
const axiomTransport = new AxiomTransport({ ... });
const logger = winston.createLogger({
  // 8<----snip----
  format: combine(errors({ stack: true }), json()),
  // 8<----snip----
});

To automatically log exceptions and rejections, add the Axiom transport to the exceptionHandlers and rejectionHandlers. For example:

import winston from 'winston';
import { WinstonTransport as AxiomTransport } from '@axiomhq/winston';
const axiomTransport = new AxiomTransport({ ... });
const logger = winston.createLogger({
  // 8<----snip----
  transports: [axiomTransport],
  exceptionHandlers: [axiomTransport],
  rejectionHandlers: [axiomTransport],
  // 8<----snip----
});

Running on Edge runtime isn’t supported.

Configure region#

By default, the transport sends data to api.axiom.co. To target a specific edge region, set the edge option on AxiomTransport to the edge domain that matches the region your dataset lives in:

new AxiomTransport({
    dataset: 'DATASET_NAME',
    token: 'API_TOKEN',
    edge: 'eu-central-1.aws.edge.axiom.co',
});
new AxiomTransport({
    dataset: 'DATASET_NAME',
    token: 'API_TOKEN',
    edge: 'us-east-1.aws.edge.axiom.co',
});

The following edge domains are available:

Edge deployment Base domain for ingest and query
US East 1 (AWS) us-east-1.aws.edge.axiom.co
EU Central 1 (AWS) eu-central-1.aws.edge.axiom.co

For more information about edge deployments, see Edge deployments.

Always use the edge option to target a region. Don't put a regional hostname in url — url is reserved for non-ingest API operations and won't route ingest correctly. (This is unrelated to the Edge runtime note above, which is about where your code runs.)

Transport options#

Option Required Description
dataset yes The Axiom dataset to ingest logs into. Falls back to the AXIOM_DATASET environment variable.
token yes An Axiom API token with ingest permission for the dataset.
orgId no Organization ID. Required when using a personal token.
edge no Edge domain for ingest, without scheme. Example: eu-central-1.aws.edge.axiom.co. Use this to target a region.
edgeUrl no Full edge URL with scheme. Takes precedence over edge if both are set. Useful for self-hosted or proxy setups.
url no Base URL for non-ingest API operations.
onError no Callback invoked when sending data fails.

Examples#

For more examples, see the examples in GitHub.

Updated

Was this page helpful?