---
title: Logging
description: Logging protocol schemas
---

{/* ⚠️  AUTO-GENERATED — DO NOT EDIT. Run build-docs.ts to regenerate. Hand-written docs go in content/docs/guides/. */}

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

<Callout type="info">
**Source:** `packages/spec/src/system/logging.zod.ts`
</Callout>

## TypeScript Usage

```typescript
import { ConsoleDestinationConfig, ExtendedLogLevel, ExternalServiceDestinationConfig, FileDestinationConfig, HttpDestinationConfig, LogDestination, LogDestinationType, LogEnrichmentConfig, LogEntry, LogFormat, LogLevel, LoggerConfig, LoggingConfig, StructuredLogEntry } 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 = ConsoleDestinationConfig.parse(data);
```

---

## ConsoleDestinationConfig

Console destination configuration

### Properties

| Property | Type | Required | Description |
| :--- | :--- | :--- | :--- |
| **stream** | `Enum<'stdout' \| 'stderr'>` | ✅ |  |
| **colors** | `boolean` | ✅ |  |
| **prettyPrint** | `boolean` | ✅ |  |


---

## ExtendedLogLevel

Extended log severity level

### Allowed Values

* `trace`
* `debug`
* `info`
* `warn`
* `error`
* `fatal`


---

## ExternalServiceDestinationConfig

External service destination configuration

### Properties

| Property | Type | Required | Description |
| :--- | :--- | :--- | :--- |
| **endpoint** | `string` | optional |  |
| **region** | `string` | optional |  |
| **credentials** | `Object` | 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** | `Object` | optional |  |
| **encoding** | `string` | ✅ |  |
| **append** | `boolean` | ✅ |  |


---

## HttpDestinationConfig

HTTP destination configuration

### Properties

| Property | Type | Required | Description |
| :--- | :--- | :--- | :--- |
| **url** | `string` | ✅ | HTTP endpoint URL |
| **method** | `Enum<'POST' \| 'PUT'>` | ✅ |  |
| **headers** | `Record<string, string>` | optional |  |
| **auth** | `Object` | optional |  |
| **batch** | `Object` | optional |  |
| **retry** | `Object` | optional |  |
| **timeout** | `integer` | ✅ |  |


---

## 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'>` | ✅ | Extended log severity level |
| **enabled** | `boolean` | ✅ |  |
| **console** | `Object` | optional | Console destination configuration |
| **file** | `Object` | optional | File destination configuration |
| **http** | `Object` | optional | HTTP destination configuration |
| **externalService** | `Object` | optional | External service destination configuration |
| **format** | `Enum<'json' \| 'text' \| 'pretty'>` | ✅ |  |
| **filterId** | `string` | optional | Filter function identifier |


---

## 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` | ✅ |  |
| **addProcessId** | `boolean` | ✅ |  |
| **addEnvironment** | `boolean` | ✅ |  |
| **addTimestampFormats** | `Object` | optional |  |
| **addCaller** | `boolean` | ✅ |  |
| **addCorrelationIds** | `boolean` | ✅ |  |


---

## 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'>` | ✅ | Log severity level |
| **format** | `Enum<'json' \| 'text' \| 'pretty'>` | ✅ | Log output format |
| **redact** | `string[]` | ✅ | Keys to redact from log context |
| **sourceLocation** | `boolean` | ✅ | Include file and line number |
| **file** | `string` | optional | Path to log file |
| **rotation** | `Object` | optional |  |


---

## LoggingConfig

Logging configuration

### Properties

| Property | Type | Required | Description |
| :--- | :--- | :--- | :--- |
| **name** | `string` | ✅ | Configuration name (snake_case, max 64 chars) |
| **label** | `string` | ✅ | Display label |
| **enabled** | `boolean` | ✅ |  |
| **level** | `Enum<'trace' \| 'debug' \| 'info' \| 'warn' \| 'error' \| 'fatal'>` | ✅ | Extended log severity level |
| **default** | `Object` | optional | Default logger configuration |
| **loggers** | `Record<string, Object>` | optional | Named logger configurations |
| **destinations** | `Object[]` | ✅ | Log destinations |
| **enrichment** | `Object` | optional | Log enrichment configuration |
| **redact** | `string[]` | ✅ | Fields to redact |
| **sampling** | `Object` | optional |  |
| **buffer** | `Object` | optional |  |
| **performance** | `Object` | optional |  |


---

## 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** | `Object` | optional | Error details |
| **trace** | `Object` | optional | Distributed tracing context |
| **source** | `Object` | optional | Source information |
| **host** | `Object` | optional | Host information |
| **environment** | `string` | optional | Environment (e.g., production, staging) |
| **user** | `Object` | optional | User context |
| **request** | `Object` | optional | Request context |
| **labels** | `Record<string, string>` | optional | Custom labels |
| **metadata** | `Record<string, any>` | optional | Additional metadata |


---

