Kora Telemetry Logging

Kora Telemetry Logging

Kora sub-skill — obey the kora-v2 meta rules on every task: R0 ground the workspace on Kora 2.0 refs before starting (framework source at tag 2.0.0.RC1 + kora-examples at migration/2.0; kora-docs is 1.x only) · R1 read this sub-skill before writing code · R2 Kora 2.0 APIs only — no Spring/Micronaut/Quarkus, no Kora 1.x APIs, no invented annotations or config keys · R3 journal any incorrect Kora usage. Add comments/Javadoc only if asked.

@Log and @Mdc are not in this skill — they are the declarative aspects, covered by kora-aop-logging. This skill owns the logging backend: module wiring, logback.xml, log levels, structured records, MDC values, and component telemetry logging.

The one thing that trips everyone: there are two independent switches

A Kora component writes a telemetry log record only when both are satisfied. They are unrelated keys with different defaults, and each fails silently on its own.

jdbc {
  poolName = "kora"
  telemetry.logging.enabled = true                     # switch 1 — without it: nothing, ever
}

logging.levels {
  "io.koraframework.database.kora.query" = "DEBUG"     # switch 2 — DB query records are DEBUG-only
}

The database logger name is built as "io.koraframework.database." + poolName + ".query", so the kora segment above is this pool's poolName, not a fixed string.

jdbc.telemetry.logging.enabled = true alone produces no output: DefaultDatabaseLogger returns early unless the logger is at DEBUG. Raising the level alone produces no output either, because the component holds a NOPLogger. Say which switch you mean whenever you answer a "my logs are missing" question — see component-telemetry-reference.md for the full logger-name table and each component's config path.

telemetry.tracing.enabled defaults to true, telemetry.metrics.enabled to false — do not generalise from one to the others.

Renamed / changed from Kora 1.x

logging.levels kept its name and shape across the rename — LoggingConfig in 2.0 still exposes Map<String,String> levels(), and LoggingModule still reads the logging section. The key is levels, plural — never logging.level. A singular key is not a recognised HOCON/YAML key, is ignored without a warning, and leaves every logger at its default level.

Quick start

1. Dependencies

Kora 2.0 is on Maven Central. Put koraVersion=2.0.0.RC1 in gradle.properties.

repositories { mavenCentral() }

configurations {
    koraBom
    annotationProcessor.extendsFrom(koraBom)
    implementation.extendsFrom(koraBom)
}

dependencies {
    koraBom platform("io.koraframework:kora-bom:$koraVersion")

    annotationProcessor "io.koraframework:annotation-processors"   // Kotlin: ksp "io.koraframework:symbol-processors"

    implementation "io.koraframework:logging-logback"   // Logback backend; pulls logging-common
    implementation "io.koraframework:config-hocon"      // MANDATORY — LoggingModule reads the `logging` config section
}

logging-logback declares api project(':logging:logging-common'), and logging-common declares api project(':json:json-common') and api project(':core:common'). So JsonWriter, the structured-argument API and the OpenTelemetry API that KoraAsyncAppender needs all arrive transitively — no extra dependency. Never pin a version on an individual io.koraframework:* artifact; the BOM does it.

2. Application graph

LogbackModule extends LoggingModule, and LoggingModule.loggingConfig(Config, ConfigValueMapper<LoggingConfig>) reads config.get("logging") — so a config module (HoconConfigModule or YamlConfigModule) must be in the graph too, or the graph will not build.

import io.koraframework.application.graph.KoraApplication;
import io.koraframework.common.annotation.KoraApp;
import io.koraframework.config.hocon.HoconConfigModule;
import io.koraframework.logging.logback.LogbackModule;

@KoraApp
public interface Application extends LogbackModule, HoconConfigModule {
    static void main(String[] args) {
        KoraApplication.run(ApplicationGraph::graph);
    }
}

LogbackModule contributes one thing of its own: a LoggingLevelApplier that drives the Logback LoggerContext. LoggingModule contributes LoggingConfig, an ILoggerFactory, the three built-in MaskingStrategy components, the structured-argument mappers, and a @Root LoggingLevelRefresher that applies logging.levels during graph initialization.

3. logback.xml

This is the shape every migrated example app uses: Kora's own text encoder inside a ConsoleAppender, wrapped by KoraAsyncAppender.

<configuration debug="false">
    <statusListener class="ch.qos.logback.core.status.NopStatusListener"/>

    <appender name="STDOUT" class="ch.qos.logback.core.ConsoleAppender">
        <encoder class="io.koraframework.logging.logback.ConsoleTextRecordEncoder"/>
    </appender>

    <appender name="ASYNC" class="io.koraframework.logging.logback.KoraAsyncAppender">
        <appender-ref ref="STDOUT"/>
    </appender>

    <root level="INFO">
        <appender-ref ref="ASYNC"/>
    </root>
    <!-- Logger levels are configured in application.conf -->
