@gyramais/log-transport 0.1.0

package/dist/options.d.ts

@@ -0,0 +1,32 @@
+export interface LokiTransportLike {
+    log?: unknown;
+    flush?: () => Promise<void>;
+    close?: () => void;
+    once?: (event: string, listener: (...args: unknown[]) => void) => unknown;
+    off?: (event: string, listener: (...args: unknown[]) => void) => unknown;
+}
+export interface LokiOptions {
+    host: string;
+    basicAuth?: string;
+    interval?: number;
+    timeout?: number;
+    labels?: Record<string, string>;
+}
+export interface FileOptions {
+    filename: string;
+}
+export interface LoggerOptions {
+    service: string;
+    app?: string;
+    level?: string;
+    instance?: string;
+    pretty?: boolean;
+    loki?: LokiOptions;
+    lokiTransport?: LokiTransportLike;
+    file?: FileOptions;
+}
+export declare const DEFAULT_APP_LABEL = "saas";
+export declare const DEFAULT_LEVEL = "debug";
+export declare const DEFAULT_LOKI_INTERVAL_SECONDS = 5;
+export declare const DEFAULT_LOKI_TIMEOUT_MS = 60000;
+//# sourceMappingURL=options.d.ts.map

package/dist/options.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"options.d.ts","sourceRoot":"","sources":["../src/options.ts"],"names":[],"mappings":"AA4BA,MAAM,WAAW,iBAAiB;IAahC,GAAG,CAAC,EAAE,OAAO,CAAC;IACd,KAAK,CAAC,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;IAC5B,KAAK,CAAC,EAAE,MAAM,IAAI,CAAC;IACnB,IAAI,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,EAAE,QAAQ,EAAE,CAAC,GAAG,IAAI,EAAE,OAAO,EAAE,KAAK,IAAI,KAAK,OAAO,CAAC;IAC1E,GAAG,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,EAAE,QAAQ,EAAE,CAAC,GAAG,IAAI,EAAE,OAAO,EAAE,KAAK,IAAI,KAAK,OAAO,CAAC;CAC1E;AAED,MAAM,WAAW,WAAW;IAE1B,IAAI,EAAE,MAAM,CAAC;IAEb,SAAS,CAAC,EAAE,MAAM,CAAC;IAMnB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAElB,OAAO,CAAC,EAAE,MAAM,CAAC;IAOjB,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CACjC;AAED,MAAM,WAAW,WAAW;IAC1B,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED,MAAM,WAAW,aAAa;IAS5B,OAAO,EAAE,MAAM,CAAC;IAOhB,GAAG,CAAC,EAAE,MAAM,CAAC;IAEb,KAAK,CAAC,EAAE,MAAM,CAAC;IAQf,QAAQ,CAAC,EAAE,MAAM,CAAC;IASlB,MAAM,CAAC,EAAE,OAAO,CAAC;IAUjB,IAAI,CAAC,EAAE,WAAW,CAAC;IAkBnB,aAAa,CAAC,EAAE,iBAAiB,CAAC;IAMlC,IAAI,CAAC,EAAE,WAAW,CAAC;CACpB;AAED,eAAO,MAAM,iBAAiB,SAAS,CAAC;AACxC,eAAO,MAAM,aAAa,UAAU,CAAC;AAGrC,eAAO,MAAM,6BAA6B,IAAI,CAAC;AAE/C,eAAO,MAAM,uBAAuB,QAAQ,CAAC"}

package/dist/options.js

