Better Stack Logger

BetterstackLogger is the Logger component’s Better Stack backend. It wraps the official @logtail/node client to ship structured logs to Better Stack’s Logs (Logtail) platform, attaching your data object to every entry and flattening exception details onto the payload. It implements the framework’s ILogger interface, so call sites stay provider-agnostic and you can swap the backend without touching the code that emits logs.

What you get

Logs ship to Better Stack for search, dashboards, and alerting, so you don’t run your own pipeline. Pass a data object and it’s sent alongside the message as structured fields. error() accepts an IException and flattens its name, status, and stack trace onto the payload. You can point at a custom ingesting endpoint or fall back to the Logtail default. The client batches logs, and flush() drains the buffer before the process exits. Registration happens through @decorator.logger(), and the logger resolves from the container.

Installation

BetterstackLogger ships with @talosjs/logger and depends on the Logtail Node client.

bun add @talosjs/logger @logtail/node

Environment variables

Variable	Required	Purpose
`BETTERSTACK_LOGGER_SOURCE_TOKEN`	Yes	Better Stack source token. Missing throws `LoggerException` (`LOG_FAILED`).
`BETTERSTACK_LOGGER_INGESTING_HOST`	No	Custom ingesting endpoint. Omitted uses the Logtail default.

BETTERSTACK_LOGGER_SOURCE_TOKEN=xxxxxxxxxxxxxxxxxxxxxxxx
# Optional: point at your source's ingesting host
BETTERSTACK_LOGGER_INGESTING_HOST=https://s1234567.eu-nbg-2.betterstackdata.com

The source token is validated when BetterstackLogger is constructed, so a missing token fails fast at startup.

How it works

On construction, the backend creates a single Logtail client with your source token (and endpoint, if set). Each level method forwards the message and data to the matching Logtail method, error, warn, info, or debug, while log and success map to info with a level field (LOG / SUCCESS) so the original level is preserved. When an IException is passed to error(), its name, status, and JSON stack trace are extracted and merged into the payload. Delivery is buffered, so call flush() to drain it.

Method	Purpose
`init()`	No-op; returns immediately.
`error(message, data?)`	Ship an error. `message` may be a `string` or `IException`.
`warn(message, data?)`	Ship a warning.
`info(message, data?)`	Ship informational output.
`debug(message, data?)`	Ship debug detail.
`log(message, data?)`	Ship a general message (sent as `info` with `level: "LOG"`).
`success(message, data?)`	Ship a success message (sent as `info` with `level: "SUCCESS"`).
`flush()`	Drain the buffered logs.

Usage

import { container } from "@talosjs/container";
import { BetterstackLogger } from "@talosjs/logger";

const logger = container.get(BetterstackLogger);

logger.info("User signed in", { userId: "123", email: "john@example.com" });
logger.success("Payment captured", { orderId: "ord_456", amount: 4999 });
logger.warn("Rate limit approaching", { remaining: 5 });

// Flush before the process exits
await logger.flush();

error() accepts a plain message or an IException. Given an exception, it flattens the name, status, and stack trace onto the payload:

import { container } from "@talosjs/container";
import { BetterstackLogger } from "@talosjs/logger";
import type { IException } from "@talosjs/exception";

const logger = container.get(BetterstackLogger);

try {
  await processPayment(order);
} catch (error) {
  logger.error(error as IException, { orderId: order.id });
}

Inject it into a service to ship logs as part of your domain logic:

import { inject } from "@talosjs/container";
import { BetterstackLogger } from "@talosjs/logger";

export class CheckoutService {
  constructor(@inject(BetterstackLogger) private readonly logger: BetterstackLogger) {}

  public completeOrder(userId: string, order: Order) {
    this.logger.success("Order completed", { userId, orderId: order.id });
  }
}

Use in the app

In an @talosjs/app application, register BetterstackLogger by adding it to the loggers array of your App config. The loggers slot of AppConfigType is typed as LoggerClassType[], so you pass the class itself and the framework registers it with the container at startup.

bun add @talosjs/app @talosjs/logger @logtail/node

import { App } from "@talosjs/app";
import { BetterstackLogger } from "@talosjs/logger";

const app = new App({
  routing: { prefix: "/api" },
  loggers: [BetterstackLogger],
});

await app.run();

loggers accepts an array, so you can ship to Better Stack while also printing to the terminal in development:

import { App } from "@talosjs/app";
import { BetterstackLogger, TerminalLogger } from "@talosjs/logger";

const app = new App({
  routing: { prefix: "/api" },
  loggers: [TerminalLogger, BetterstackLogger],
});

Set BETTERSTACK_LOGGER_SOURCE_TOKEN (and optionally BETTERSTACK_LOGGER_INGESTING_HOST) in your .env.yml (or environment), then inject the logger into a service or controller:

import { inject } from "@talosjs/container";
import { BetterstackLogger } from "@talosjs/logger";

export class CheckoutService {
  constructor(@inject(BetterstackLogger) private readonly logger: BetterstackLogger) {}

  public async completeOrder(userId: string, order: Order) {
    // ... persist the order ...
    this.logger.success("Order completed", { userId, orderId: order.id });
  }
}

Because delivery is buffered, flush the client before the process exits, for example from a shutdown hook:

import { container } from "@talosjs/container";
import { BetterstackLogger } from "@talosjs/logger";

process.on("SIGTERM", async () => {
  await container.get(BetterstackLogger).flush();
  process.exit(0);
});

Exceptions

BetterstackLogger throws LoggerException on misconfiguration, carrying a machine-readable key.

Key	When
`LOG_FAILED`	`BetterstackLogger` is constructed without `BETTERSTACK_LOGGER_SOURCE_TOKEN`.

import { LoggerException } from "@talosjs/logger";

try {
  const logger = container.get(BetterstackLogger);
} catch (error) {
  if (error instanceof LoggerException && error.key === "LOG_FAILED") {
    console.error("Better Stack is missing its source token", error.data);
  }
  throw error;
}

Working with it day to day

Drain the buffer with flush() before the process terminates, or the last logs never leave. Keep the message string stable and push variable detail into the data object; interpolated strings are harder to search later. When you catch an exception, pass the IException itself to error() so the name, status, and stack trace come through. The source token lives in .env, never in source. And if your source uses a region-specific endpoint, set BETTERSTACK_LOGGER_INGESTING_HOST to match it. For error and exception tracking specifically, see Better Stack Exceptions. See the Logger component for the provider interface and how logs flow through the framework.

Getting Started

AI

Framework

Command Line

Better Stack Logger

What you get

Installation

Environment variables

How it works

Usage

Use in the app

Exceptions

Working with it day to day

​What you get

​Installation

​Environment variables

​How it works

​Usage

​Use in the app

​Exceptions

​Working with it day to day

What you get

Installation

Environment variables

How it works

Usage

Use in the app

Exceptions

Working with it day to day