Logging Package Cheatsheet

Code-verified reference for packages/logging.

Core Pipeline

Cognesy\Logging\Pipeline\LoggingPipeline:

LoggingPipeline::create(): self
filter(EventFilter $filter): self
enrich(EventEnricher $enricher): self
format(EventFormatter $formatter): self
write(LogWriter $writer): self
build(): callable (callable(Event): void)
__invoke(): callable (returns build())

build() snapshots the current pipeline configuration. Later builder mutations do not affect an already-built callable. Minimal usage:

use Cognesy\Events\Event;
use Cognesy\Logging\Enrichers\BaseEnricher;
use Cognesy\Logging\Formatters\DefaultFormatter;
use Cognesy\Logging\LogEntry;
use Cognesy\Logging\Pipeline\LoggingPipeline;
use Cognesy\Logging\Writers\CallableWriter;

$pipeline = LoggingPipeline::create()
    ->enrich(new BaseEnricher())
    ->format(new DefaultFormatter())
    ->write(CallableWriter::create(function (LogEntry $entry): void {}))
    ->build();

$pipeline(new Event(['scope' => 'demo']));

Contracts

EventFilter::__invoke(Event $event): bool
EventEnricher::__invoke(Event $event): LogContext
EventFormatter::__invoke(Event $event, LogContext $context): LogEntry
LogWriter::__invoke(LogEntry $entry): void
ContextProvider::getContext(): array

Value Objects

LogEntry:

LogEntry::create(string $level, string $message, array $context = [], ?DateTimeImmutable $timestamp = null, string $channel = 'default'): self
withContext(array $additionalContext): self
withLevel(string $level): self
withMessage(string $message): self
withChannel(string $channel): self
isLevel(string $level): bool
isLevelOrAbove(string $minimumLevel): bool
jsonSerialize(): array

LogContext:

LogContext::fromEvent(Event $event, array $additionalContext = []): self
withFrameworkContext(array $context): self
withPerformanceMetrics(array $metrics): self
withUserContext(array $context): self
toArray(): array
jsonSerialize(): array

Built-In Filters

LogLevelFilter(string $minimumLevel = LogLevel::DEBUG)
EventClassFilter(array $excludedClasses = [], array $includedClasses = [])
EventHierarchyFilter(array $excludedClasses = [], array $includedClasses = [])
CompositeFilter(EventFilter ...$filters) (AND logic)

EventHierarchyFilter helpers:

EventHierarchyFilter::httpEventsOnly(): self
EventHierarchyFilter::structuredOutputEventsOnly(): self
EventHierarchyFilter::excludeHttpDebug(): self

Built-In Enrichers

BaseEnricher
LazyEnricher(Closure $contextProvider, string $contextKey = 'framework')
LazyEnricher::framework(Closure $provider): self
LazyEnricher::metrics(Closure $provider): self
LazyEnricher::user(Closure $provider): self

Built-In Formatters

DefaultFormatter(string $messageTemplate = '{event_class}: {message}', string $channel = 'instructor')
MessageTemplateFormatter(array $templates = [], string $defaultTemplate = '{event_name}', string $channel = 'instructor')

Template placeholders supported by MessageTemplateFormatter:

{event_class}, {event_name}, {event_id}
event-data placeholders like {method}, {url}
framework placeholders like {framework.request_id}

Built-In Writers

PsrLoggerWriter(LoggerInterface $logger)
MonologChannelWriter(Logger $logger, bool $useEntryChannel = true)
CallableWriter(Closure $writer)
CallableWriter::create(callable $writer): self
CompositeWriter(LogWriter ...$writers)

Framework Factories

Config keys:

channel (string)
level (string)
exclude_events (array<class-string>)
include_events (array<class-string>)
templates (array<string, string>)

SymfonyLoggingFactory:

create(ContainerInterface $container, LoggerInterface $logger, array $config = []): callable
defaultSetup(ContainerInterface $container, LoggerInterface $logger): callable
productionSetup(ContainerInterface $container, LoggerInterface $logger): callable

Wiretap Integration

Cognesy\Logging\Integrations\EventPipelineWiretap:

EventPipelineWiretap(mixed $pipeline) — wraps a callable(Event): void pipeline
__invoke(object $event): void — forwards Event instances to the pipeline, ignores non-Event objects

Zero-Config JSONL Logging (`EventLog`)

Cognesy\Logging\EventLog is a factory that replaces new EventDispatcher(...) in runtime default paths. It automatically attaches a structured JSONL file sink when INSTRUCTOR_LOG_PATH is set in the environment.

Enabling

# Shell: set env var before running your script
INSTRUCTOR_LOG_PATH=/tmp/instructor.jsonl php my-script.php

# Or from PHP (call once at bootstrap)
EventLog::enable('/tmp/instructor.jsonl');

# Or configure the whole default logging profile
EventLog::enable(new EventLogConfig(
    path: '/tmp/instructor.jsonl',
    level: LogLevel::DEBUG,
    excludeHttpDebug: true,
    stringClipLength: 2048,
));

