Download the PHP package gilbitron/canonical-context-logging without Composer

Canonical Context Logging - PHP SDK

PHP SDK for Canonical Context Logging - structured JSON logs with one wide event per request.

Overview

This package implements the Canonical Context Logging pattern:

1. Emit structured logs only - JSON, consistent keys, no free-text messages
2. Log one "wide event" per request - Capture all context in a single final log entry
3. Accumulate context via middleware - Build an event object at request start, enrich it throughout execution, emit once at the end
4. Prefer context over volume - Fewer logs, richer data
5. Tail-sample aggressively - Always keep errors + slow requests; sample the rest
6. Store logs as queryable data - Columnar DB + SQL > grep
7. OTel is transport, not design - You decide what to log; business context is your job

Requirements

• PHP 8.1 or higher
• OpenTelemetry SDK

Installation

Quick Start

Basic Usage (Framework-Agnostic)

With Error Handling

Configuration

Exporter Options

Console Exporter (Development)

For local development, you can use the console exporter to output logs to stdout/stderr:

OTLP Exporter (Production)

The OTLP exporter uses the official OpenTelemetry SDK and reads configuration from environment variables:

Environment Variables:

The exporter reads standard OpenTelemetry environment variables:

• OTEL_EXPORTER_OTLP_ENDPOINT - OTLP endpoint URL (default: http://localhost:4318)
• OTEL_EXPORTER_OTLP_PROTOCOL - Protocol to use: http/protobuf or http/json (default: http/protobuf)
• OTEL_EXPORTER_OTLP_HEADERS - Headers as comma-separated key=value pairs (e.g., key1=value1,key2=value2)
• OTEL_EXPORTER_OTLP_TIMEOUT - Timeout in seconds (default: 10)

Example:

File Exporter

Write logs to a file in JSONL format (one JSON object per line):

The FileExporter automatically creates the directory structure if it doesn't exist and appends each log entry as a new line (JSONL format).

Custom Exporter

Implement ExporterInterface to create your own exporter:

Logger Configuration

Tail-Sampling Rules:

• Errors are always logged
• Slow requests (above threshold) are always logged
• Other requests are sampled based on sampleRate
• If sampleRate is null, all requests are logged

Context Storage

Singleton Storage (Framework-Agnostic)

Container Storage (Framework-Specific)

For framework integration, create a custom storage implementation that uses your framework's container.

EventContext API

The EventContext class accumulates all context for a single request:

Log Output Format

The structured log output follows this schema:

Best Practices

1. One log per request - Use middleware to emit a single log at request end
2. Accumulate context - Add business context throughout request execution
3. Structured data only - No free-text messages, use consistent keys
4. Tail-sample - Configure sampling to reduce volume while keeping errors and slow requests
5. Business context - Include user, org, plan, feature flags, etc. - anything that helps answer questions
6. Error handling - Always capture exceptions in context, even if you re-throw them

License

MIT