Axiom Docs

Prerequisites

Create an Axiom account.
Create a dataset in Axiom where you send your data.
Create an API token in Axiom with permissions to ingest data to the dataset you have created.

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.

Platform overview

Send data

Understand data

Use cases

Miscellaneous

Axiom transport for Winston logger

Prerequisites

Install SDK

Import the Axiom transport for Winston

Create a Winston logger instance

Error, exception, and rejection handling

Configure region

Transport options

Examples

​Prerequisites

​Install SDK

​Import the Axiom transport for Winston

​Create a Winston logger instance

​Error, exception, and rejection handling

​Configure region

​Transport options

​Examples

Prerequisites

Install SDK

Import the Axiom transport for Winston

Create a Winston logger instance

Error, exception, and rejection handling

Configure region

Transport options

Examples