structured-logs-rfc-34

name	structured-logs-rfc-34
description	RFC-34 compliant structured logging standards for Java services. Covers JSON log format, structured arguments, required fields, and Logback configuration. Use when implementing or reviewing logging in Java services.
compatibility	Java projects using Spring Boot with Logback
metadata	{"version":"1.0.0","technology":"java","category":"observability","tags":["java","logging","rfc-34","structured-logs","observability"]}

Structured Logs (RFC-34)

RFC-34 compliant structured logging standards for Java services.

When to use this skill

• Implementing logging in new Java services
• Converting unstructured logs to structured format
• Reviewing logging practices
• Configuring Logback for JSON output
• Adding business context to logs

Skill Contents

Sections

• When to use this skill
• Quick Start
• Required Fields
• Best Practices
• References
• Related Rules
• Related Skills

Available Resources

📚 references/ - Detailed documentation

• logging standards

---

Quick Start

1. Add Dependencies

implementation 'org.springframework.boot:spring-boot-starter-logging'
implementation 'net.logstash.logback:logstash-logback-encoder:${latest_version}'

2. Use Structured Arguments

import static net.logstash.logback.argument.StructuredArguments.kv;

log.info("Transaction processed",
         kv("transaction_id", txn.getId()),
         kv("user_id", user.getId()));

This produces JSON with separate fields for transaction_id and user_id.

Required Fields

All logs must include these fields:

Field	Description
@timestamp	Log timestamp
message	Log message text
logger	Logger name
thread_name	Thread name
level	Log level (INFO, WARN, ERROR, etc.)
dd.service	Service name
dd.env	Environment
dd.version	Service version

Best Practices

• Add business identifiers (IDs) as separate fields instead of embedding in messages
• Keep log message text clear and concise
• Use appropriate log levels consistently
• Include enough context to understand the event without additional queries
• Use snake_case for field names
• For logs containing objects, properly structure them rather than using toString()

Example

// ✅ Good - structured fields
log.info("Order created", kv("order_id", orderId), kv("user_id", userId), kv("amount", amount));

// ❌ Bad - embedded in message
log.info("Order {} created for user {} with amount {}", orderId, userId, amount);

References

Reference	Description
references/logging-standards.md	Complete RFC-34 implementation guide

Related Rules

• java-structured-logs - Full logging standards

Related Skills

Skill	Purpose
java-standards	General Java standards
java-testing	Testing log output