DOCSEARCHbyAlgolia
Submit Docs

Axiom JS SDK

repository·main·Indexed 40 days ago

https://github.com/axiomhq/axiom-js

Official JavaScript and TypeScript libraries for the Axiom API (version 0.14.0). Enables data ingestion, querying via APL and MPL, and integration with logging frameworks like Winston and Pino. Includes specialized observability support for TanStack Start applications via the @axiomhq/tanstack-start package, providing router navigation timing, middleware correlation, and error boundary integration for React and Solid.

Tokens
36.8K
Snippets
108
Records
149
Agent score
99%

What's inside Axiom

  1. Overview of axiom-js packages

    main

    axiom-js is a monorepo providing official tools for interacting with Axiom. It includes core API bindings, logging transports for popular libraries, and observability utilities for the TanStack ecosystem:

    • @axiomhq/js: Official API bindings for ingesting or querying data.
    • @axiomhq/winston: A winston transport for sending logs to Axiom.
    • @axiomhq/pino: A pino transport for sending logs to Axiom.
    • @axiomhq/tanstack-start: Observability utilities designed for TanStack Router (SPA) and TanStack Start.

  2. Use @axiomhq/tanstack-start package surface

    main

    The @axiomhq/tanstack-start package is organized into several subpaths depending on your needs:

    Root Package

    Use the root package for framework-neutral TanStack Start observability (middleware, error handling, and formatters).

    @axiomhq/tanstack-start/router

    Use this subpath for TanStack Router navigation and timing helpers.

    @axiomhq/tanstack-start/react

    Use the React adapter to report errors from TanStack Router defaultErrorComponent, per-route errorComponent, or app-level boundaries.

    @axiomhq/tanstack-start/solid

    Use the Solid adapter to report errors from TanStack Router defaultErrorComponent, per-route errorComponent, or app-level boundaries.

  3. Observability patterns in @axiomhq/tanstack-start

    main

    The @axiomhq/tanstack-start package provides several observability paths for TanStack Start applications:

    1. SPA Navigation & Timing: Use @axiomhq/tanstack-start/router to observe TanStack Router SPA navigation and route timing events.
    2. Middleware & Correlation: Use TanStack Start request/function middleware. You can enable client+server correlation by using createAxiomFnMiddleware(..., { correlation: true }).
    3. Error Boundary Integration: Use @axiomhq/tanstack-start/react to integrate with TanStack Router's defaultErrorComponent for route-level error reporting.
    4. API Route Handlers: Observability is supported for TanStack Start API route handlers (e.g., server.handlers on file routes like GET /api/time).

  4. Handle type checking for .vue files in TypeScript

    main

    Standard tsc cannot process type information for .vue imports. To perform type checking in this project environment, use vue-tsc instead of the standard tsc CLI.

    For editor-level type support, ensure the TypeScript Vue Plugin (Volar) is installed so the TypeScript language service can recognize .vue file types.

  5. Observability features in @axiomhq/tanstack-start

    main

    The @axiomhq/tanstack-start package provides observability for Solid-based TanStack Start applications through three primary paths:

    1. Router Observability: Uses @axiomhq/tanstack-start/router to capture TanStack Router SPA navigation and route timing events.
    2. Middleware Observability: Uses TanStack Start request/function middleware. You can enable client and server correlation by using createAxiomFnMiddleware(..., { correlation: true }).
    3. Solid Error Boundary Integration: Uses @axiomhq/tanstack-start/solid to integrate with Solid route-level error boundaries via the TanStack Router defaultErrorComponent.

  8. Implement Client-Side Proxy Ingestion

    main

    To keep Axiom tokens secure on the server while allowing client-side logging, use ProxyTransport on the client and createAxiomProxyHandler on a server route.

    1. Client: Configure a Logger using ProxyTransport pointing to a local API endpoint.
    2. Server: Create an API route (e.g., /api/axiom) that uses createAxiomProxyHandler to forward the request to your server-side logger.
    // 1. Client Setup (src/lib/axiom/client.ts)
