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): ArctonLoggerParámetros
| Parámetro | Tipo | Descripción |
|---|---|---|
options | LoggerOptions | Opcional. 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.methody elpathnamede la URL del request (sin el query string) antes de llamar anext(). - Con
pretty: false(el default): una vez quenext()resuelve, loguea una línea de JSON conmethod,path,status(ctx.response.status,200por defecto) ydurationMs— aerrorsi el status es5xx,warnsi es4xx,infoen cualquier otro caso. - Con
pretty: true: loguea una línea→cuando llega el request, y una línea←cuando termina (o una líneaERRsi nada aguas abajo capturó un error lanzado) — ver Modo pretty. - Si
next()rechaza — nada aguas abajo capturó el error — loguea una línea aerror(JSON) o una líneaERR(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. levelfiltra 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.responsepor 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): LoggerParámetros
| Parámetro | Tipo | Descripción |
|---|---|---|
options | LoggerOptions | Opcional. 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
| Campo | Tipo | Default | Descripción |
|---|---|---|---|
level | LevelWithSilent | 'info' | Nivel mínimo a loguear. Cualquier cosa por debajo se descarta antes de siquiera construir un record. |
pretty | boolean | false | Formatea para que lo lea una persona en vez de JSON separado por líneas. |
sink | (line: string) => void | escribe a process.stdout si existe, console.log si no | Dónde se escribe cada línea formateada. |
bindings | Record<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}`)