@@ -0,0 +1,25 @@
+"use strict";
+/*
+  Contrato de configuração do pacote.
+
+  Tudo entra por parâmetro: o pacote NÃO lê `process.env` em nenhum ponto. São três
+  razões, em ordem de peso:
+
+  1. Correção. Os 15 serviços não leem os mesmos envs — `gyra-export` lê `APP_NAME`,
+     e `gyra-file` e `gyra-websocket-server` não leem `ENVIRONMENT` nem `LOG_LEVEL`.
+     Um helper de env compartilhado mudaria o comportamento desses em silêncio.
+  2. Testabilidade. Ler env obriga o teste a mutar estado global do processo, o que
+     torna a suíte sensível à ordem de execução.
+  3. Contrato visível. A assinatura diz o que o pacote precisa, sem o consumidor
+     ter que ler o código-fonte.
+
+  Quem lê env é o serviço, no entrypoint, onde o env já mora hoje.
+*/
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DEFAULT_LOKI_TIMEOUT_MS = exports.DEFAULT_LOKI_INTERVAL_SECONDS = exports.DEFAULT_LEVEL = exports.DEFAULT_APP_LABEL = void 0;
+exports.DEFAULT_APP_LABEL = 'saas';
+exports.DEFAULT_LEVEL = 'debug';
+/* Curto de propósito — ver o comentário de `interval` acima. */
+exports.DEFAULT_LOKI_INTERVAL_SECONDS = 5;
+exports.DEFAULT_LOKI_TIMEOUT_MS = 60000;
+//# sourceMappingURL=options.js.map

package/dist/options.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"options.js","sourceRoot":"","sources":["../src/options.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;EAeE;;;AAmIW,QAAA,iBAAiB,GAAG,MAAM,CAAC;AAC3B,QAAA,aAAa,GAAG,OAAO,CAAC;AAErC,gEAAgE;AACnD,QAAA,6BAA6B,GAAG,CAAC,CAAC;AAElC,QAAA,uBAAuB,GAAG,KAAK,CAAC"}

package/package.json

@@ -0,0 +1,35 @@
+{
+  "name": "@gyramais/log-transport",
+  "version": "0.1.0",
+  "description": "Entrega de log ao Loki e registro de excecao fatal para os servicos gyra-*",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "files": [
+    "dist",
+    "src"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/gyramais/gyra-libs.git",
+    "directory": "packages/log-transport"
+  },
+  "license": "ISC",
+  "scripts": {
+    "build": "rm -rf dist && tsc -p tsconfig.json && node ../../scripts/verify-build.js",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "test": "jest --randomize",
+    "test:cov": "jest --coverage",
+    "prepack": "npm run build"
+  },
+  "dependencies": {
+    "winston-loki": "^6.1.6"
+  },
+  "peerDependencies": {
+    "@nestjs/common": ">=10",
+    "nest-winston": "^1.9.4",
+    "winston": "^3.13.1"
+  }
+}

package/src/console-redirect.ts

@@ -0,0 +1,50 @@
+/* eslint-disable @typescript-eslint/no-explicit-any */
+
+/*
+  Redireciona `console.*` para o Logger do Nest, para que biblioteca de terceiro (e
+  código legado) que escreve em `console` também chegue aos transports.
+
+  Saiu do `buildNestLogger` de propósito: trocar os métodos de `console` é efeito
+  colateral global do processo, e importar um pacote não deve mudar o que
+  `console.log` faz no serviço inteiro. Quem quer, chama.
+*/
+
+import { Logger } from '@nestjs/common';
+
+export interface ConsoleRedirectOptions {
+  /*
+    Em formato legível (desenvolvimento), `console.log` vira `Logger.log` e aparece
+    no terminal. Fora dele vira `Logger.debug`, para não inflar o volume de
+    ingestão com o que bibliotecas de terceiro escrevem — o que já é problema
+    conhecido de custo no Loki.
+  */
+  pretty?: boolean;
+}
+
+export const redirectConsoleToNestLogger = (
+  options: ConsoleRedirectOptions = {},
+): void => {
+  console.log = (message?: any, ...optionalParams: any[]) => {
+    if (options.pretty) {
+      Logger.log(message, ...optionalParams);
+    } else {
+      Logger.debug(message, ...optionalParams);
+    }
+  };
+
+  console.error = (message?: any, data?: any, ...optionalParams: any[]) => {
+    Logger.error(message, { data }, ...optionalParams);
+  };
+
+  console.warn = (message?: any, ...optionalParams: any[]) => {
+    Logger.warn(message, ...optionalParams);
+  };
+
+  console.debug = (message?: any, ...optionalParams: any[]) => {
+    Logger.debug(message, ...optionalParams);
+  };
+
+  console.info = (message?: any, ...optionalParams: any[]) => {
+    Logger.verbose(message, ...optionalParams);
+  };
+};

