Child Loggers

Create namespaced loggers for different parts of your application.

Overview

Child loggers help you:

Organize logs — Group logs by component or feature
Filter logs — Find logs from specific parts of your app
Inherit configuration — Share settings with parent logger

Creating Child Loggers

typescript

1import { createLogger } from 'vestig'
2 
3const logger = createLogger({
4  level: 'info',
5  context: { service: 'api' }
6})
7 
8// Create child loggers
9const dbLogger = logger.child('database')
10const authLogger = logger.child('auth')
11const cacheLogger = logger.child('cache')
12 
13dbLogger.info('Query executed')
14// → namespace: "database"
15 
16authLogger.info('User logged in')
17// → namespace: "auth"

Namespace Hierarchy

Child loggers can be nested to create hierarchies:

typescript

1const appLogger = logger.child('app')
2const userService = appLogger.child('user-service')
3const userRepo = userService.child('repository')
4 
5userRepo.info('User created')
6// → namespace: "app:user-service:repository"

Configuration Merge Semantics

Understanding how child logger configuration works is important for predictable behavior.

Merge Behavior

Child loggers merge configuration with their parent using object spread:

typescript

1// Simplified internal implementation:
2const childConfig = {
3  ...parentConfig,    // Start with parent config
4  ...childOptions,    // Override with child options
5  namespace: fullNamespace,
6  context: { ...parentConfig.context, ...childOptions?.context }
7}

Config Properties

Property	Inheritance Behavior
`level`	Child overrides parent if specified
`enabled`	Child overrides parent if specified
`structured`	Child overrides parent if specified
`sanitize`	Child overrides parent if specified
`context`	Merged (parent + child, child wins conflicts)
`namespace`	Concatenated with `:` separator
`transports`	Not inherited - use same instance

Override Level

typescript

1// Parent with info level
2const logger = createLogger({ level: 'info' })
3 
4// Child with debug level (for detailed debugging)
5const debugLogger = logger.child('debug', {
6  level: 'debug'
7})
8 
9debugLogger.debug('This is visible')
10logger.debug('This is not visible')

Context Merging

Context is deeply merged, with child values taking precedence:

typescript

1const logger = createLogger({
2  context: { service: 'api', version: '1.0', env: 'prod' }
3})
4 
5const v2Logger = logger.child('v2', {
6  context: { version: '2.0' }  // Only override version
7})
8 
9v2Logger.info('Request')
10// → context: { service: 'api', version: '2.0', env: 'prod' }
11//            ↑ from parent    ↑ from child    ↑ from parent

Transports Are Shared

Child loggers share the same transport instances as their parent:

typescript

1const logger = createLogger()
2logger.addTransport(new HTTPTransport({ url: '...' }))
3 
4const child = logger.child('module')
5 
6// Both use the same HTTPTransport instance
7logger.info('Parent log')  // → sent via HTTPTransport
8child.info('Child log')    // → sent via same HTTPTransport

Caching Behavior

With No Config (Cached)

Child loggers without config options are cached via WeakRef:

typescript

1const logger = createLogger()
2 
3const child1 = logger.child('api')
4const child2 = logger.child('api')
5 
6child1 === child2  // true (same instance)

This prevents memory bloat when creating child loggers repeatedly (e.g., per-request).

With Config (Not Cached)

Child loggers with config options are never cached:

typescript

1const logger = createLogger()
2 
3const child1 = logger.child('api', { level: 'debug' })
4const child2 = logger.child('api', { level: 'debug' })
5 
6child1 === child2  // false (different instances)

Memory Management

Cached children use WeakRef, allowing garbage collection when no references remain:

typescript

1function processRequest(id: string) {
2  const requestLogger = logger.child(id)  // Cached by namespace
3  requestLogger.info('Processing')
4  // When function exits and no references remain, GC can collect
5}
6 
7// Safe to call millions of times - old children are GC'd
8for (let i = 0; i < 1000000; i++) {
9  processRequest(`req-${i}`)
10}

Tip: For request-scoped logging with unique IDs, use context instead of namespace:

typescript

1// ✅ Better: Single cached child, unique context per request
2function processRequest(id: string) {
3  const requestLogger = logger.child('request', { context: { requestId: id } })
4  requestLogger.info('Processing')
5}

Use Cases

By Feature

typescript

