# @stream-io/logger

> Logging library for Stream.io JS-based SDKs and applications

Latest version **2.1.0** (published 2026-10-30) · SEE LICENSE IN LICENSE license · 0 weekly downloads

## Install

```sh
npm install @stream-io/logger
pnpm add @stream-io/logger
yarn add @stream-io/logger
bun add @stream-io/logger
```

## Health

**Score 70/100 (B)** — status: active.

Positive: has types; esm support; no vulnerabilities; recently updated; high maintenance score; high quality score.

Warnings: low downloads.

## Facts

| | |
|---|---|
| Version | 2.1.0 |
| Published | 2026-10-30 |
| First published | 2025-09-15 |
| Weekly downloads | 0 |
| License | SEE LICENSE IN LICENSE |
| TypeScript types | bundled |
| Module format | ESM + CommonJS |
| Dependencies | 0 |
| Unpacked size | 36.1 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| Author | GetStream.io, Inc. |
| Maintainers | tbarbugli, tschellenbach, vishtree, stream-release-bot, vangalilea88, zita.szupera, caleb.murphy, martincupela |
| Keywords | logging |

## Links

- npm: https://www.npmjs.com/package/@stream-io/logger
- npm.io page: https://npm.io/package/@stream-io/logger

## Alternatives

- [cli-color](https://npm.io/package/cli-color.md) — 3.4M weekly downloads
- [log](https://npm.io/package/log.md) — 1.3M weekly downloads
- [logstash-client](https://npm.io/package/logstash-client.md) — 4.5K weekly downloads
- [@nocobase/plugin-logger](https://npm.io/package/@nocobase/plugin-logger.md) — 2.0K weekly downloads
- [child-process-debug](https://npm.io/package/child-process-debug.md) — 695 weekly downloads

## Recent versions

- 2.1.0 (latest) — 2026-10-30
- 2.0.0 — 2025-10-27
- 1.2.2 — 2025-10-16
- 1.2.1 — 2025-10-15
- 1.2.0 — 2025-10-10
- 1.1.4 — 2025-09-17
- 1.1.3 — 2025-09-17
- 1.1.2 — 2025-09-16
- 1.1.1 — 2025-09-16
- 1.1.0 — 2025-09-16
- 1.0.2 — 2025-09-16
- 1.0.1 — 2025-09-16
- 1.0.0 — 2025-09-15

## README

# @stream-io/logger

<sub>`sdk/src/logger.ts`</sub>

```ts
import { createLoggerSystem } from "@stream-io/logger";

// known SDK logger scopes; defaults to 'string' when unspecified.
export type AvailableScopes = "coordinator" | "network" | "sfu" | "filters";

export const logger = createLoggerSystem<AvailableScopes>();

// now you can use logger.configureLoggers and logger.getLogger
```

After that you can set up a sink and a log level for each of these scopes individually. The mechanism will use `default` scope if logger cannot find settings for the accessed scope. A "sink" is a function which gets funneled logs an SDK code produces. A sink gets a log level, message and other values we pass down to it as arguments from the SDK.

Log levels are pre-defined and are ordered by severity as such:

- trace: 0
- debug: 1
- info: 2
- warn: 3
- error: 4

For example; if you set a log level to a value `warn` for a scope `coordinator`, you will only see errors and warnings generated by the SDK for that specific scope.

## Usage

```ts
import { createLoggerSystem } from '@stream-io/logger';

// arbitrary logging mechanism of your choice
import SuperLogger from "./SuperLogger";

const logger = createLoggerSystem<"sfu" | "coordinator">();

logger.configureLoggers({
  sfu: {
    level: "error",
  },
  coordinator: {
    level: "warn",
    sink: (logLevel, message, ...rest) => {
      switch (logLevel) {
        case "warn": {
          console.warn(message, ...rest);
          break;
        }
        case "error": {
          SuperLogger.error(message, ...rest);
        }
      }
    },
  },
});
```

You can augment the settings of the `default` scope if you don't want to apply custom sinks/levels to all the SDK-defined scopes individually.

```ts
import { createLoggerSystem } from "@stream-io/logger";

import SuperLogger from "./SuperLogger";

const logger = createLoggerSystem();

logger.configureLoggers({
  default: {
    level: "info",
    sink: (logLevel, message, ...rest) => {
      SuperLogger[logLevel](message, ...rest);
    },
  },
});
```

If you need to reset specific scopes during your application runtime to use defaults instead you can do so as follows:

```ts
import { createLoggerSystem } from "@stream-io/logger";

const logger = createLoggerSystem<"coordinator">();

logger.configureLoggers({
  coordinator: {
    level: null,
    sink: null,
  },
});
```

This action will only reset the `coordinator` scope and `sfu` scope will stay intact (considering previous examples). If you need to reset the defaults completely, you can do so as follows:

```ts
import { createLoggerSystem } from "@stream-io/logger";

const logger = createLoggerSystem();
logger.restoreDefaults();
```

This action will clear all the pre-defined settings and restore `default` scope if it has been augmented.

## Sentry Integration

Here is an example showing a basic [Sentry](https://sentry.io/welcome/) integration:

```ts
import { LogLevel, configureLoggers, Sink } from "@stream-io/logger";

import * as Sentry from "@sentry/nextjs";

const sentrySeverityByLogLevel: Record<LogLevel, Sentry.SeverityLevel> = {
  debug: "debug",
  info: "info",
  warn: "warning",
  error: "error",
};

const customSentrySink: Sink = (logLevel, message, ...rest) => {
  Sentry.captureEvent({
    level: sentrySeverityByLogLevel[logLevel],
    extra: args,
  });
};

const logger = createLoggerSystem();

logger.configureLoggers({
  default: {
    sink: customSentrySink,
    level: "warn",
  },
});
```

## Compatibility

Ships ESM (`.mjs`) and CommonJS (`.cjs`) compiled to ES2022. Toolchains that cannot parse ES2022 (e.g. webpack 4) need to transpile this package.

---
_Source: https://npm.io/package/@stream-io/logger · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._
