This release is 2 versions behind 1.2.2 — the latest version of @logtape/logtape. Jump to latest

@logtape/logtape@1.2.0-dev.344+834f24a9
Built and signed on GitHub Actions
Built and signed on GitHub Actions

dahlia/logtape

Simple logging library with zero dependencies for Deno/Node.js/Bun/browsers

JSR Score

100%

Published

3 months ago (1.2.0-dev.344+834f24a9)

@logtape/logtape

Logger

interface Logger

A logger interface. It provides methods to log messages at different severity levels.

const logger = getLogger("category");
logger.trace `A trace message with ${value}`
logger.debug `A debug message with ${value}.`;
logger.info `An info message with ${value}.`;
logger.warn `A warning message with ${value}.`;
logger.error `An error message with ${value}.`;
logger.fatal `A fatal error message with ${value}.`;

Properties

readonly



category: readonly string[]

The category of the logger. It is an array of strings.

readonly



parent: Logger | null

The logger with the supercategory of the current logger. If the current logger is the root logger, this is null.

Methods



getChild(subcategory: string
 | readonly [string]
 | readonly [string, ...string[]]): Logger

Get a child logger with the given subcategory.

const logger = getLogger("category");
const subLogger = logger.getChild("sub-category");

The above code is equivalent to:

const logger = getLogger("category");
const subLogger = getLogger(["category", "sub-category"]);



with(properties: Record<string, unknown>): Logger

Get a logger with contextual properties. This is useful for log multiple messages with the shared set of properties.

const logger = getLogger("category");
const ctx = logger.with({ foo: 123, bar: "abc" });
ctx.info("A message with {foo} and {bar}.");
ctx.warn("Another message with {foo}, {bar}, and {baz}.", { baz: true });

The above code is equivalent to:

const logger = getLogger("category");
logger.info("A message with {foo} and {bar}.", { foo: 123, bar: "abc" });
logger.warn(
  "Another message with {foo}, {bar}, and {baz}.",
  { foo: 123, bar: "abc", baz: true },
);



trace(message: TemplateStringsArray,
...values: readonly unknown[],
): void

Log a trace message. Use this as a template string prefix.

logger.trace `A trace message with ${value}.`;



trace(message: string,
properties?: Record<string, unknown> | (() => Record<string, unknown>),
): void

Log a trace message with properties.

logger.trace('A trace message with {value}.', { value });

If the properties are expensive to compute, you can pass a callback that returns the properties:

logger.trace(
  'A trace message with {value}.',
  () => ({ value: expensiveComputation() })
);



trace(properties: Record<string, unknown>): void

Log a trace values with no message. This is useful when you want to log properties without a message, e.g., when you want to log the context of a request or an operation.

logger.trace({ method: 'GET', url: '/api/v1/resource' });

Note that this is a shorthand for:

logger.trace('{*}', { method: 'GET', url: '/api/v1/resource' });

If the properties are expensive to compute, you cannot use this shorthand and should use the following syntax instead:

logger.trace('{*}', () => ({
  method: expensiveMethod(),
  url: expensiveUrl(),
}));



trace(callback: LogCallback): void

Lazily log a trace message. Use this when the message values are expensive to compute and should only be computed if the message is actually logged.

logger.trace(l => l`A trace message with ${expensiveValue()}.`);



debug(message: TemplateStringsArray,
...values: readonly unknown[],
): void

Log a debug message. Use this as a template string prefix.

logger.debug `A debug message with ${value}.`;



debug(message: string,
properties?: Record<string, unknown> | (() => Record<string, unknown>),
): void

Log a debug message with properties.

logger.debug('A debug message with {value}.', { value });

If the properties are expensive to compute, you can pass a callback that returns the properties:

logger.debug(
  'A debug message with {value}.',
  () => ({ value: expensiveComputation() })
);



debug(properties: Record<string, unknown>): void

Log a debug values with no message. This is useful when you want to log properties without a message, e.g., when you want to log the context of a request or an operation.

logger.debug({ method: 'GET', url: '/api/v1/resource' });

Note that this is a shorthand for:

logger.debug('{*}', { method: 'GET', url: '/api/v1/resource' });

If the properties are expensive to compute, you cannot use this shorthand and should use the following syntax instead:

