Logging

Logging Protocol - Comprehensive Observability Logging

Unified logging protocol that combines:

Basic kernel logging (LoggerConfig)
Enterprise-grade features (LoggingConfig)
Multiple log destinations (file, console, external services)
Structured logging with enrichment
Log aggregation and forwarding
Integration with external log management systems

Source: packages/spec/src/system/logging.zod.ts

TypeScript Usage

import { ConsoleDestinationConfigSchema, ExtendedLogLevel, ExternalServiceDestinationConfigSchema, FileDestinationConfigSchema, HttpDestinationConfigSchema, LogDestinationSchema, LogDestinationType, LogEnrichmentConfigSchema, LogEntrySchema, LogFormat, LogLevel, LoggerConfigSchema, LoggingConfigSchema, StructuredLogEntrySchema } from '@objectstack/spec/system';
import type { ConsoleDestinationConfig, ExtendedLogLevel, ExternalServiceDestinationConfig, FileDestinationConfig, HttpDestinationConfig, LogDestination, LogDestinationType, LogEnrichmentConfig, LogEntry, LogFormat, LogLevel, LoggerConfig, LoggingConfig, StructuredLogEntry } from '@objectstack/spec/system';

// Validate data
const result = ConsoleDestinationConfigSchema.parse(data);

ConsoleDestinationConfig

Console destination configuration

Properties

Property	Type	Required
stream	`Enum<'stdout' \| 'stderr'>`	optional (default: `"stdout"`)
colors	`boolean`	optional (default: `true`)
prettyPrint	`boolean`	optional (default: `false`)

ExtendedLogLevel

Extended log severity level

Allowed Values

trace
debug
info
warn
error
fatal

ExternalServiceDestinationConfig

External service destination configuration

Properties

Property	Type	Required
endpoint	`string`	optional
region	`string`	optional
credentials	`{ accessKeyId?: string; secretAccessKey?: string; apiKey?: string; environmentId?: string }`	optional
logGroup	`string`	optional
logStream	`string`	optional
index	`string`	optional
config	`Record<string, any>`	optional

FileDestinationConfig

File destination configuration

Properties

Property	Type	Required	Description
path	`string`	✅	Log file path
rotation	`{ maxSize: string; maxFiles: integer; compress: boolean; interval?: Enum<'hourly' \| 'daily' \| 'weekly' \| 'monthly'> }`	optional
encoding	`string`	optional (default: `"utf8"`)
append	`boolean`	optional (default: `true`)

HttpDestinationConfig

HTTP destination configuration

Properties

Property	Type	Required	Description
url	`string`	✅	HTTP endpoint URL
method	`Enum<'POST' \| 'PUT'>`	optional (default: `"POST"`)
headers	`Record<string, string>`	optional
auth	`{ type: Enum<'basic' \| 'bearer' \| 'api_key'>; username?: string; password?: string; token?: string; … }`	optional
batch	`{ maxSize: integer; flushInterval: integer }`	optional
retry	`{ maxAttempts: integer; initialDelay: integer; backoffMultiplier: number }`	optional
timeout	`integer`	optional (default: `30000`)

Nested Shape: `HttpDestinationConfig.auth`

Property	Type	Required	Description
type	`Enum<'basic' \| 'bearer' \| 'api_key'>`	✅	Auth type
username	`string`	optional
password	`string`	optional
token	`string`	optional
apiKey	`string`	optional
apiKeyHeader	`string`	optional (default: `"X-API-Key"`)

LogDestination

Log destination configuration

Properties

Property	Type	Required	Description
name	`string`	✅	Destination name (snake_case)
type	`Enum<'console' \| 'file' \| 'syslog' \| 'elasticsearch' \| 'cloudwatch' \| 'stackdriver' \| 'azure_monitor' \| 'datadog' \| 'splunk' \| 'loki' \| 'http' \| 'kafka' \| 'redis' \| 'custom'>`	✅	Destination type
level	`Enum<'trace' \| 'debug' \| 'info' \| 'warn' \| 'error' \| 'fatal'>`	optional (default: `"info"`)	Extended log severity level
enabled	`boolean`	optional (default: `true`)
console	`{ stream: Enum<'stdout' \| 'stderr'>; colors: boolean; prettyPrint: boolean }`	optional	Console destination configuration
file	`{ path: string; rotation?: object; encoding: string; append: boolean }`	optional	File destination configuration
http	`{ url: string; method: Enum<'POST' \| 'PUT'>; headers?: Record<string, string>; auth?: object; … }`	optional	HTTP destination configuration
externalService	`{ endpoint?: string; region?: string; credentials?: object; logGroup?: string; … }`	optional	External service destination configuration
format	`Enum<'json' \| 'text' \| 'pretty'>`	optional (default: `"json"`)
filterId	`string`	optional	Filter function identifier

Nested Shape: `LogDestination.file`