package/src/fatal-handlers.ts

@@ -0,0 +1,232 @@
+import { LoggerService } from '@nestjs/common';
+import LokiTransport = require('winston-loki');
+
+/*
+  O flush no caminho do crash é limitado no tempo de propósito: um Loki
+  indisponível não pode impedir o pod de morrer e reiniciar.
+*/
+const FLUSH_TIMEOUT_MS = 2000;
+
+type FatalOrigin = 'uncaughtException' | 'unhandledRejection';
+
+interface FatalHandlersOptions {
+  flushTimeoutMs?: number;
+  exit?: (code: number) => void;
+}
+
+/*
+  Winston entrega a linha ao transport por stream, num tick posterior ao
+  `logger.error()`. Sem esperar por essa entrega, o batch ainda está vazio quando
+  o flush é pedido — e aí o flush resolve na hora e o processo sai levando a linha
+  embora. O transport emite `logged` quando recebe.
+*/
+const LOGGED_HANDOFF_TIMEOUT_MS = 100;
+
+const waitForHandoff = (
+  transport: LokiTransport,
+  timeoutMs: number,
+): Promise<void> =>
+  new Promise((resolve) => {
+    const done = () => {
+      clearTimeout(timer);
+      transport.off?.('logged', done);
+      resolve();
+    };
+    const timer = setTimeout(done, timeoutMs);
+    transport.once?.('logged', done);
+  });
+
+/**
+ * Entrega ao Loki o que está bufferizado e só então devolve o controle,
+ * desistindo depois de `timeoutMs`. Nunca lança: no caminho de saída do
+ * processo, uma falha de flush não pode virar um segundo erro.
+ *
+ * O `flush()` do winston-loki apenas *aguarda* o laço periódico de envio, que
+ * pode estar a um intervalo inteiro de distância; quem está encerrando precisa
+ * *forçar* o envio agora. `close()` faz exatamente isso — interrompe a espera do
+ * laço e manda o batch pendente — e o `flush()` seguinte resolve quando esse
+ * envio termina.
+ */
+const flushLokiTransport = async (
+  transport: LokiTransport | undefined,
+  timeoutMs = FLUSH_TIMEOUT_MS,
+): Promise<void> => {
+  if (!transport?.flush) return;
+
+  let timer: NodeJS.Timeout | undefined;
+
+  const drain = async () => {
+    await waitForHandoff(
+      transport,
+      Math.min(LOGGED_HANDOFF_TIMEOUT_MS, timeoutMs),
+    );
+    transport.close?.();
+    await transport.flush();
+  };
+
+  try {
+    await Promise.race([
+      drain(),
+      new Promise<void>((resolve) => {
+        timer = setTimeout(resolve, timeoutMs);
+      }),
+    ]);
+  } catch {
+    /*
+      Silencioso por escolha: quem chama já está encerrando o processo e a linha
+      de erro do flush não teria para onde ir.
+    */
+  } finally {
+    if (timer) clearTimeout(timer);
+  }
+};
+
+const describeReason = (
+  reason: unknown,
+): { message: string; stack: string } => {
+  if (reason instanceof Error) {
+    return {
+      message: `${reason.name}: ${reason.message}`,
+      stack: reason.stack ?? '',
+    };
+  }
+
+  return { message: String(reason), stack: '' };
+};
+
+/**
+ * Registra os handlers de exceção fatal do processo.
+ *
+ * Sem eles, o handler padrão do Node imprime a stack direto no stderr — sem
+ * passar por nenhum transport do winston — e o crash fica invisível na
+ * observabilidade, encontrável apenas por `kubectl logs --previous`.
+ *
+ * O processo continua morrendo: depois de uma exceção não capturada o estado é
+ * indefinido, e reiniciar é o comportamento correto. O que muda é o crash passar
+ * a ficar registrado.
+ */
+/*
+  Handler de exceção fatal é recurso ÚNICO do processo, e o guard de reentrância
+  vive no closure de cada chamada — então dois registros são dois guards, e um
+  único erro fatal dispara os dois. Medido: quatro registros produziram quatro
+  linhas `[FATAL]`, quatro flushes concorrentes no mesmo transport e quatro
+  chamadas de exit.
+
+  O risco cresceu quando o pacote passou a suportar vários loggers com um
+  transport compartilhado (ver `createLokiTransport`): fica natural registrar um
+  handler por logger.
+
+  Este é o único estado global do pacote, e a distinção importa: ele descreve o
+  PROCESSO — se os handlers já estão instalados nele —, não configuração. Config
+  em variável global é o que `options.ts` recusa; isto é outra coisa.
+
+  `Symbol.for` e não um `let` de módulo: sobrevive a duas instâncias do pacote na
+  árvore de dependências, que é exatamente o caso em que o registro duplicado
+  aconteceria sem ninguém perceber.
+*/
+const REGISTERED = Symbol.for(
+  '@gyramais/log-transport.fatalHandlersRegistered',
+);
+
+type GlobalWithGuard = typeof globalThis & { [REGISTERED]?: boolean };
+
+const registerFatalHandlers = (
+  logger: LoggerService,
+  transport: LokiTransport | undefined,
+  options: FatalHandlersOptions = {},
+): (() => void) => {
+  const target = globalThis as GlobalWithGuard;
+
+  if (target[REGISTERED]) {
+    /*
+      Avisa em vez de ignorar em silêncio: registro duplicado é erro de
+      integração do consumidor, e descobrir isso durante um crash em produção é
+      o pior momento possível.
+    */
+    process.stdout.write(
+      `${JSON.stringify({
+        level: 'warn',
+        message:
+          '[FATAL-HANDLERS-DUP] registerFatalHandlers chamado mais de uma vez ' +
+          'neste processo; a chamada extra foi ignorada. Chame uma vez, com o ' +
+          'transport compartilhado.',
+        timestamp: new Date().toISOString(),
+      })}\n`,
+    );
+
+    return () => undefined;
+  }
+
+  target[REGISTERED] = true;
+  const flushTimeoutMs = options.flushTimeoutMs ?? FLUSH_TIMEOUT_MS;
+  const exit = options.exit ?? ((code: number) => process.exit(code));
+
+  /*
+    Um segundo erro fatal enquanto o primeiro ainda está sendo flushado não pode
+    reiniciar o ciclo — senão o processo nunca chega ao exit.
+  */
+  let handling = false;
+
+  const handleFatal = async (origin: FatalOrigin, reason: unknown) => {
+    if (handling) return;
+    handling = true;
+
+    /*
+      O exit vai no finally porque o guard de reentrância já está levantado: se
+      registrar ou flushar falhasse aqui, uma segunda passagem sairia na primeira
+      linha e o processo ficaria pendurado — travado num estado indefinido em vez
+      de reiniciar.
+    */
+    try {
+      const { message, stack } = describeReason(reason);
+
+      logger.error(`[FATAL] ${origin}: ${message}`, {
+        origin,
+        /*
+          String, não array: o Loki exige valores string na structured metadata e
+          rejeita a requisição inteira quando recebe outra coisa.
+        */
+        stack,
+      });
+
+      await flushLokiTransport(transport, flushTimeoutMs);
+    } finally {
+      exit(1);
+    }
+  };
+
+  /*
+    O catch fecha o laço: sem ele, uma falha dentro do handler de
+    unhandledRejection viraria uma nova unhandledRejection.
+  */
+  const onFatal =
+    (origin: FatalOrigin) =>
+    (reason: unknown): void => {
+      handleFatal(origin, reason).catch((): void => {
+        /*
+          Vazio de propósito: o processo já está encerrando, e uma linha de erro
+          daqui não teria para onde ir.
+        */
+      });
+    };
+
+  const onUncaught = onFatal('uncaughtException');
+  const onRejection = onFatal('unhandledRejection');
+
+  process.on('uncaughtException', onUncaught);
+  process.on('unhandledRejection', onRejection);
+
+  /*
+    Desfaz o registro e libera o guard. Em produção o processo não desregistra —
+    ele morre. Isto existe para o teste poder registrar de novo na próxima
+    execução, e é o que torna o guard acima verificável em vez de um efeito
+    global impossível de exercitar.
+  */
+  return () => {
+    process.off('uncaughtException', onUncaught);
+    process.off('unhandledRejection', onRejection);
+    delete target[REGISTERED];
+  };
+};
+
+export { registerFatalHandlers, flushLokiTransport };

