Structured Logging

Also Known As

TL;DR

Explanation

Structured logs include consistent fields: timestamp, level, message, request_id, user_id, duration_ms, context. JSON is the de facto format for structured logs. Tools like Elasticsearch, Datadog, and CloudWatch Logs Insights can query structured logs efficiently. PHP libraries: Monolog with JsonFormatter. Correlation IDs (request_id) thread a single request across all log entries — essential for debugging distributed systems. Never log PII (email, password, credit card) in plain text.

Common Misconception

Why It Matters

Common Mistakes

• Logging PII (email addresses, passwords, tokens) in plain text — creates compliance and security risk.
• Not including a correlation/request ID — impossible to trace a single request across multiple log entries.
• Using different field names for the same concept across services — breaks cross-service log queries.

Avoid When

• Never log sensitive values — passwords, tokens, credit card numbers, or full request bodies.
• Do not use structured logging as a debugging dump during development — use a debugger instead.

When To Use

• Use structured logging in any application that runs in production — log aggregation tools require it.
• Include a correlation ID on every log entry to trace a single request across multiple services.

Code Examples

// Unstructured — impossible to query reliably
error_log("User $userId logged in from {$_SERVER['REMOTE_ADDR']} in {$elapsed}ms");

use Monolog\Logger;
use Monolog\Handler\StreamHandler;
use Monolog\Formatter\JsonFormatter;

$log = new Logger('app');
$handler = new StreamHandler('php://stdout');
$handler->setFormatter(new JsonFormatter());
$log->pushHandler($handler);

// Structured context — every field is queryable
$log->info('User login', [
    'user_id'    => $userId,
    'ip'         => $request->ip(),
    'request_id' => $requestId,
    'duration_ms'=> $elapsed,
]);

References

• ↗ https://github.com/Seldaek/monolog

Tags

Related Terms