</configuration>

ConsoleTextRecordEncoder is what renders traceId/spanId, Kora MDC entries and structured arguments; a plain <pattern> encoder drops all of them. Use ConsoleTextRecordEncoder in src/main/resources/logback.xml and keep the pattern encoder for logback-test.xml, exactly as the examples do.

4. Levels come from the config, not from logback.xml

LoggingLevelRefresher.init() runs during graph initialization and calls LoggingLevelApplier.reset() first: the Logback root logger is forced to INFO and every other logger's level is set to null (inherit). Only then are the logging.levels entries applied. Any <logger name="…" level="…"/> element and the <root level="…"> value in logback.xml are therefore discarded the moment the graph starts.

logging.levels {
  "ROOT" = "WARN"
  "io.koraframework" = "INFO"
  "com.example" = "DEBUG"
}

logging:
  levels:
    ROOT: "WARN"
    io.koraframework: "INFO"
    com.example: "DEBUG"

5. Log

import org.slf4j.Logger;
import org.slf4j.LoggerFactory;

private static final Logger log = LoggerFactory.getLogger(UserService.class);

log.info("Created user with id={}", generatedId);   // parameterized, never concatenated

What's in references/ and assets/

Core patterns

Structured arguments

io.koraframework.logging.common.arg.StructuredArgument attaches machine-readable JSON to a record, as a parameter, a marker (metadata only), or a bare value for SLF4J key/value pairs. In all three forms the JSON is appended on its own indented line as name={…}; the parameter form additionally consumes a {} slot, where SLF4J prints the argument's toString() (a bare record dump, not the JSON) — so keep the message a constant and prefer the marker or addKeyValue form. Typed overloads exist for String, Integer, Long, Boolean and Map<String,String>; anything else takes a writer lambda over the Jackson 3 tools.jackson.core.JsonGenerator.

import io.koraframework.logging.common.arg.StructuredArgument;

log.info("Request {} processed", StructuredArgument.arg("requestId", requestId));

log.info(StructuredArgument.marker("userId", userId), "User action performed");

log.atInfo()
   .addKeyValue("user", StructuredArgument.value(gen -> {
       gen.writeStartObject();
       gen.writeStringProperty("id", user.id());       // Jackson 3 name — NOT writeStringField
       gen.writeStringProperty("email", user.email());
       gen.writeEndObject();
   }))
   .log("User created");

See structured-logging-reference.md.

Kora MDC

io.koraframework.logging.common.MDC holds structured (JSON-typed) values and is published through public static final ScopedValue<MDC> VALUE. Kora binds a fresh MDC at the entry of every request, message or job — the Undertow request handler, the gRPC transport filter, each Kafka consumer batch/record, each scheduled job, each JMS message. Inside such a scope MDC.put(...) works; outside one — graph init, a shutdown hook, a plain unit test — MDC.get() throws because the ScopedValue is unbound.

import io.koraframework.logging.common.MDC;

MDC.put("orderId", orderId);        // String / Integer / Long / Boolean / StructuredArgumentWriter
MDC.put("attempt", attempt);
log.info("Processing order");       // both keys attached to the record

KoraAsyncAppender snapshots the bound MDC into the queued event, so values survive the hop to the appender thread; Logback's stock AsyncAppender does not. The string-only org.slf4j.MDC also works (Kora speaks SLF4J) and is what a %X{} pattern reads. See mdc-context-reference.md.

Masking

@io.koraframework.logging.common.annotation.Mask on a record/class field, and on the type itself, tells the processor to generate a <Type>MaskingRulesModule supplying a MaskingRules<T> component. MaskedStructuredArgumentMapper then replaces matched values through a MaskingStrategy — MaskingFull (default, ***), MaskingKeepFirst, MaskingKeepLast, or your own @Component. Rules match a bare field name globally (password), a dotted path from the logged root (user.password), or a path with a * wildcard segment (users.*.password).

Common pitfalls

Anti-patterns

• Do not concatenate: log.info("user " + id) — use log.info("user {}", id).
• Do not put per-package levels in logback.xml; they are wiped at graph start.
• Do not log secrets or PII. Use @Mask for structured values and maskHeaders / maskQueries for HTTP telemetry.
• Do not pin versions on io.koraframework:* artifacts — io.koraframework:kora-bom does it.
• Do not carry a Kora 1.x Context-based MDC helper into 2.0; there is nothing to port it onto.