package/src/index.ts

@@ -0,0 +1,34 @@
+/*
+  Entrega de log dos serviços gyra-*: monta os transports (Console, File, Loki) a
+  partir de configuração explícita, e registra exceção fatal com flush antes do
+  exit.
+
+  Nada aqui lê variável de ambiente — ver `options.ts` para o porquê. Quem lê é o
+  serviço, no entrypoint dele.
+
+  O exemplo de uso completo está no README do pacote. Ele NÃO fica aqui de
+  propósito: o exemplo mostra o consumidor lendo `process.env`, e como o build
+  publica os comentários (`removeComments: false`), essas linhas apareceriam no
+  `dist/` e fariam um grep de auditoria acusar o pacote de ler ambiente.
+*/
+
+export { buildNestLogger, createLokiTransport } from './logger';
+export type { BuiltLogger, CreateLokiTransportOptions } from './logger';
+
+export { redirectConsoleToNestLogger } from './console-redirect';
+export type { ConsoleRedirectOptions } from './console-redirect';
+
+export { registerFatalHandlers, flushLokiTransport } from './fatal-handlers';
+
+export {
+  DEFAULT_APP_LABEL,
+  DEFAULT_LEVEL,
+  DEFAULT_LOKI_INTERVAL_SECONDS,
+  DEFAULT_LOKI_TIMEOUT_MS,
+} from './options';
+export type {
+  LoggerOptions,
+  LokiOptions,
+  FileOptions,
+  LokiTransportLike,
+} from './options';

