En esta guía (6 elementos)

Observability — Structured Logging

Project-agnostic. Part of the Observability suite. Covers: SLF4J + Logback configuration, OTEL trace-id correlation in logs, JSON structured logging for production, logging rules and PII guards.

Replace com.example.platform / platform-service placeholders with your project’s actual package and service name when applying patterns.

Security tie-in: never log secrets, tokens, PII, or full request bodies. See security.md §10.

Companion files:

observability.md — index + three-pillars overview.
obs-metrics.md — Micrometer + Prometheus + decorator metrics.
obs-tracing.md — OTEL tracing.
obs-recipes.md — step-by-step + dashboards + alerting + checklist.

8. Structured Logging

SLF4J + Logback Configuration with OTEL Trace Correlation

The project uses SLF4J with Logback. Trace correlation is automatic via Micrometer Tracing’s MDC integration.

Current Log Pattern (application.yml)

1
logging:
2
  pattern:
3
    console: "%d{HH:mm:ss.SSS} [%thread] [trace-id=%X{traceId}] %-5level %logger{5} - %msg%n"
4
    file: "%d{HH:mm:ss.SSS} [%thread] [trace-id=%X{traceId}] %-5level %logger{5} - %msg%n"

JSON Structured Logging (Recommended for Production)

For production environments, use JSON-formatted logs for better parsing by log aggregators (ELK, Loki, NewRelic Logs):

Add the dependency to bootstrap/build.gradle.kts:

1
dependencies {
2
    // Logback JSON encoder for structured logging
3
    implementation("ch.qos.logback.contrib:logback-json-classic:0.1.5")
4
    implementation("ch.qos.logback.contrib:logback-jackson:0.1.5")
5
    // OR use Logstash encoder (more common):
6
    implementation("net.logstash.logback:logstash-logback-encoder:8.0")
7
}

Create bootstrap/src/main/resources/logback-spring.xml:

1
<?xml version="1.0" encoding="UTF-8"?>
2
<configuration>
3

4
    <springProfile name="local,dev">
5
        <appender name="CONSOLE" class="ch.qos.logback.core.ConsoleAppender">
6
            <encoder>
7
                <pattern>%d{HH:mm:ss.SSS} [%thread] [trace-id=%X{traceId}] [span-id=%X{spanId}] %-5level %logger{36} - %msg%n</pattern>
8
            </encoder>
9
        </appender>
10
        <root level="INFO">
11
            <appender-ref ref="CONSOLE"/>
12
        </root>
13
    </springProfile>
14

15
    <springProfile name="staging,production">
16
        <appender name="CONSOLE_JSON" class="ch.qos.logback.core.ConsoleAppender">
17
            <encoder class="net.logstash.logback.encoder.LogstashEncoder">
18
                <includeMdcKeyName>traceId</includeMdcKeyName>
19
                <includeMdcKeyName>spanId</includeMdcKeyName>
20
                <customFields>
21
                    {"service":"platform-service"}
22
                </customFields>
23
            </encoder>
24
        </appender>
25
        <root level="INFO">
26
            <appender-ref ref="CONSOLE_JSON"/>
27
        </root>
28
    </springProfile>
29

30
</configuration>

Logging Examples

Kotlin:

1
import org.slf4j.LoggerFactory
2

3
class CreateUserUseCase(
4
    private val userRepository: UserRepositoryPort,
5
) : CreateUserPort {
6

7
    companion object {
8
        private val log = LoggerFactory.getLogger(CreateUserUseCase::class.java)
9
    }
10

11
    override fun execute(command: CreateUserCommand): User {
12
        log.info("Creating user id={}", command.userId)
13
        val user = userRepository.save(command.toUser())
14
        log.info("User created successfully with id={}", user.id)
15
        return user
16
    }
17
}

Java:

1
import org.slf4j.Logger;
2
import org.slf4j.LoggerFactory;
3

4
public class CreateUserUseCase implements CreateUserPort {
5

6
    private static final Logger log = LoggerFactory.getLogger(CreateUserUseCase.class);
7

8
    private final UserRepositoryPort userRepository;
9

10
    public CreateUserUseCase(UserRepositoryPort userRepository) {
11
        this.userRepository = userRepository;
12
    }
13

14
    @Override
15
    public User execute(CreateUserCommand command) {
16
        log.info("Creating user id={}", command.userId());
17
        User user = userRepository.save(command.toUser());
18
        log.info("User created successfully with id={}", user.getId());
19
        return user;
20
    }
21
}

Logging Rules

Use parameterized messages (log.info("msg {}", value)) — never string concatenation.
Never log sensitive data (passwords, tokens, PII beyond what is strictly necessary).
Include domain context (entity IDs, operation names) for traceability.
Log at the right level:
- ERROR: Unrecoverable failures that need immediate attention.
- WARN: Recoverable issues or degraded behavior.
- INFO: Significant business events (created, updated, deleted).
- DEBUG: Detailed diagnostic information (cache hits, query parameters).
The trace-id is automatically included in every log line via MDC — do not log it manually.