PHP Observability: Structured Logs and Correlation IDs

Structured logs pair machine-readable fields with a correlation ID across a request.

What It Does

Structured logs pair machine-readable fields with a correlation ID across a request. The following examples distinguish a normal use case, a boundary case and a practical application.

Requirements and Compatibility

PHP 8.x and a local test environment. Apply input validation, correct error handling and the requirements of any optional libraries.

The code focuses on the core concept. Production implementation may also need routes, validation, persistence, authorization or deployment tooling.

Example 1: Basic Behavior

Understand the primary operation and its inputs.

<?php
$id = bin2hex(random_bytes(8));
$event = ['level' => 'info', 'request_id' => $id, 'event' => 'started'];
echo json_encode($event, JSON_THROW_ON_ERROR);

Example 2: Another Case

Check failure behavior or a different execution path.

<?php
$exception = new RuntimeException('Internal token=secret123');
$log = ['level' => 'error', 'exception' => get_class($exception), 'code' => $exception->getCode()];
echo json_encode($log, JSON_THROW_ON_ERROR); // Never log the raw secret-bearing message

Practical Example: Putting It to Use

Apply the behavior in a small, controlled scenario.

<?php
$start = hrtime(true);
$durationMs = (hrtime(true) - $start) / 1e6;
echo json_encode(['duration_ms' => round($durationMs, 3)], JSON_THROW_ON_ERROR);

Important Behavior and Edge Cases

Do not log secrets, credentials, personal data or entire untrusted payloads.

Comparison with Related Functions or Approaches

Common Beginner Mistakes

Key Takeaways

• Structured logs pair machine-readable fields with a correlation ID across a request.
• Do not log secrets, credentials, personal data or entire untrusted payloads.
• A PSR-3 logger offers a standard interface to recording events.

Before adapting these examples, verify the return values, test the failure paths and confirm that your application meets its security and environment requirements.