home / skills / bitsoex / bitso-java / logback-config-rfc-27

logback-config-rfc-27 skill

safe

This skill helps you configure RFC-27 compliant logback settings for Java services, enabling environment-specific, rotation-ready logging with console and JSON

npx playbooks add skill bitsoex/bitso-java --skill logback-config-rfc-27

Review the files below or copy the command above to add this skill to your agents.

Files (2)

SKILL.md

5.1 KB

---
name: logback-config-rfc-27
description: >
  RFC-27 compliant static Logback configuration for Java services. Covers logback.xml
  structure, appenders, encoders, and deployment-specific configuration.
  Use when setting up or reviewing logging configuration in Java services.
compatibility: Java projects using Spring Boot with Logback
metadata:
  version: "1.0.0"
  technology: java
  category: observability
  tags:
    - java
    - logging
    - rfc-27
    - logback
    - configuration
---

# Logback Configuration (RFC-27)

RFC-27 compliant static Logback configuration for Java services.

## When to use this skill

- Setting up logging configuration for new Java services
- Reviewing or updating logback.xml configuration
- Configuring environment-specific logging
- Setting up log file rotation and retention
- Configuring appenders for different outputs (console, file, JSON)

## Skill Contents

### Sections

- [When to use this skill](#when-to-use-this-skill) (L24-L31)
- [Quick Start](#quick-start) (L52-L90)
- [Configuration Structure](#configuration-structure) (L91-L115)
- [Appender Types](#appender-types) (L116-L134)
- [Environment Configuration](#environment-configuration) (L135-L154)
- [References](#references) (L155-L160)
- [Related Rules](#related-rules) (L161-L164)
- [Related Skills](#related-skills) (L165-L170)

### Available Resources

**📚 references/** - Detailed documentation
- [configuration patterns](references/configuration-patterns.md)

---

## Quick Start

### 1. Create logback-spring.xml

Place in `src/main/resources/logback-spring.xml`:

```xml
<?xml version="1.0" encoding="UTF-8"?>
<configuration scan="true" scanPeriod="30 seconds">
    <include resource="org/springframework/boot/logging/logback/defaults.xml"/>

    <!-- Console appender for local development -->
    <springProfile name="local">
        <appender name="CONSOLE" class="ch.qos.logback.core.ConsoleAppender">
            <encoder>
                <pattern>%d{HH:mm:ss.SSS} [%thread] %-5level %logger{36} - %msg%n</pattern>
            </encoder>
        </appender>
        <root level="INFO">
            <appender-ref ref="CONSOLE"/>
        </root>
    </springProfile>

    <!-- JSON appender for production -->
    <springProfile name="!local">
        <appender name="JSON" class="ch.qos.logback.core.ConsoleAppender">
            <encoder class="net.logstash.logback.encoder.LogstashEncoder"/>
        </appender>
        <root level="INFO">
            <appender-ref ref="JSON"/>
        </root>
    </springProfile>
</configuration>
```

### 2. Do NOT Commit logback.xml to Git

Per RFC-27, `logback.xml` should NOT be in version control. Use `logback-spring.xml` instead, which supports Spring profiles.

## Configuration Structure

### Required Elements

| Element | Purpose |
|---------|---------|
| `<configuration>` | Root element with optional scan attributes |
| `<appender>` | Defines output destination |
| `<encoder>` | Formats log messages |
| `<root>` | Default logging level |

### Spring Profile Integration

Use `<springProfile>` to apply configuration conditionally:

```xml
<springProfile name="production">
    <!-- Production-specific config -->
</springProfile>

<springProfile name="!production">
    <!-- Non-production config -->
</springProfile>
```

## Appender Types

| Appender | Use Case |
|----------|----------|
| `ConsoleAppender` | Standard output (container logs) |
| `RollingFileAppender` | File with rotation |
| `AsyncAppender` | Non-blocking wrapper |

### Console Appender (Production)

```xml
<appender name="JSON" class="ch.qos.logback.core.ConsoleAppender">
    <encoder class="net.logstash.logback.encoder.LogstashEncoder">
        <includeMdcKeyName>traceId</includeMdcKeyName>
        <includeMdcKeyName>spanId</includeMdcKeyName>
    </encoder>
</appender>
```

## Environment Configuration

### Log Levels per Environment

| Environment | Root Level | Notes |
|-------------|------------|-------|
| `local` | DEBUG | Verbose for development |
| `development` | INFO | Standard logging |
| `staging` | INFO | Match production |
| `production` | INFO | Minimize noise |

### Logger Overrides

```xml
<!-- Reduce noise from specific libraries -->
<logger name="org.apache.kafka" level="WARN"/>
<logger name="org.springframework.web" level="INFO"/>
<logger name="com.bitso" level="DEBUG"/>
```

## References

| Reference | Description |
|-----------|-------------|
| [references/configuration-patterns.md](references/configuration-patterns.md) | Detailed configuration examples |

## Related Rules

- [java-structured-logs](.cursor/rules/java-structured-logs/java-structured-logs.mdc) - Structured logging standards (RFC-34)

## Related Skills

| Skill | Purpose |
|-------|---------|
| [structured-logs-rfc-34](.claude/skills/structured-logs-rfc-34/SKILL.md) | Structured logging format |
| [dynamic-loglevel-rfc-27](.claude/skills/dynamic-loglevel-rfc-27/SKILL.md) | Runtime log level control |
<!-- AUTO-GENERATED FILE - DO NOT EDIT DIRECTLY -->
<!-- Source: bitsoex/ai-code-instructions → java/skills/logback-config-rfc-27/SKILL.md -->
<!-- To modify, edit the source file and run the distribution workflow -->

Overview

This skill provides an RFC-27 compliant static Logback configuration for Java services, focused on clear structure, environment-specific profiles, and production-friendly output. It explains where to place logback-spring.xml, which appenders and encoders to use, and deployment practices like not committing logback.xml to version control. Use it to set up or review consistent logging across services.

How this skill works

The configuration uses a root <configuration> element with springProfile blocks to apply different appenders and log levels per environment. It includes Console and RollingFile appenders, JSON encoding for production via LogstashEncoder, and encoder patterns for development. Logger overrides and async appenders are used to control noise and minimize runtime impact.

When to use it

Setting up logging for a new Java service using Spring Boot
Reviewing or auditing existing logback.xml/logback-spring.xml files
Configuring environment-specific logging (local, dev, staging, production)
Setting up log rotation, retention, and non-blocking appenders
Preparing logs for structured downstream processing (JSON/Logstash)

Best practices

Place logback-spring.xml in src/main/resources and avoid committing environment-specific logback.xml files
Use <springProfile> to separate local (human-friendly) and production (JSON) formats
Prefer ConsoleAppender for containers and RollingFileAppender for node-level persistence
Use LogstashEncoder for structured JSON with MDC keys (traceId, spanId) in production
Wrap appenders with AsyncAppender for high-throughput services to avoid blocking I/O

Example use cases

Local development: ConsoleAppender with human-readable pattern and DEBUG root level
Production: ConsoleAppender emitting JSON via LogstashEncoder and INFO root level
Staging: Match production logging format but allow temporary increased verbosity for troubleshooting
Microservice with heavy library noise: Add specific logger overrides (e.g., org.apache.kafka -> WARN)
Services requiring traceability: include MDC keys like traceId and spanId in JSON encoder

FAQ

Why use logback-spring.xml instead of logback.xml?

logback-spring.xml supports Spring profiles and should be used to avoid committing environment-specific defaults into version control.

How do I include trace IDs in logs?

Add MDC keys to the encoder (e.g., includeMdcKeyName traceId and spanId) when using LogstashEncoder to ensure traceability in JSON logs.

When should I use AsyncAppender?

Use AsyncAppender for any high-throughput or latency-sensitive service to prevent blocking on I/O when writing logs.