Usage in runtimes (internal)

// Before
$events = $events ?? new EventDispatcher('instructor.structured-output.runtime');

// After
$events = $events ?? EventLog::root('instructor.structured-output.runtime');

EventLog::root() creates a plain dispatcher when no path is set — no I/O, zero cost in tests. When INSTRUCTOR_LOG_PATH is set, it attaches a logging wiretap filtered at INFO level (default). For child dispatchers that bubble to a root:

$childEvents = EventLog::child('child-component', $parentEvents);

API

Cognesy\Logging\EventLog:

EventLog::enable(string|EventLogConfig $config): void — programmatic opt-in; call at bootstrap
EventLog::disable(): void — reset programmatic opt-in
EventLog::root(string $name, ?LoggerInterface $logger = null): CanHandleEvents
EventLog::child(string $name, CanHandleEvents $parent): CanHandleEvents

File-backed defaults

Default values now come from packages/logging/resources/config/event_log.yaml. Override that file in app-level config by adding config/event_log.yaml. Available knobs:

path
level
includeEvents
excludeEvents
useHierarchyFilter
excludeHttpDebug
includePayload
includeCorrelation
includeEventMetadata
includeComponentMetadata
stringClipLength

Example:

path: /tmp/instructor.jsonl
level: debug
excludeHttpDebug: true
excludeEvents:
  - Cognesy\\Http\\Events\\DebugRequestBodyUsed
stringClipLength: 2048

Log level and overrides

Default minimum level: INFO. Override via env:

INSTRUCTOR_LOG_PATH=/tmp/instructor.jsonl INSTRUCTOR_LOG_LEVEL=debug php my-script.php

JSONL format

Each line is a JSON object:

{"timestamp":"2026-03-18T12:00:00+00:00","level":"info","channel":"instructor.structured-output.runtime","message":"StructuredOutputStarted","context":{"event_id":"...","event_class":"...","package":"instructor","component":"instructor.structured-output.runtime","correlation":{},"payload":{}}}

Off by default

No INSTRUCTOR_LOG_PATH → EventLog::root() returns a plain dispatcher, no files written
No test detection heuristics — the empty path is the only gating signal
Framework injections (Laravel, Symfony) pass $events explicitly → EventLog::root() never runs

Callsite conventions (internal)

There are three situations and each has its own correct pattern: 1. Runtime/builder with optional user-provided dispatcher Use ?? — EventLog only runs when no dispatcher is provided:

// Correct: user's dispatcher takes precedence; EventLog only as default
$this->events = $events ?? EventLog::root('http.client.runtime');

2. Configurator/builder that accepts a parent dispatcher When a parent is provided, create a plain child dispatcher — EventLog must NOT be involved. When no parent is provided, use EventLog::root() as the standalone default:

// Correct: user-provided parent → plain child dispatcher; standalone → EventLog
$events = $parentEvents !== null
    ? new EventDispatcher('agent-builder', $parentEvents)
    : EventLog::root('agent-builder');

Do NOT use EventLog::child() here — that would attach EventLog to a dispatcher the user already controls, which may have its own logging configured. 3. Zero-config static factory (no dispatcher parameter) Always use EventLog::root() directly — there is no user-supplied dispatcher to respect:

// Correct: standalone factory, no parent
public static function default(): self {
    $events = EventLog::root('agent-loop');
    // ...
}

Rule of thumb: EventLog should be involved only when the code, not the user, is responsible for creating the dispatcher. If the user passes anything in, bypass EventLog entirely.

Observability components (internal)

EventLogConfig — loads event_log.yaml defaults and applies env overrides
FileJsonLogWriter — append-only JSONL sink; swallows write errors silently
StructuredEventFormatter — normalizes Event → LogEntry with correlation fields

Framework Integrations

Laravel:

Laravel-specific logging integration lives in packages/laravel.

Symfony:

Cognesy\Logging\Integrations\Symfony\InstructorLoggingBundle
InstructorLoggingExtension registers instructor_logging.pipeline_factory and instructor_logging.pipeline_listener.
WiretapEventBusPass adds one wiretap() method call to the configured event bus service.

Symfony config root (instructor_logging):

enabled (bool, default true)
preset (default|production|custom)
event_bus_service (string, default Cognesy\Events\Contracts\CanHandleEvents)
config.channel (string)
config.level (emergency|alert|critical|error|warning|notice|info|debug)
config.exclude_events (string[])
config.include_events (string[])
config.templates (array<string, string>)

​Logging Package Cheatsheet

​Core Pipeline

​Contracts

​Value Objects

​Built-In Filters

​Built-In Enrichers

​Built-In Formatters

​Built-In Writers

​Framework Factories

​Wiretap Integration

​Zero-Config JSONL Logging (EventLog)

​Enabling

​Usage in runtimes (internal)

​API

​File-backed defaults

​Log level and overrides

​JSONL format

​Off by default

​Callsite conventions (internal)

​Observability components (internal)

​Framework Integrations