ArctonArcton
Referencia de la API

Logger

Las factories logger() y createLogger(), la interfaz Logger, y sus opciones, de @arcton/logger.

Resumen

Loguea una línea por request, sin ninguna dependencia en runtime:

import { Arcton } from '@arcton/core'
import { logger } from '@arcton/logger'

const app = Arcton()

app.use(logger())

app.get('/', () => ({ hello: 'world' }))

app.listen()

@arcton/logger es solo app.use(). Ver Logging para la guía orientada al uso.

logger()

Propósito — construye un middleware de logging de requests.

Firma

function logger(options?: LoggerOptions): ArctonLogger

Parámetros

ParámetroTipoDescripción
optionsLoggerOptionsOpcional. Ver abajo cada campo y su default.

Tipo de retorno — un ArctonLogger: un Middleware con una propiedad .logger agregada, pensado para pasarse a app.use().

Comportamiento

  • Lee ctx.request.method y el pathname de la URL del request (sin el query string) antes de llamar a next().
  • Con pretty: false (el default): una vez que next() resuelve, loguea una línea de JSON con method, path, status (ctx.response.status, 200 por defecto) y durationMs — a error si el status es 5xx, warn si es 4xx, info en cualquier otro caso.
  • Con pretty: true: loguea una línea → cuando llega el request, y una línea ← cuando termina (o una línea ERR si nada aguas abajo capturó un error lanzado) — ver Modo pretty.
  • Si next() rechaza — nada aguas abajo capturó el error — loguea una línea a error (JSON) o una línea ERR (pretty), con el error adjunto, y vuelve a lanzar el mismo error sin modificarlo. No se loguea ninguna línea de finalización después.
  • level filtra ambos formatos de la misma manera: 'silent' no imprime nada, y un nivel por encima del que tendría una línea dada la descarta.
  • Nunca corta la cadena ni toca ctx.response por sí mismo — una ruta se comporta exactamente igual que sin ningún logger registrado.

Errores — ninguno.

Ejemplo

import { Arcton } from '@arcton/core'
import { logger } from '@arcton/logger'

const app = Arcton()

app.use(logger({ level: 'debug', pretty: true }))

app.get('/users/:id', ctx => ({ id: ctx.params.id }))
app.get('/boom', () => {
  throw new Error('kaboom')
})

app.listen()

createLogger()

Propósito — construye un Logger independiente, sin depender de ningún request. logger() construye uno de estos internamente para su middleware de logging de requests, pero es igual de usable en un background job o al arrancar.

Firma

function createLogger(options?: LoggerOptions): Logger

Parámetros

ParámetroTipoDescripción
optionsLoggerOptionsOpcional. Ver abajo cada campo y su default.

Tipo de retorno — un Logger.

Errores — ninguno.

Ejemplo

import { createLogger } from '@arcton/logger'

const log = createLogger({ level: 'debug' })

log.info('server starting', { pid: process.pid })

const dbLog = log.child({ component: 'database' })
dbLog.info('query executed', { table: 'users' })

Logger

Propósito — la interfaz que comparten cada método de logging (trace hasta fatal) y child(), devuelta tanto por createLogger() como en .logger de un ArctonLogger.

Firma

interface Logger {
  trace(msg: string, data?: Record<string, unknown>): void
  debug(msg: string, data?: Record<string, unknown>): void
  info(msg: string, data?: Record<string, unknown>): void
  warn(msg: string, data?: Record<string, unknown>): void
  error(msg: string, data?: Record<string, unknown>): void
  fatal(msg: string, data?: Record<string, unknown>): void
  child(bindings: Record<string, unknown>): Logger
}

Parámetros

Propiedad

Tipo

Comportamiento: una llamada por debajo del level configurado retorna de inmediato — no se construye ningún record, no se paga ningún costo de Date/serialización. data en una llamada dada sobrescribe un campo de bindings del mismo nombre solo para ese record. Un valor bajo err (o cualquier key) que sea un Error se serializa a { name, message, stack }, ya que JSON.stringify solo reduce un Error plano a {}. child(bindings) devuelve un nuevo Logger con bindings mezclado sobre el suyo propio — de forma recursiva, así que un nieto lleva todo lo que sus ancestros agregaron — sin mutar el logger sobre el que se llamó.

Ejemplo

import { createLogger } from '@arcton/logger'

const log = createLogger()

log.warn('cache miss', { key: 'user:42' })

const requestLog = log.child({ requestId: 'req_1' })
requestLog.info('handled') // incluye requestId: 'req_1'

LoggerOptions

Propósito — el objeto de opciones aceptado tanto por logger() como por createLogger().

Firma

import type { LevelWithSilent } from '@arcton/logger'

interface LoggerOptions {
  level?: LevelWithSilent
  pretty?: boolean
  sink?: (line: string) => void
  bindings?: Record<string, unknown>
}

Campos

CampoTipoDefaultDescripción
levelLevelWithSilent'info'Nivel mínimo a loguear. Cualquier cosa por debajo se descarta antes de siquiera construir un record.
prettybooleanfalseFormatea para que lo lea una persona en vez de JSON separado por líneas.
sink(line: string) => voidescribe a process.stdout si existe, console.log si noDónde se escribe cada línea formateada.
bindingsRecord<string, unknown>{}Campos mezclados en cada record — lo que child() agrega, no un reemplazo.

Comportamiento: el sink por defecto se resuelve una sola vez, cuando se carga @arcton/logger — process.stdout.write en Node/Bun, console.log en cualquier lugar donde process no exista (un Worker). Pasá el tuyo propio para redirigir la salida — a un archivo, una captura de test, otro servicio — sin cambiar nada más.

LogLevel y LevelWithSilent

Propósito — los nombres de nivel que acepta un Logger, y el conjunto más amplio que acepta LoggerOptions.level.

Firma

type LogLevel = 'trace' | 'debug' | 'info' | 'warn' | 'error' | 'fatal'
type LevelWithSilent = LogLevel | 'silent'

Comportamiento: ordenados como se listan, trace el más bajo — una llamada se escribe cuando el rango de su propio nivel es igual o mayor que el del mínimo configurado. 'silent' supera a cualquier nivel real, así que nada pasa el filtro.

ArctonLogger

Propósito — lo que devuelve logger().

Firma

type ArctonLogger = Middleware & {
  readonly logger: Logger
}

Comportamiento — una función Middleware común, así que app.use(logger()) funciona exactamente igual que app.use(cors()). .logger es la misma instancia de Logger que usa el middleware para loguear, para loguear cualquier cosa fuera del ciclo request/response:

import { Arcton } from '@arcton/core'
import { logger } from '@arcton/logger'

const app = Arcton()
const log = logger()

app.use(log)
app.get('/', () => 'ok')

const server = app.listen({ port: 0 })
log.logger.info(`listening on ${server.url}`)

En esta página