import { ConsoleTransport, Logger, ProxyTransport } from '@axiomhq/logging';
import type { Transport } from '@axiomhq/logging';
import { tanStackStartClientFormatters } from '@axiomhq/tanstack-start';
import { tanStackRouterFormatters } from '@axiomhq/tanstack-start/router';

function createBrowserTransports(): [Transport, ...Transport[]] {
  return [
    new ProxyTransport({ url: '/api/axiom' }),
    new ConsoleTransport({ prettyPrint: true }),
  ];
}

export const routerLogger = new Logger({
  transports: createBrowserTransports(),
  formatters: tanStackRouterFormatters,
});

export const clientLogger = new Logger({
  transports: createBrowserTransports(),
  formatters: tanStackStartClientFormatters,
});

// 2. Server Setup (src/lib/axiom/server.ts)
import { Axiom } from '@axiomhq/js';
import { AxiomJSTransport, ConsoleTransport, Logger } from '@axiomhq/logging';
import { tanStackStartServerFormatters } from '@axiomhq/tanstack-start';

const axiom = new Axiom({ token: process.env.AXIOM_TOKEN! });

export const startLogger = new Logger({
  transports: [
    new AxiomJSTransport({
      axiom,
      dataset: process.env.AXIOM_DATASET!,
    }),
    new ConsoleTransport({ prettyPrint: true }),
  ],
  formatters: tanStackStartServerFormatters,
});

// 3. Proxy Route (src/routes/api/axiom.ts)
import { createFileRoute } from '@tanstack/react-router';
import { createAxiomProxyHandler } from '@axiomhq/tanstack-start';
import { startLogger } from '../../lib/axiom/server';

const proxyHandler = createAxiomProxyHandler(startLogger);

export const Route = createFileRoute('/api/axiom')({
  server: {
    handlers: {
      POST: ({ request }) => proxyHandler(request),
    },
  },
});

  10. Run Axiom JS SDK examples

    main

    To run the provided examples in the examples-js package, you must first set your AXIOM_TOKEN environment variable. You can then execute any example file using ts-node via npx.

    Prerequisites:

    • An Axiom token.
    • ts-node installed or accessible via npx.
    export AXIOM_TOKEN="..."
npx ts-node <example-file.ts>

  11. Run Axiom JS SDK integration tests

    main

    To run the integration tests for the JS SDK, use the pnpm integration command.

    By default, the tests create datasets with names that include an AXIOM_DATASET_SUFFIX. If you are running tests against a shared organization, you should set this suffix to a unique value like a pipeline ID or a commit hash to avoid collisions. For local development, you can explicitly set it to local.

    export AXIOM_DATASET_SUFFIX="local"
pnpm integration

  12. Available Axiom JS SDK usage examples

    main

    The examples-js repository contains several TypeScript examples demonstrating common tasks with the Axiom JS SDK. These include:

    Data Ingestion

    • Create an annotation: create-annotation.ts
    • Ingest events: ingest-events.ts
    • Ingest a file: ingest-file.ts
    • Ingest a JSON string: ingest-string.ts

    Querying and Data Retrieval

    • Query datasets (APL): query.ts (using Axiom Processing Language)
    • Query metrics (MPL): query-metrics.ts (using Metrics Processing Language)
    • Query legacy: query-legacy.ts
    • Retrieve saved queries: saved-queries.ts

    Inspection and Management

    • List datasets: list-datasets.ts
    • Inspect a dataset: inspect-dataset.ts (includes fields and map fields)
    • Inspect metrics metadata: inspect-metrics-dataset.ts
    • Inspect dashboards: inspect-dashboards.ts (listing and retrieving by UID)
    • Manage monitors: manage-monitors.ts (create, list, get, update, delete)
    • Manage users: users.ts (current user, list users, retrieve by ID)