Tsed Logger

Ts.ED Logger

Ts.ED logs through one global Logger instance ($log from @tsed/logger) plus one ContextLogger per request ($ctx.logger). Appenders decide where events go, layouts decide how they look.

Read the appender and layout reference before configuring outputs and the request logging reference before touching the logger configuration key.

1. Know what is already installed

• @tsed/logger and @tsed/logger-std are dependencies of @tsed/platform-http. A Ts.ED HTTP application already has two appenders on $log: stdout (levels info, debug) and stderr (levels trace, fatal, error, warn), both with the colored layout.
• Outside an HTTP application (script, worker, library), $log only has one console appender registered under the name stdout.
• Everything else is opt-in in v8: install the package and import it for its side effect before calling $log.appenders.set().

2. Get a logger

Use the application logger for lifecycle and background work:

import {Injectable, inject} from "@tsed/di";
import {Logger} from "@tsed/logger";

@Injectable()
export class BillingService {
  protected logger = inject(Logger);

  $onInit() {
    this.logger.info({event: "BILLING_READY"});
  }
}

logger() from @tsed/di returns the same instance without a class; @Inject() logger: Logger also works. Do not create new Logger() in application code: it has no appenders and ignores the Ts.ED configuration.

3. Log inside a request

Use the request logger so every line carries reqId, time and duration:

import {Controller} from "@tsed/di";
import {Context} from "@tsed/platform-params";
import {Get} from "@tsed/schema";

@Controller("/orders")
export class OrdersController {
  @Get("/")
  list(@Context() $ctx: Context) {
    $ctx.logger.info({event: "ORDERS_LIST", tenant: $ctx.request.headers["x-tenant"]});
  }
}

In a service called during the request, use context().logger.info({...}) (context from @tsed/di) instead of passing $ctx around.

• $ctx.logger methods take one argument: an object, or a string (stored as message).
• Request logs are buffered (logger.maxStackSize, default 30) and flushed when the request ends; error and fatal flush immediately.
• Never put per-request data on the global logger ($log.context.set(...), a shared field, a custom appender state). Concurrent requests overwrite each other.

4. Configure levels and request logging

import "@tsed/platform-express";
import "@tsed/platform-log-request";
import {Configuration} from "@tsed/di";

@Configuration({
  logger: {
    level: "info",
    logRequest: true,
    ignoreUrlPatterns: ["^/health", /^\/metrics/],
    disableRoutesSummary: process.env.NODE_ENV === "production"
  }
})
export class Server {}

1. level accepts debug, info, warn, error, off. The default is info, and off when NODE_ENV=test.
2. In v8, request start/end logs exist only after import "@tsed/platform-log-request". Without it logRequest does nothing.
3. Shape or redact request logs with logger.alterLog(level, obj, $ctx) and logger.onLogResponse($ctx).
4. Remaining keys: reqIdBuilder, maxStackSize, format, disableBootstrapLog, debug, perf. See the reference.

5. Configure appenders

import {$log} from "@tsed/logger";
import "@tsed/logger-std";
import "@tsed/logger/layouts/JsonLayout.js";

if (process.env.NODE_ENV === "production") {
  $log.appenders
    .set("stdout", {type: "stdout", levels: ["info", "debug"], layout: {type: "json"}})
    .set("stderr", {type: "stderr", levels: ["trace", "fatal", "error", "warn"], layout: {type: "json"}});
}

1. Run this at module top level, before bootstrap. Keep the explicit import "@tsed/logger-std" in the same file: that import resets stdout/stderr to their defaults, so it must run before your set() calls, not after.
2. Reuse the names stdout and stderr to replace the default appenders. Any other name adds an output and duplicates every line; call $log.appenders.delete("stdout") or .clear() first when that is not wanted.
3. Filter with levels (plural, array of level names). Omit it to receive every level.
4. Layouts other than colored need an import: @tsed/logger/layouts/JsonLayout.js, BasicLayout.js, MessagePassThroughLayout.js, DummyLayout.js, ObjectLayout.js; pattern needs the @tsed/logger-pattern-layout package.
5. With the JSON layout, log objects: their keys are merged at the root of the JSON line. Strings end up in the data array.

6. Add a connector

Install, import, then register. Available packages: @tsed/logger-file, -logstash-http, -logstash-udp, -seq, -loggly, -slack, -rabbitmq, -smtp, -insight, -logentries, -connect.

import {$log} from "@tsed/logger";
import {FileAppender} from "@tsed/logger-file";

$log.appenders.set("file", {
  type: FileAppender,
  filename: "logs/app.log",
  pattern: ".yyyy-MM-dd",
  levels: ["info", "warn", "error", "fatal"]
});

• Prefer passing the appender class as type: it proves the package is imported and avoids typos in the string name.
• Connector settings go under options; file settings (filename, maxLogSize, backups, pattern) stay at the top level.