Logging

Overview

Fracta uses Go’s log/slog for structured JSON logging, wrapped by the internal/fractalog package. All log output includes a "component" tag identifying the subsystem that emitted it. Fracta also has an internal event bus for structured lifecycle and infrastructure events. The event bus does not replace slog or fractalog; it uses them through LogSink. See docs/event-bus.md for the event-bus architecture and how it relates to logging.

Configuration

Add a logging section to fracta.yaml:

logging:
  file: fracta.log   # log file path
  level: info       # debug | info | warn | error

Path resolution:

Absolute path (e.g., /var/log/fracta.log) — used as-is
Relative path or bare filename (e.g., fracta.log, logs/fracta.log) — resolved from the working directory where the fracta binary runs

Level precedence: logging.level in config > FRACTA_LOG_LEVEL env var > default (info) When logging.file is set, logs go to both stderr and the file. When omitted, logs go to stderr only (original behavior).

Full fracta.yaml example

# fracta.yaml — logging in context with other config sections

logging:
  file: .fracta/fracta.log       # logs alongside state.db in .fracta/
  level: info                 # debug | info | warn | error

connections:
  falkordb:
    type: redis
    url: ${FALKORDB_URL}
    graph_name: fracta_knowledge
  elastic_main:
    type: elasticsearch
    url: ${ELASTIC_URL}
    api_key: ${ELASTIC_API_KEY}

runtime:
  backend: local
  state:
    driver: sqlite
    sqlite:
      path: .fracta/state.db

project:
  default_base_branch: main

agents:
  default_host_type: claude
  default_mode: batch

hosts:
  claude:
    adapter: claude
    model_tiers:
      heavy: opus
      medium: sonnet
      light: haiku

ontology:
  schemas:
    - uri: embed://graph-schema/core
    - uri: embed://graph-schema/threat-hunting

mcp_servers:
  servers:
    elastic:
      local:
        command: podman
        args: ["run", "-i", "--rm", "docker.elastic.co/mcp/elasticsearch", "stdio"]
        env:
          ES_URL: "${ELASTIC_URL}"
          ES_API_KEY: "${ELASTIC_API_KEY}"

strategy:
  dir: strategies
  pool_size: 2

Architecture

fractalog.Init()         ← called once at startup (cmd/root.go init)
                         sets slog.Default() → JSON handler → stderr

fractalog.AttachFile()   ← called after config parse (cmd/serve.go, cmd/worker.go)
                         replaces slog.Default() → JSON handler → MultiWriter(stderr, file)

fractalog.Component(name) ← called by every subsystem
                           returns *slog.Logger with "component" = name

Event Bus Interaction

Logging architecture is still based on slog + fractalog. What changed with spec-28 is the path for event-style observability:

bus emitters send events.Event through events.Bus
LogSink writes the event as a normal structured log line under component events
StoreSink persists the event without logging again
K8sEventSink may also export selected events to Kubernetes Events in K8s mode

So:

ordinary application logs still use fractalog.Component("name") directly
bus events become structured log lines through LogSink
logging configuration and output destinations are unchanged

Usage

Struct with a logger field

import "github.com/darkquasar/fracta/internal/fractalog"

type Gateway struct {
    logger *slog.Logger
}

func New() *Gateway {
    return &Gateway{
        logger: fractalog.Component("gateway"),
    }
}

func (g *Gateway) DoSomething() {
    g.logger.Info("something happened", "key", "value")
}

Standalone function

func reconcileOrphans(ctx context.Context) {
    log := fractalog.Component("serve")
    log.Info("reconciling", "count", n)
}

Rules

Always use fractalog.Component("name") — never bare slog.Info() or slog.Default().With("component", ...).
Never use package-level var log = fractalog.Component(...) — the handler is captured at call time, which is before AttachFile runs. Always create loggers inside functions.
Component names should match the package or subsystem name (e.g., "gateway", "reconciler", "serve", "worker").

Component Registry

Component	Package
`serve`	`cmd/serve.go`
`worker`	`cmd/worker.go`
`controlplane`	`internal/controlplane`
`reaper`	`internal/controlplane`
`signal-handler`	`internal/controlplane`
`admission`	`internal/admission`
`orchestrator`	`internal/orchestrator`
`worker`	`internal/worker`
`pgqueue`	`internal/queue/postgres`
`mcpclient`	`internal/mcpclient`
`mcpserver`	`internal/mcpserver`
`strategy`	`internal/mcpserver` (strategy tools)
`gateway`	`internal/gateway`
`graph`	`internal/graph/falkordb`
`rag`	`internal/graph/rag`
`reconciler`	`internal/registry`
`sidecar`	`internal/strategy`
`mailbox`	`internal/state/sqlitestore`
`config`	`internal/config`
`loaders`	`internal/loaders`

Log Format

All output is JSON (one object per line):

{"time":"2026-03-30T12:00:00Z","level":"INFO","msg":"registered server","component":"gateway","server":"vendor_mcp","tools":12}

Filtering Examples

# All gateway logs
jq 'select(.component == "gateway")' fracta.log

# Errors only
jq 'select(.level == "ERROR")' fracta.log

# Strategy warnings
jq 'select(.component == "strategy" and .level == "WARN")' fracta.log

Introduction

Getting Started

Swarm

Strategies

Patterns

Guides

Reference

Operations

Development

Contributing

Overview

Configuration

Full fracta.yaml example

Architecture

Event Bus Interaction

Usage

Struct with a logger field

Standalone function

Rules

Component Registry

Log Format

Filtering Examples

​Overview

​Configuration

​Full fracta.yaml example

​Architecture

​Event Bus Interaction

​Usage

​Struct with a logger field

​Standalone function

​Rules

​Component Registry

​Log Format

​Filtering Examples

Overview

Configuration

Full fracta.yaml example

Architecture

Event Bus Interaction

Usage

Struct with a logger field

Standalone function

Rules

Component Registry

Log Format

Filtering Examples