Download the PHP package knotlog/knotlog without Composer

Knotlog

Wide logging for PHP

Knotlog is inspired by the ideas of loggingsucks.com and implements wide logging as a first-class pattern in PHP. Avoid the pitfalls of traditional logging by using a single structured log event that captures all relevant context of a request as a canonical log line, dramatically improving observability and debugging capabilities.

Transform debugging from archaeological grep sessions into analytical queries with structured, queryable data.

The Problem with Traditional Logging

Traditional logging is broken:

• String search is ineffective: Logs are treated as unstructured text, making it difficult to correlate events
• Optimized for writing, not querying: Developers emit what is convenient, not what is useful
• Missing business context: Standard logs lack the rich dimensionality needed for real investigations

The Wide Logging Solution

Instead of asking "what is my code doing?", ask "what happened to this request?"

A proper wide event contains:

• Infrastructure context (service name, version, region, deployment)
• Request metadata (method, path, duration, status)
• User information (ID, subscription level, account age)
• Business data (cart contents, payment method, features enabled)
• Error details (type, code, message, stack trace)

Installation

Requirements

• PHP 8.4 or newer

Basic Usage

The Log class implements JsonSerializable, so it can be directly encoded to JSON for structured logging systems.

Collecting Multiple Entries

Knotlog also has an append() method that allows adding multiple values under a single key, without overwriting:

This is useful in situations where related items are populated by different parts of the codebase.

Service Logging

Additionally, Knotlog provides a LogList class that can be passed to dependencies and used to attach multiple entries under a single key. This is useful for cases where a service should be able to log multiple related items, without directly having access to the main Log instance, such as:

• Collecting external API calls
• Tracking database statements executed
• Recording multiple commands or queries in a CQRS system

Then, inside the service class (Connection in this example), use the LogList to add entries:

⚠️ LogList entries MUST be objects. Complex objects SHOULD implement JsonSerializable.

The LogList maintains insertion order and will encode as a JSON array:

Exception Logging

It is not recommended to add exception objects to Knotlog. Exception tracing is better handled by other systems, such as Monolog or another PSR-3 logger.

For convenience, Log provides a hasError() method that will return true if either the exception or error keys are set in the log. This is particularly useful for determining if the log should be output when sampling is enabled.

HTTP Middleware

Knotlog provides a PSR-15 middleware to log request and response context.

Knotlog provides a middleware to log uncaught exception context and generate error responses.

Knotlog provides a middleware to flag every response with a 400+ status code as an error in the log. The error is set to the HTTP reason phrase (e.g., "Not Found", "Internal Server Error"). This is particularly useful when log sampling is in effect, ensuring that error responses are always logged.

When using these middleware, the order should be (from first to last):

• LogResponseError - execute the request, flag error responses
• LogRequestResponse - log the request, execute the request, log the response
• LogRequestError - catch uncaught exceptions, log them, generate error response

⚠️ The order may depend on the application middleware stack. Some frameworks prefer a last-in-first-out order.

Console Events

Knotlog provides a Symfony Console event listener that logs command execution and error context.

If you prefer not to use the event system, you can manually log console context:

Log Writers

Knotlog provides a LogWriter interface to enable flexible output destinations for wide log events. The interface defines a contract with a single method write(Log $log): void.

FileWriter

The FileWriter writes log events to a file.

LoggerWriter

The LoggerWriter outputs log events to any PSR-3 compatible logger using message interpolation.

The writer automatically routes log events to the appropriate log level:

• error() - when the log contains an error or exception (uses {error} placeholder)
• info() - for all other log events (uses {message} placeholder)

The entire log context is passed to the logger, allowing it to format and process the data according to its own implementation. The message key can be customized to match your logging schema.

SampledWriter

The SampledWriter is a decorator that samples log events based on a configurable rate, while always logging errors.

The sampled writer ensures that:

• All log events with errors or exceptions are always written (sampling is bypassed)
• Non-error events are sampled at the specified rate
• The sampling decision is made once at construction time and applies to all writes

This is particularly useful for high-traffic applications where logging every successful request would be prohibitively expensive, while still capturing all errors for debugging.

ToggledWriter

The ToggledWriter is a decorator that allows log writing to be enabled or disabled at runtime.

This is useful for conditionally disabling log output based on runtime configuration, such as feature flags or environment-specific settings.

Log Formatters

Knotlog provides a LogFormatter interface to enable flexible formatting of log lines. The interface defines a contract with a single method format(Log $log): string.

JsonFormatter

The JsonFormatter formats log events as JSON strings. Additional flags may be passed through to json_encode:

License

MIT License, see LICENSE file for details.