Getting Started

What is Penna?

Penna is a fast and lightweight slf4j implementation that writes structured JSON log messages to stdout. You can read more here.

When should I use Penna?

Penna is specially useful for when you run you applications on docker containers or kubernetes pods and your log is captured from stdout to a log aggregator like loki or the elastic stack.

Adding Penna to your project

Add the latest version of penna-core to your dependency manager.

// gradle
runtimeOnly 'com.hkupty.penna:penna-core:0.8.0'

<!-- maven -->
<dependency>
    <groupId>com.hkupty.penna</groupId>
    <artifactId>penna-core</artifactId>
    <version>0.8.0</version>
</dependency>

Enjoy! Penna comes with sane defaults so no initial configuration is needed

What if I want to change the configuration?

Then you need to add penna-yaml-config to your project, alongside jackson-dataformat-yaml:

// gradle
runtimeOnly 'com.hkupty.penna:penna-yaml-config:0.8.0'

// penna-yaml-config is a thin layer and uses a yaml parsing libray under the hood.
// You can chose among jackson, snakeyaml (yaml 1.1) or snakeyaml engine (yaml 1.2)

// Jackson
runtimeOnly 'com.fasterxml.jackson.core:jackson-core:2.17.0'
runtimeOnly 'com.fasterxml.jackson.core:jackson-databind:2.17.0'
runtimeOnly 'com.fasterxml.jackson.dataformat:jackson-dataformat-yaml:2.17.0'

// Snakeyaml
runtimeOnly 'org.yaml:snakeyaml:2.2'

// Snakeyaml engine
runtimeOnly 'org.snakeyaml:snakeyaml-engine:2.7'

<!-- maven -->
<dependency>
    <groupId>com.hkupty.penna</groupId>
    <artifactId>penna-yaml-config</artifactId>
    <version>0.8.0</version>
</dependency>
<dependency>
    <groupId>com.fasterxml.jackson.core</groupId>
    <artifactId>jackson-core</artifactId>
    <version>$jacksonVersion</version>
</dependency>
<dependency>
    <groupId>com.fasterxml.jackson.core</groupId>
    <artifactId>jackson-databind</artifactId>
    <version>$jacksonVersion</version>
</dependency>
<dependency>
    <groupId>com.fasterxml.jackson.dataformat</groupId>
    <artifactId>jackson-dataformat-yaml</artifactId>
    <version>$jacksonVersion</version>
</dependency>

<dependency>
    <groupId>org.yaml</groupId>
    <artifactId>snakeyaml</artifactId>
    <version>2.2</version>
</dependency>

<dependency>
    <groupId>org.snakeyaml</groupId>
    <artifactId>snakeyaml-engine</artifactId>
    <version>2.7</version>
</dependency>

And then you can configure a resources/penna.yaml file like this:

# resources/penna.yaml
---
# Since version 0.8, penna-yaml-config supports setting up a file watcher
# so any updates to this file will be reflected immediately
watch: true
loggers:
    # All the loggers under `com.yourapp` will be configured to debug level.
    com.yourapp: { level: debug }
    # this special namespace (and everything below it) will get trace level instead
    com.yourapp.specialNamespace: { level: trace }
    org.noisylibrary: { level: warn }

Can I change more parameters in the configuration?

As mentioned before, penna comes with a set of good defaults so you don’t have to worry about them, but if you really want to tweak some parameters, you can.

loggers:
    com.mycompany.myapp:
        level: debug
        fields:
            # These are the default fields. You can remove some fields if you want to
            - level
            - logger
            - thread
            - data
            - mdc
            - markers
            - message
            - throwable
        exceptions:
            # Whether penna will try to avoid printing duplicated log messages.
            # By default, this feature is on, which means once it prints a log message it
            # has seen before, it will short-circuit out of printing that stack trace
            deduplicate: true
            # The maximum number of frames in the stack it will print
            maxDepth: 64
            # If the exceptions contains parents, what is the maximum depth
            # Penna will traverse.
            traverseDepth: 2