1const logger = createLogger()
2 
3const authLogger = logger.child('auth')
4const paymentLogger = logger.child('payment')
5const notificationLogger = logger.child('notification')

By Layer

typescript

1const logger = createLogger()
2 
3const controllerLogger = logger.child('controller')
4const serviceLogger = logger.child('service')
5const repositoryLogger = logger.child('repository')

By Component (React)

typescript

1// In a Server Component
2import { getLogger } from '@vestig/next'
3 
4export async function UserProfile({ userId }) {
5  const log = await getLogger('components:user-profile')
6 
7  log.debug('Rendering user profile', { userId })
8 
9  // ...
10}

Pattern: Service Logger

Common pattern for creating a logger per service:

typescript

1// lib/logger.ts
2import { createLogger } from 'vestig'
3 
4const rootLogger = createLogger({
5  level: process.env.LOG_LEVEL ?? 'info',
6  context: {
7    service: process.env.SERVICE_NAME,
8    version: process.env.VERSION
9  }
10})
11 
12export function getServiceLogger(namespace: string) {
13  return rootLogger.child(namespace)
14}

typescript

1// services/user.ts
2import { getServiceLogger } from '@/lib/logger'
3 
4const log = getServiceLogger('user-service')
5 
6export async function createUser(data: UserInput) {
7  log.info('Creating user', { email: data.email })
8  // ...
9}

Filtering by Namespace

Use namespace patterns in your log aggregation:

bash

1# Find all database logs
2grep '"namespace":"database' logs.json
3 
4# Find all auth-related logs
5grep '"namespace":"auth' logs.json

Or configure transports to filter:

typescript

1new HTTPTransport({
2  endpoint: '...',
3  filter: (entry) => entry.namespace?.startsWith('api:')
4})

Namespace in Sampling

Use namespace sampling for fine-grained control:

typescript

1import { createNamespaceSampler, createLogger } from 'vestig'
2 
3const sampler = createNamespaceSampler({
4  defaultRate: 0.1,
5  rates: {
6    'api:*': 0.5,      // 50% of API logs
7    'db:*': 0.25,      // 25% of DB logs
8    'auth:*': 1.0      // All auth logs
9  }
10})
11 
12const logger = createLogger({
13  sampling: { sampler }
14})

Child Loggers

Create namespaced loggers for different parts of your application.

Overview

Child loggers help you:

Organize logs — Group logs by component or feature
Filter logs — Find logs from specific parts of your app
Inherit configuration — Share settings with parent logger

Creating Child Loggers

typescript

1import { createLogger } from 'vestig'
2 
3const logger = createLogger({
4  level: 'info',
5  context: { service: 'api' }
6})
7 
8// Create child loggers
9const dbLogger = logger.child('database')
10const authLogger = logger.child('auth')
11const cacheLogger = logger.child('cache')
12 
13dbLogger.info('Query executed')
14// → namespace: "database"
15 
16authLogger.info('User logged in')
17// → namespace: "auth"

Namespace Hierarchy

Child loggers can be nested to create hierarchies:

typescript

1const appLogger = logger.child('app')
2const userService = appLogger.child('user-service')
3const userRepo = userService.child('repository')
4 
5userRepo.info('User created')
6// → namespace: "app:user-service:repository"

Configuration Merge Semantics

Understanding how child logger configuration works is important for predictable behavior.

Merge Behavior

Child loggers merge configuration with their parent using object spread:

typescript

1// Simplified internal implementation:
2const childConfig = {
3  ...parentConfig,    // Start with parent config
4  ...childOptions,    // Override with child options
5  namespace: fullNamespace,
6  context: { ...parentConfig.context, ...childOptions?.context }
7}

Config Properties

Property	Inheritance Behavior
`level`	Child overrides parent if specified
`enabled`	Child overrides parent if specified
`structured`	Child overrides parent if specified
`sanitize`	Child overrides parent if specified
`context`	Merged (parent + child, child wins conflicts)
`namespace`	Concatenated with `:` separator
`transports`	Not inherited - use same instance

Override Level

typescript

1// Parent with info level
2const logger = createLogger({ level: 'info' })
3 
4// Child with debug level (for detailed debugging)
5const debugLogger = logger.child('debug', {
6  level: 'debug'
7})
8 
9debugLogger.debug('This is visible')
10logger.debug('This is not visible')

Context Merging

Context is deeply merged, with child values taking precedence:

typescript