Property	Type	Required	Description
path	`string`	✅	Log file path
rotation	`{ maxSize: string; maxFiles: integer; compress: boolean; interval?: Enum<'hourly' \| 'daily' \| 'weekly' \| 'monthly'> }`	optional
encoding	`string`	optional (default: `"utf8"`)
append	`boolean`	optional (default: `true`)

Nested Shape: `LogDestination.http`

Property	Type	Required	Description
url	`string`	✅	HTTP endpoint URL
method	`Enum<'POST' \| 'PUT'>`	optional (default: `"POST"`)
headers	`Record<string, string>`	optional
auth	`{ type: Enum<'basic' \| 'bearer' \| 'api_key'>; username?: string; password?: string; token?: string; … }`	optional
batch	`{ maxSize: integer; flushInterval: integer }`	optional
retry	`{ maxAttempts: integer; initialDelay: integer; backoffMultiplier: number }`	optional
timeout	`integer`	optional (default: `30000`)

LogDestinationType

Log destination type

Allowed Values

console
file
syslog
elasticsearch
cloudwatch
stackdriver
azure_monitor
datadog
splunk
loki
http
kafka
redis
custom

LogEnrichmentConfig

Log enrichment configuration

Properties

Property	Type	Required	Description
staticFields	`Record<string, any>`	optional	Static fields added to every log
dynamicEnrichers	`string[]`	optional	Dynamic enricher function IDs
addHostname	`boolean`	optional (default: `true`)
addProcessId	`boolean`	optional (default: `true`)
addEnvironment	`boolean`	optional (default: `true`)
addTimestampFormats	`{ unix: boolean; iso: boolean }`	optional
addCaller	`boolean`	optional (default: `false`)
addCorrelationIds	`boolean`	optional (default: `true`)

LogEntry

Properties

Property	Type	Required	Description
timestamp	`string`	✅	ISO 8601 timestamp
level	`Enum<'debug' \| 'info' \| 'warn' \| 'error' \| 'fatal' \| 'silent'>`	✅	Log severity level
message	`string`	✅	Log message
context	`Record<string, any>`	optional	Structured context data
error	`Record<string, any>`	optional	Error object if present
traceId	`string`	optional	Distributed trace ID
spanId	`string`	optional	Span ID
service	`string`	optional	Service name
component	`string`	optional	Component name (e.g. plugin id)

LogFormat

Log output format

Allowed Values

json
text
pretty

LogLevel

Log severity level

Allowed Values

debug
info
warn
error
fatal
silent

LoggerConfig

Properties

Property	Type	Required	Description
name	`string`	optional	Logger name identifier
level	`Enum<'debug' \| 'info' \| 'warn' \| 'error' \| 'fatal' \| 'silent'>`	optional (default: `"info"`)	Log severity level
format	`Enum<'json' \| 'text' \| 'pretty'>`	optional (default: `"json"`)	Log output format
redact	`string[]`	optional (default: `["password","token","secret","key"]`)	Keys to redact from log context
sourceLocation	`boolean`	optional (default: `false`)	Include file and line number
file	`string`	optional	Path to log file
rotation	`{ maxSize: string; maxFiles: number }`	optional

LoggingConfig

Logging configuration

Properties

Property	Type	Required	Description
name	`string`	✅	Configuration name (snake_case, max 64 chars)
label	`string`	✅	Display label
enabled	`boolean`	optional (default: `true`)
level	`Enum<'trace' \| 'debug' \| 'info' \| 'warn' \| 'error' \| 'fatal'>`	optional (default: `"info"`)	Extended log severity level
default	`{ name?: string; level: Enum<'debug' \| 'info' \| 'warn' \| 'error' \| 'fatal' \| 'silent'>; format: Enum<'json' \| 'text' \| 'pretty'>; redact: string[]; … }`	optional	Default logger configuration
loggers	`Record<string, { name?: string; level: Enum<'debug' \| 'info' \| 'warn' \| 'error' \| 'fatal' \| 'silent'>; format: Enum<'json' \| 'text' \| 'pretty'>; redact: string[]; … }>`	optional	Named logger configurations
destinations	`{ name: string; type: Enum<'console' \| 'file' \| 'syslog' \| 'elasticsearch' \| 'cloudwatch' \| 'stackdriver' \| …>; level: Enum<'trace' \| 'debug' \| 'info' \| 'warn' \| 'error' \| 'fatal'>; enabled: boolean; … }[]`	✅	Log destinations
enrichment	`{ staticFields?: Record<string, any>; dynamicEnrichers?: string[]; addHostname: boolean; addProcessId: boolean; … }`	optional	Log enrichment configuration
redact	`string[]`	optional (has default)	Fields to redact
sampling	`{ enabled: boolean; rate: number; rateByLevel?: Record<string, number> }`	optional
buffer	`{ enabled: boolean; size: integer; flushInterval: integer; flushOnShutdown: boolean }`	optional
performance	`{ async: boolean; workers: integer }`	optional