logger.debug('{*}', () => ({
  method: expensiveMethod(),
  url: expensiveUrl(),
}));



debug(callback: LogCallback): void

Lazily log a debug message. Use this when the message values are expensive to compute and should only be computed if the message is actually logged.

logger.debug(l => l`A debug message with ${expensiveValue()}.`);



info(message: TemplateStringsArray,
...values: readonly unknown[],
): void

Log an informational message. Use this as a template string prefix.

logger.info `An info message with ${value}.`;



info(message: string,
properties?: Record<string, unknown> | (() => Record<string, unknown>),
): void

Log an informational message with properties.

logger.info('An info message with {value}.', { value });

If the properties are expensive to compute, you can pass a callback that returns the properties:

logger.info(
  'An info message with {value}.',
  () => ({ value: expensiveComputation() })
);



info(properties: Record<string, unknown>): void

Log an informational values with no message. This is useful when you want to log properties without a message, e.g., when you want to log the context of a request or an operation.

logger.info({ method: 'GET', url: '/api/v1/resource' });

Note that this is a shorthand for:

logger.info('{*}', { method: 'GET', url: '/api/v1/resource' });

If the properties are expensive to compute, you cannot use this shorthand and should use the following syntax instead:

logger.info('{*}', () => ({
  method: expensiveMethod(),
  url: expensiveUrl(),
}));



info(callback: LogCallback): void

Lazily log an informational message. Use this when the message values are expensive to compute and should only be computed if the message is actually logged.

logger.info(l => l`An info message with ${expensiveValue()}.`);



warn(message: TemplateStringsArray,
...values: readonly unknown[],
): void

Log a warning message. Use this as a template string prefix.

logger.warn `A warning message with ${value}.`;



warn(message: string,
properties?: Record<string, unknown> | (() => Record<string, unknown>),
): void

Log a warning message with properties.

logger.warn('A warning message with {value}.', { value });

If the properties are expensive to compute, you can pass a callback that returns the properties:

logger.warn(
  'A warning message with {value}.',
  () => ({ value: expensiveComputation() })
);



warn(properties: Record<string, unknown>): void

Log a warning values with no message. This is useful when you want to log properties without a message, e.g., when you want to log the context of a request or an operation.

logger.warn({ method: 'GET', url: '/api/v1/resource' });

Note that this is a shorthand for:

logger.warn('{*}', { method: 'GET', url: '/api/v1/resource' });

If the properties are expensive to compute, you cannot use this shorthand and should use the following syntax instead:

logger.warn('{*}', () => ({
  method: expensiveMethod(),
  url: expensiveUrl(),
}));



warn(callback: LogCallback): void

Lazily log a warning message. Use this when the message values are expensive to compute and should only be computed if the message is actually logged.

logger.warn(l => l`A warning message with ${expensiveValue()}.`);



warning(message: TemplateStringsArray,
...values: readonly unknown[],
): void

Log a warning message. Use this as a template string prefix.

logger.warning `A warning message with ${value}.`;



warning(message: string,
properties?: Record<string, unknown> | (() => Record<string, unknown>),
): void

Log a warning message with properties.

logger.warning('A warning message with {value}.', { value });

If the properties are expensive to compute, you can pass a callback that returns the properties:

logger.warning(
  'A warning message with {value}.',
  () => ({ value: expensiveComputation() })
);



warning(properties: Record<string, unknown>): void

Log a warning values with no message. This is useful when you want to log properties without a message, e.g., when you want to log the context of a request or an operation.

logger.warning({ method: 'GET', url: '/api/v1/resource' });

Note that this is a shorthand for:

logger.warning('{*}', { method: 'GET', url: '/api/v1/resource' });

If the properties are expensive to compute, you cannot use this shorthand and should use the following syntax instead:

logger.warning('{*}', () => ({
  method: expensiveMethod(),
  url: expensiveUrl(),
}));



warning(callback: LogCallback): void

Lazily log a warning message. Use this when the message values are expensive to compute and should only be computed if the message is actually logged.

logger.warning(l => l`A warning message with ${expensiveValue()}.`);



error(message: TemplateStringsArray,
...values: readonly unknown[],
): void

Log an error message. Use this as a template string prefix.

logger.error `An error message with ${value}.`;



