opencode/docs/LOGGING.md

Logging Architecture

This document describes the structured logging system used across agent-core.

---

Overview

Agent-core uses a centralized structured logging system based on the Log utility. This provides:

• Consistent log formatting across all modules
• Configurable log levels
• Structured metadata for debugging
• Integration with wide events for observability

---

Log Utility

Location

packages/agent-core/src/util/log.ts

Usage

import { Log } from "../util/log"

// Create a logger for your module
const log = Log.create({ service: "my-service" })

// Use structured logging
log.debug("processing request", { requestId: "abc123", size: 1024 })
log.info("operation complete", { duration: 150 })
log.warn("rate limit approaching", { remaining: 10 })
log.error("operation failed", { error: err.message, code: err.code })

Log Levels

Level	Use Case
debug	Detailed debugging information
info	Normal operational messages
warn	Potential issues that don't stop execution
error	Errors that affect functionality

---

Module-Specific Logging

Personas (src/personas/)

import { Log } from "../util/log"

const log = Log.create({ service: "personas.tiara" })
// Or subsystem-specific:
const log = Log.create({ service: "personas.fact-extractor" })

Memory (src/memory/)

const log = Log.create({ service: "memory.qdrant" })

MCP Servers (src/mcp/)

const log = Log.create({ service: "mcp.server" })

Domain Tools (src/domain/)

const log = Log.create({ service: "domain.zee" })
const log = Log.create({ service: "domain.stanley" })

---

Zee Gateway Logging

The zee gateway uses createSubsystemLogger for consistent logging:

import { createSubsystemLogger } from "./logging"

const log = createSubsystemLogger("gateway")
log.info("server started", { port: 3210 })

Subsystems

Subsystem	Purpose
gateway	HTTP/WebSocket server
hooks	Webhook processing
whatsapp	WhatsApp bridge
telegram	Telegram bot
discord	Discord integration

---

Acceptable Console Usage

The following console.log usage patterns are acceptable:

Test Files

Test output is expected to use console for immediate feedback:

// integration.test.ts
console.log(`[TEST] ${msg}`)
console.log(`[✓] ${msg}`)

MCP Servers (stdio protocol)

MCP servers running on stdio use console.error for startup messages:

// Standard MCP server startup
console.error("Portfolio MCP server running on stdio")

Plugin Fallbacks

Plugin system provides fallback logging when structured logger unavailable:

warn: (message, data) => console.warn(`[plugin] ${message}`, data || '')

---

Wide Events

For observability, agent-core integrates wide events:

Configuration

{
  "wideEvents": {
    "enabled": true,
    "sampleRate": 0.02,
    "slowMs": 2000,
    "payloads": "summary"
  }
}

Event Fields

Field	Description
timestamp	ISO timestamp
service	Service name
operation	Operation being performed
duration_ms	Operation duration
status	success or error
metadata	Additional context

---

Best Practices

1. Always use structured logging in production code
2. Include relevant context as metadata, not in the message string
3. Use appropriate log levels - debug for development, info for operations
4. Create service-specific loggers for easier filtering
5. Avoid logging sensitive data (API keys, passwords, tokens)

Good

log.info("user authenticated", { userId: "123", method: "oauth" })

Bad

log.info(`user 123 authenticated via oauth`)  // Unstructured
console.log("user authenticated")             // Not structured
log.info("auth", { token: "secret123" })      // Sensitive data

---

Audit Summary

Component	Logging Method	Status
packages/agent-core/	Log utility	✓ Structured
src/personas/	Log utility	✓ Structured
src/memory/	Log utility	✓ Structured
src/mcp/	Log utility	✓ Structured
src/domain/	Log utility	✓ Structured
zee/src/	createSubsystemLogger	✓ Structured
Test files	console.log	✓ Acceptable
MCP stdio servers	console.error	✓ Protocol standard

---

Generated: 2026-01-12