package/src/logger.ts

@@ -0,0 +1,255 @@
+/* eslint-disable @typescript-eslint/no-explicit-any */
+
+/*
+  PROVENIÊNCIA: derivado de gyra-core/src/common/logger/LoggerFactory.ts na branch
+  GYR-1555 (tag `backup/GYR-1555-pre-close`), onde o defeito de entrega ao Loki foi
+  diagnosticado e provado contra um Loki 3.0 real: antes, 21 linhas enviadas e 0
+  chegando, sem nenhum erro reportado; depois, 21 de 21.
+
+  Diferenças em relação à fonte, todas deliberadas:
+
+  - Nenhuma leitura de `process.env` — ver `options.ts`.
+  - Sem singleton de módulo. A fonte guardava o transport numa variável de módulo
+    para o handler de exceção fatal alcançá-lo; aqui ele volta no retorno, porque
+    estado global no pacote é o mesmo problema de ler env com outra roupa.
+
+    O singleton da fonte, porém, resolvia um problema real que o retorno sozinho
+    não resolve: serviço que monta VÁRIOS loggers no mesmo processo — o worker do
+    gyra-core monta quatro — teria um batcher por logger, e o flush de exceção
+    fatal drenaria só um deles. Para isso existe `createLokiTransport`: o
+    consumidor cria o transport uma vez e passa o mesmo em `lokiTransport`. O
+    compartilhamento fica explícito no call site, em vez de escondido no módulo.
+  - O redirecionamento de `console.*` saiu para `console-redirect.ts`, como opt-in
+    explícito: é efeito colateral de processo, e importar um pacote não deve mudar
+    o que `console.log` faz.
+*/
+
+import { Logform, format, transports } from 'winston';
+import { WinstonModule } from 'nest-winston';
+import LokiTransport = require('winston-loki');
+import type { LoggerService } from '@nestjs/common';
+import { hostname } from 'os';
+
+import {
+  DEFAULT_APP_LABEL,
+  DEFAULT_LEVEL,
+  DEFAULT_LOKI_INTERVAL_SECONDS,
+  DEFAULT_LOKI_TIMEOUT_MS,
+  LoggerOptions,
+  LokiOptions,
+} from './options';
+
+/*
+  O winston-loki só reportava erro de conexão; a 6.1.6 passou a anexar o status
+  HTTP quando o Loki recusa o envio.
+*/
+type LokiShipError = Error & { statusCode?: number };
+
+export interface BuiltLogger {
+  logger: LoggerService;
+
+  /*
+    Presente somente quando `options.loki` foi informado. Quem trata exceção fatal
+    precisa dele para dar flush antes do exit — sem isso a stack do crash nunca sai
+    do buffer.
+  */
+  lokiTransport?: LokiTransport;
+}
+
+const formatMeta = (meta: Record<string | symbol, any>): string => {
+  const splat = meta[Symbol.for('splat')];
+
+  if (splat?.[0].stack) {
+    return ' ' + JSON.stringify(splat?.[0].stack?.[0], null, 2);
+  }
+
+  if (splat && splat.length) {
+    const obj = splat?.[0]?.context ?? splat;
+
+    if (typeof obj === 'string') {
+      return ' ' + obj;
+    }
+
+    if (
+      Array.isArray(obj) &&
+      obj.length === 1 &&
+      typeof obj[0] === 'object' &&
+      Object.keys(obj[0]).length === 1 &&
+      obj[0].context === undefined
+    ) {
+      return '';
+    }
+
+    return ' ' + JSON.stringify(obj, null, 2);
+  }
+
+  return '';
+};
+
+const buildPrettyFormat = (): Logform.Format => {
+  const localFormat = format.printf(({ message, level, ..._meta }) => {
+    const color = {
+      white: '\x1B[38;2;173;190;203m',
+      blue: '\x1B[34m',
+      red: '\x1B[31m',
+      yellow: '\x1B[33m',
+      cyan: '\x1B[36m',
+      magenta: '\x1B[35m',
+      reset: '\x1B[0m',
+    };
+
+    const levelColor: Record<string, string> = {
+      info: color.white,
+      error: color.red,
+      warn: color.yellow,
+      debug: color.cyan,
+      verbose: color.magenta,
+    };
+
+    const currentColor = levelColor[level];
+
+    const meta = formatMeta(_meta);
+
+    /*
+      `verbose` é o maior level, com 7 letras; +1 para sempre sobrar espaço.
+    */
+    let finalMessage = `${level.padEnd(8)}  ${message}${meta ?? ''}`;
+    finalMessage = finalMessage.replaceAll('\n', `\n${currentColor ?? 'red'}`);
+
+    return `${currentColor}` + finalMessage + `${color.reset}`;
+  });
+
+  return format.combine(format.splat(), localFormat);
+};
+
+export interface CreateLokiTransportOptions extends LokiOptions {
+  service: string;
+  app?: string;
+  instance?: string;
+  pretty?: boolean;
+}
+
+/**
+ * Constrói o transport do Loki isoladamente, para o consumidor COMPARTILHAR um
+ * único batcher entre vários loggers do mesmo processo.
+ *
+ * Use isto quando o serviço monta mais de um logger — o worker do gyra-core monta
+ * quatro. Com um transport por logger, cada um tem seu batcher, e o flush de
+ * exceção fatal cobre só um deles.
+ *
+ *     const lokiTransport = createLokiTransport({ service: 'gyra-core', host });
+ *     const { logger } = buildNestLogger({ service: 'gyra-core', lokiTransport });
+ *     // ...e o mesmo `lokiTransport` nos outros loggers do processo
+ */
+export const createLokiTransport = (
+  options: CreateLokiTransportOptions,
+): LokiTransport => {
+  const { service, app, instance, pretty, ...loki } = options;
+
+  return buildLokiTransport(
+    loki,
+    {
+      service,
+      app: app ?? DEFAULT_APP_LABEL,
+      instance: instance ?? hostname(),
+      ...loki.labels,
+    },
+    pretty
+      ? buildPrettyFormat()
+      : format.combine(format.timestamp(), format.json()),
+  );
+};
+
+const buildLokiTransport = (
+  loki: LokiOptions,
+  labels: Record<string, string>,
+  lineFormat: Logform.Format,
+): LokiTransport =>
+  new LokiTransport({
+    host: loki.host,
+    basicAuth: loki.basicAuth,
+    json: true,
+    labels,
+    interval: loki.interval ?? DEFAULT_LOKI_INTERVAL_SECONDS,
+    batching: true,
+    timeout: loki.timeout ?? DEFAULT_LOKI_TIMEOUT_MS,
+    format: lineFormat,
+
+    /*
+      A falha de entrega tem que ser audível: enquanto era silenciosa, o serviço
+      perdeu ~99,5% dos seus logs sem ninguém notar. Escreve direto no console
+      porque passar pelo logger completo realimentaria o Loki num laço de erro.
+    */
+    onConnectionError: (err: LokiShipError) =>
+      process.stdout.write(
+        `${JSON.stringify({
+          level: 'error',
+          message: `[LOKI-SHIP-FAIL] status=${err?.statusCode ?? 'none'} ${
+            err?.message ?? err
+          }`,
+          timestamp: new Date().toISOString(),
+        })}\n`,
+      ),
+  });
+
+/**
+ * Monta o logger do Nest com os transports pedidos e devolve, junto, o transport
+ * do Loki — necessário para `registerFatalHandlers` dar flush antes do exit.
+ *
+ * Não instala nada no processo: nem handler de exceção, nem redirecionamento de
+ * `console.*`. Esses são opt-in explícito, porque mexem no ciclo de vida do
+ * processo.
+ */
+export const buildNestLogger = (options: LoggerOptions): BuiltLogger => {
+  const lineFormat = options.pretty
+    ? buildPrettyFormat()
+    : format.combine(format.timestamp(), format.json());
+
+  /*
+    Passar os dois é ambíguo: um pede para construir um transport novo, o outro
+    para reusar um existente. Falhar alto é melhor que escolher em silêncio e
+    deixar o consumidor com dois batchers sem saber.
+  */
+  if (options.loki && options.lokiTransport) {
+    throw new Error(
+      '[log-transport] `loki` e `lokiTransport` sao mutuamente exclusivos: ' +
+        'use `loki` para construir um transport novo, ou `lokiTransport` para ' +
+        'reusar um ja construido por createLokiTransport().',
+    );
+  }
+
+  const transportsList: any[] = [
+    new transports.Console({ format: lineFormat }),
+  ];
+
+  let lokiTransport: LokiTransport | undefined;
+
+  if (options.lokiTransport) {
+    lokiTransport = options.lokiTransport as LokiTransport;
+    transportsList.push(lokiTransport);
+  } else if (options.loki) {
+    lokiTransport = buildLokiTransport(
+      options.loki,
+      {
+        service: options.service,
+        app: options.app ?? DEFAULT_APP_LABEL,
+        instance: options.instance ?? hostname(),
+        ...options.loki.labels,
+      },
+      lineFormat,
+    );
+
+    transportsList.push(lokiTransport);
+  } else if (options.file) {
+    transportsList.push(
+      new transports.File({ filename: options.file.filename }),
+    );
+  }
+
+  const logger = WinstonModule.createLogger({
+    level: options.level ?? DEFAULT_LEVEL,
+    transports: transportsList,
+  });
+
+  return { logger, lokiTransport };
+};