error(message: string,
properties?: Record<string, unknown> | (() => Record<string, unknown>),
): void

Log an error message with properties.

logger.warn('An error message with {value}.', { value });

If the properties are expensive to compute, you can pass a callback that returns the properties:

logger.error(
  'An error message with {value}.',
  () => ({ value: expensiveComputation() })
);



error(properties: Record<string, unknown>): void

Log an error values with no message. This is useful when you want to log properties without a message, e.g., when you want to log the context of a request or an operation.

logger.error({ method: 'GET', url: '/api/v1/resource' });

Note that this is a shorthand for:

logger.error('{*}', { method: 'GET', url: '/api/v1/resource' });

If the properties are expensive to compute, you cannot use this shorthand and should use the following syntax instead:

logger.error('{*}', () => ({
  method: expensiveMethod(),
  url: expensiveUrl(),
}));



error(callback: LogCallback): void

Lazily log an error message. Use this when the message values are expensive to compute and should only be computed if the message is actually logged.

logger.error(l => l`An error message with ${expensiveValue()}.`);



fatal(message: TemplateStringsArray,
...values: readonly unknown[],
): void

Log a fatal error message. Use this as a template string prefix.

logger.fatal `A fatal error message with ${value}.`;



fatal(message: string,
properties?: Record<string, unknown> | (() => Record<string, unknown>),
): void

Log a fatal error message with properties.

logger.warn('A fatal error message with {value}.', { value });

If the properties are expensive to compute, you can pass a callback that returns the properties:

logger.fatal(
  'A fatal error message with {value}.',
  () => ({ value: expensiveComputation() })
);



fatal(properties: Record<string, unknown>): void

Log a fatal error values with no message. This is useful when you want to log properties without a message, e.g., when you want to log the context of a request or an operation.

logger.fatal({ method: 'GET', url: '/api/v1/resource' });

Note that this is a shorthand for:

logger.fatal('{*}', { method: 'GET', url: '/api/v1/resource' });

If the properties are expensive to compute, you cannot use this shorthand and should use the following syntax instead:

logger.fatal('{*}', () => ({
  method: expensiveMethod(),
  url: expensiveUrl(),
}));



fatal(callback: LogCallback): void

Lazily log a fatal error message. Use this when the message values are expensive to compute and should only be computed if the message is actually logged.

logger.fatal(l => l`A fatal error message with ${expensiveValue()}.`);



emit(record: Omit<LogRecord, "category">): void

Emits a log record with custom fields while using this logger's category.

This is a low-level API for integration scenarios where you need full control over the log record, particularly for preserving timestamps from external systems.

const logger = getLogger(["my-app", "integration"]);

// Emit a log with a custom timestamp
logger.emit({
  timestamp: kafkaLog.originalTimestamp,
  level: "info",
  message: [kafkaLog.message],
  rawMessage: kafkaLog.message,
  properties: {
    source: "kafka",
    partition: kafkaLog.partition,
    offset: kafkaLog.offset,
  },
});

Add Package

deno add jsr:@logtape/logtape

Import symbol

import { type Logger } from "@logtape/logtape";

Import directly with a jsr specifier

import { type Logger } from "jsr:@logtape/logtape";

Add Package

pnpm i jsr:@logtape/logtape

or (using pnpm 10.8 or older)

pnpm dlx jsr add @logtape/logtape

Import symbol

import { type Logger } from "@logtape/logtape";

Add Package

yarn add jsr:@logtape/logtape

or (using Yarn 4.8 or older)

yarn dlx jsr add @logtape/logtape

Import symbol

import { type Logger } from "@logtape/logtape";

Add Package

vlt install jsr:@logtape/logtape

Import symbol

import { type Logger } from "@logtape/logtape";

Add Package

npx jsr add @logtape/logtape

Import symbol

import { type Logger } from "@logtape/logtape";

Add Package

bunx jsr add @logtape/logtape

Import symbol

import { type Logger } from "@logtape/logtape";

@logtape/logtape@1.2.0-dev.344+834f24a9Built and signed on GitHub ActionsBuilt and signed on GitHub Actions

Properties

Methods

New Ticket: Report package

@logtape/logtape@1.2.0-dev.344+834f24a9
Built and signed on GitHub Actions
Built and signed on GitHub Actions