Logging

Module for declarative logging of method arguments and result using annotations.

Dependency

Most likely already transitively connected from other dependencies or from Logback, otherwise it needs to be added:

Java Kotlin

Dependency build.gradle:

implementation "ru.tinkoff.kora:logging-common"

Module:

@KoraApp
public interface Application extends LoggingModule { }

Dependency build.gradle.kts:

implementation("ru.tinkoff.kora:logging-common")

Module:

@KoraApp
interface Application : LoggingModule

Logging

It is expected to use special combinations of annotations to customize method logging.

Argument

@Log.in
public String methodWithReturnAndOnlyLogArgs(@Log.off String strParam,int numParam) {
    return"testResult";
}

Logging Level	Logging
TRACE, DEBUG	DEBUG [] r.t.e.e.Example.methodWithArgs: > {data: {numParam: "4"}}
INFO	INFO [] r.t.e.e.Example.methodWithArgs: >

Result

@Log.out
public String methodWithOnlyLogReturnAndArgs(String strParam, int numParam) {
    return "testResult"
}

Logging level	Logging
TRACE, DEBUG	DEBUG [] r.t.e.e.Example.methodWithArgs: < {data: {out: "testResult"}}
INFO	INFO [] r.t.e.e.Example.methodWithArgs: <

Argument and result

@Log
public String methodWithArgs(String strParam, int numParam) {
    return "testResult";
}

Logging Level	Logging
TRACE, DEBUG	DEBUG [] r.t.e.e.Example.methodWithArgs: > {data: {strParam: "s", numParam: "4"}} DEBUG [] r.t.e.e.Example.methodWithArgs: < {data: {out: "testResult"}}
INFO	INFO [] r.t.e.e.Example.methodWithArgs: > INFO [] r.t.e.e.Example.methodWithArgs: <

Selective logging

@Log.out
@Log.off
public String methodWithOnlyLogReturnAndArgs(String strParam,int numParam) {
    return"testResult";
}

Logging Level	Logging
TRACE, DEBUG	INFO [] r.t.e.e.Example.methodWithArgs: <
INFO	INFO [] r.t.e.e.Example.methodWithArgs: <

MDC (Mapped Diagnostic Context)

The @Mdc annotation allows adding key-value pairs to MDC (Mapped Diagnostic Context) for structured logging. MDC allows adding contextual information to each log message.

The annotation can be applied to methods and method parameters. Multiple application is supported.

Parameters of the @Mdc annotation:

• key() - Key for the MDC entry. If not specified, the name of the annotated parameter is used.
• value() - Value for the MDC entry. If not specified, the value of the annotated parameter is used.
• global() - If true, the MDC value will be available globally within the thread, not just during method execution.

Parameter annotation

Java Kotlin

public String test(@Mdc String s) {
    return "1";
}

fun test(@Mdc s: String): String {
    return "1"
}

In this case, the MDC key will match the parameter name ("s"), and the value will be the parameter value.

Parameter annotation with key

Java Kotlin

public String test(@Mdc(key = "123") String s) {
    return "1";
}

fun test(@Mdc(key = "123") s: String): String {
    return "1"
}

Here, the MDC key will be "123", and the value will be the value of parameter "s".

Method use

Java Kotlin

@Mdc(key = "key1", value = "value2")
public String test(String s) {
    return "1";
}

@Mdc(key = "key1", value = "value2")
fun test(s: String): String {
    return "1"
}

This example demonstrates: - Method annotation with local MDC value

Combined

Java Kotlin

@Mdc(key = "key", value = "value", global = true)
@Mdc(key = "key1", value = "value2")
public Integer test(@Mdc(key = "123") String s) {
    return "1";
}

@Mdc(key = "key", value = "value", global = true)
@Mdc(key = "key1", value = "value2")
fun test(@Mdc(key = "123") s: String): String {
    return "1"
}

In this example, two MDC annotations are applied to the method, and one annotation is applied to the parameter.

Generated value for MDC value

Java Kotlin

@Mdc(key = "key", value = "${java.util.UUID.randomUUID().toString()}")
public Integer test(String s) {
    return "1";
}

@Mdc(key = "key", value = "\${java.util.UUID.randomUUID().toString()}")
fun test(s: String): String {
    return "1"
}

When calling the method, an MDC entry will be added with the key "key" and a value as generated random UUID.

Example log with MDC:

INFO [main] r.t.e.e.Example.test: > {data: {s: "testValue"}} key=some-uuid-value key1=value2 123=testValue

Signatures

Available signatures for repository methods out of the box:

Java Kotlin

Class must be non final in order for aspects to work.

The T refers to the type of the return value, either Void.

• T myMethod()
• Optional<T> myMethod()
• CompletionStage<T> myMethod() CompletionStage
• Mono<T> myMethod() Project Reactor (require dependency)
• Flux<T> myMethod() Project Reactor (require dependency)

Class must be open in order for aspects to work.

By T we mean the type of the return value, either T?, either Unit.

• myMethod(): T
• suspend myMethod(): T Kotlin Coroutine (require dependency as implementation)
• myMethod(): Flow<T> Kotlin Coroutine (require dependency as implementation)