structured-logs-rfc-34_skill

Overview

This skill defines RFC-34 compliant structured logging standards for Java services, focused on JSON log format, structured arguments, required fields, and Logback configuration. It guides implementation and reviews to ensure logs carry consistent service, environment, and business context. Use it to produce searchable, parseable logs that work with observability platforms.

How this skill works

The skill specifies required JSON fields (timestamp, message, logger, thread_name, level, dd.service, dd.env, dd.version) and recommends using net.logstash.logback's StructuredArguments for key/value fields. It shows the Logback encoder dependency and examples that add business identifiers as separate fields rather than embedding them in text. The guidance enforces snake_case field names and structured objects for complex data.

When to use it

• Implement logging in a new Java service to meet RFC-34
• Convert legacy unstructured logs to JSON structured format
• Review or audit logging practices and compliance
• Configure Logback to emit JSON for observability tools
• Add business context to logs for tracing and debugging

Best practices

• Always include required fields: @timestamp, message, logger, thread_name, level, dd.service, dd.env, dd.version
• Prefer StructuredArguments.kv(...) to add business identifiers as separate JSON fields
• Keep the human-readable message concise; move context into structured fields
• Use snake_case for all field names and avoid embedding IDs in message text
• Structure objects in JSON instead of relying on toString() representations
• Choose log levels consistently and include enough context to interpret events

Example use cases

• Log transaction events with transaction_id and user_id as JSON fields for traceability
• Configure Spring Boot Logback with logstash-logback-encoder to send JSON to log aggregator
• Audit service that requires standardized dd.service, dd.env, dd.version fields for deployment tracking
• Refactor legacy code: replace formatted message arguments with structured kv fields
• Create alerts and dashboards using the structured fields (level, dd.service, transaction_id) for filtering