Agent Skills: Structured Logs (RFC-34)

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 |