Nested Shape: `LoggingConfig.default`

Property	Type	Required	Description
name	`string`	optional	Logger name identifier
level	`Enum<'debug' \| 'info' \| 'warn' \| 'error' \| 'fatal' \| 'silent'>`	optional (default: `"info"`)	Log severity level
format	`Enum<'json' \| 'text' \| 'pretty'>`	optional (default: `"json"`)	Log output format
redact	`string[]`	optional (default: `["password","token","secret","key"]`)	Keys to redact from log context
sourceLocation	`boolean`	optional (default: `false`)	Include file and line number
file	`string`	optional	Path to log file
rotation	`{ maxSize: string; maxFiles: number }`	optional

Nested Shape: `LoggingConfig.loggers[string]`

Property	Type	Required	Description
name	`string`	optional	Logger name identifier
level	`Enum<'debug' \| 'info' \| 'warn' \| 'error' \| 'fatal' \| 'silent'>`	optional (default: `"info"`)	Log severity level
format	`Enum<'json' \| 'text' \| 'pretty'>`	optional (default: `"json"`)	Log output format
redact	`string[]`	optional (default: `["password","token","secret","key"]`)	Keys to redact from log context
sourceLocation	`boolean`	optional (default: `false`)	Include file and line number
file	`string`	optional	Path to log file
rotation	`{ maxSize: string; maxFiles: number }`	optional

Nested Shape: `LoggingConfig.destinations[number]`

Log destination configuration

Property	Type	Required	Description
name	`string`	✅	Destination name (snake_case)
type	`Enum<'console' \| 'file' \| 'syslog' \| 'elasticsearch' \| 'cloudwatch' \| 'stackdriver' \| …>`	✅	Destination type
level	`Enum<'trace' \| 'debug' \| 'info' \| 'warn' \| 'error' \| 'fatal'>`	optional (default: `"info"`)	Extended log severity level
enabled	`boolean`	optional (default: `true`)
console	`{ stream: Enum<'stdout' \| 'stderr'>; colors: boolean; prettyPrint: boolean }`	optional	Console destination configuration
file	`{ path: string; rotation?: object; encoding: string; append: boolean }`	optional	File destination configuration
http	`{ url: string; method: Enum<'POST' \| 'PUT'>; headers?: Record<string, string>; auth?: object; … }`	optional	HTTP destination configuration
externalService	`{ endpoint?: string; region?: string; credentials?: object; logGroup?: string; … }`	optional	External service destination configuration
format	`Enum<'json' \| 'text' \| 'pretty'>`	optional (default: `"json"`)
filterId	`string`	optional	Filter function identifier

Nested Shape: `LoggingConfig.enrichment`

Property	Type	Required	Description
staticFields	`Record<string, any>`	optional	Static fields added to every log
dynamicEnrichers	`string[]`	optional	Dynamic enricher function IDs
addHostname	`boolean`	optional (default: `true`)
addProcessId	`boolean`	optional (default: `true`)
addEnvironment	`boolean`	optional (default: `true`)
addTimestampFormats	`{ unix: boolean; iso: boolean }`	optional
addCaller	`boolean`	optional (default: `false`)
addCorrelationIds	`boolean`	optional (default: `true`)

StructuredLogEntry

Structured log entry

Properties

Property	Type	Required	Description
timestamp	`string`	✅	ISO 8601 timestamp
level	`Enum<'trace' \| 'debug' \| 'info' \| 'warn' \| 'error' \| 'fatal'>`	✅	Log severity level
message	`string`	✅	Log message
context	`Record<string, any>`	optional	Structured context
error	`{ name?: string; message?: string; stack?: string; code?: string; … }`	optional	Error details
trace	`{ traceId: string; spanId: string; parentSpanId?: string; traceFlags?: integer }`	optional	Distributed tracing context
source	`{ service?: string; component?: string; file?: string; line?: integer; … }`	optional	Source information
host	`{ hostname?: string; pid?: integer; ip?: string }`	optional	Host information
environment	`string`	optional	Environment (e.g., production, staging)
user	`{ id?: string; username?: string; email?: string }`	optional	User context
request	`{ id?: string; method?: string; path?: string; userAgent?: string; … }`	optional	Request context
labels	`Record<string, string>`	optional	Custom labels
metadata	`Record<string, any>`	optional	Additional metadata

Nested Shape: `StructuredLogEntry.trace`

Property	Type	Required	Description
traceId	`string`	✅	Trace ID
spanId	`string`	✅	Span ID
parentSpanId	`string`	optional	Parent span ID
traceFlags	`integer`	optional	Trace flags

Nested Shape: `StructuredLogEntry.source`

Property	Type	Required	Description
service	`string`	optional	Service name
component	`string`	optional	Component name
file	`string`	optional	Source file
line	`integer`	optional	Line number
function	`string`	optional	Function name

Logging

On this page