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 (L24-L31)
Quick Start (L51-L71)
Required Fields (L72-L86)
Best Practices (L87-L105)
References (L106-L111)
Related Rules (L112-L115)
Related Skills (L116-L121)

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 |