1const logger = createLogger({
2  context: { service: 'api', version: '1.0', env: 'prod' }
3})
4 
5const v2Logger = logger.child('v2', {
6  context: { version: '2.0' }  // Only override version
7})
8 
9v2Logger.info('Request')
10// → context: { service: 'api', version: '2.0', env: 'prod' }
11//            ↑ from parent    ↑ from child    ↑ from parent

Transports Are Shared

Child loggers share the same transport instances as their parent:

typescript

1const logger = createLogger()
2logger.addTransport(new HTTPTransport({ url: '...' }))
3 
4const child = logger.child('module')
5 
6// Both use the same HTTPTransport instance
7logger.info('Parent log')  // → sent via HTTPTransport
8child.info('Child log')    // → sent via same HTTPTransport

Caching Behavior

With No Config (Cached)

Child loggers without config options are cached via WeakRef:

typescript

1const logger = createLogger()
2 
3const child1 = logger.child('api')
4const child2 = logger.child('api')
5 
6child1 === child2  // true (same instance)

This prevents memory bloat when creating child loggers repeatedly (e.g., per-request).

With Config (Not Cached)

Child loggers with config options are never cached:

typescript

1const logger = createLogger()
2 
3const child1 = logger.child('api', { level: 'debug' })
4const child2 = logger.child('api', { level: 'debug' })
5 
6child1 === child2  // false (different instances)

Memory Management

Cached children use WeakRef, allowing garbage collection when no references remain:

typescript

1function processRequest(id: string) {
2  const requestLogger = logger.child(id)  // Cached by namespace
3  requestLogger.info('Processing')
4  // When function exits and no references remain, GC can collect
5}
6 
7// Safe to call millions of times - old children are GC'd
8for (let i = 0; i < 1000000; i++) {
9  processRequest(`req-${i}`)
10}

Tip: For request-scoped logging with unique IDs, use context instead of namespace:

typescript

1// ✅ Better: Single cached child, unique context per request
2function processRequest(id: string) {
3  const requestLogger = logger.child('request', { context: { requestId: id } })
4  requestLogger.info('Processing')
5}

Use Cases

By Feature

typescript

1const logger = createLogger()
2 
3const authLogger = logger.child('auth')
4const paymentLogger = logger.child('payment')
5const notificationLogger = logger.child('notification')

By Layer

typescript

1const logger = createLogger()
2 
3const controllerLogger = logger.child('controller')
4const serviceLogger = logger.child('service')
5const repositoryLogger = logger.child('repository')

By Component (React)

typescript

1// In a Server Component
2import { getLogger } from '@vestig/next'
3 
4export async function UserProfile({ userId }) {
5  const log = await getLogger('components:user-profile')
6 
7  log.debug('Rendering user profile', { userId })
8 
9  // ...
10}

Pattern: Service Logger

Common pattern for creating a logger per service:

typescript

1// lib/logger.ts
2import { createLogger } from 'vestig'
3 
4const rootLogger = createLogger({
5  level: process.env.LOG_LEVEL ?? 'info',
6  context: {
7    service: process.env.SERVICE_NAME,
8    version: process.env.VERSION
9  }
10})
11 
12export function getServiceLogger(namespace: string) {
13  return rootLogger.child(namespace)
14}

typescript

1// services/user.ts
2import { getServiceLogger } from '@/lib/logger'
3 
4const log = getServiceLogger('user-service')
5 
6export async function createUser(data: UserInput) {
7  log.info('Creating user', { email: data.email })
8  // ...
9}

Filtering by Namespace

Use namespace patterns in your log aggregation:

bash

1# Find all database logs
2grep '"namespace":"database' logs.json
3 
4# Find all auth-related logs
5grep '"namespace":"auth' logs.json

Or configure transports to filter:

typescript

1new HTTPTransport({
2  endpoint: '...',
3  filter: (entry) => entry.namespace?.startsWith('api:')
4})

Namespace in Sampling

Use namespace sampling for fine-grained control:

typescript

1import { createNamespaceSampler, createLogger } from 'vestig'
2 
3const sampler = createNamespaceSampler({
4  defaultRate: 0.1,
5  rates: {
6    'api:*': 0.5,      // 50% of API logs
7    'db:*': 0.25,      // 25% of DB logs
8    'auth:*': 1.0      // All auth logs
9  }
10})
11 
12const logger = createLogger({
13  sampling: { sampler }
14})