1. Introduction

This library provides an appender for logback, allowing you to send logs to the LogDNA online logging platform, via their HTTPS Ingest API. MDC thread-bound data can be send, indexed and searched into your LogDNA dashboard.

This library relies on a JAX-RS v2.1 implementation (of your choice) with a Jackson JSON mapper. For a lightweight implementation, you can check this other appender.

2. How to use it

First, copy this dependency into your pom.xml file.

<dependency>
    <groupId>net.zileo</groupId>
    <artifactId>logback-logdna</artifactId>
    <version>2.0.1</version>
</dependency>

Version 1.3.0 or greater requires Java 11 or greater.

If you don’t already have one in your project, add a JAX-RS implementation into your pom.xml, like Jersey (the one used in the unit tests), RESTEasy or Apache CXF.

Then, copy the following two LogDna appenders to your classpath:/logback.xml file. Check the next chapter for a description of each configuration option.

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

    <appender name="LogDnaHttp" class="net.zileo.logback.logdna.LogDnaAppender">
        <encoder>
            <pattern>[%thread] %msg%n</pattern>
        </encoder>
        <appName>LogDnaTest</appName>
        <ingestUrl>${LOGDNA_INGEST_URL}</ingestUrl>
        <ingestKey>${LOGDNA_INGEST_KEY}</ingestKey>
        <mdcFields>requestId,requestTime</mdcFields>
        <mdcTypes>string,int</mdcTypes>
        <tags>dev</tags>
        <connectTimeout>5000</connectTimeout>
        <readTimeout>10000</readTimeout>
        <useTimeDrift>false</useTimeDrift>
        <hostname>my-host</hostname>
    </appender>

    <appender name="LogDna" class="ch.qos.logback.classic.AsyncAppender">
        <appender-ref ref="LogDnaHttp" />
        <queueSize>500</queueSize>
        <discardingThreshold>0</discardingThreshold>
        <includeCallerData>false</includeCallerData>
    </appender>

    <root level="INFO">
        <appender-ref ref="LogDna" />
    </root>

</configuration>
Tip
 This configuration is based on an asynchronous wrapper, for performance reason. Check this nice OverOps blog article for more information.

Finally, you have to provide a LOGDNA_INGEST_KEY (API key you’ll create in your LogDNA console) and the LOGDNA_INGEST_URL (should be https://logs.logdna.com/logs/ingest) via your System properties or environment variables. If you don’t provide an API key, the appender will be automatically disabled (with a warning).

3. Configuration options

  • You can use your own logging pattern.

  • Set up comma-separated tags if you want to.

  • Set up comma-separated MDC keys to index (from the MDC thread local binding).

  • Set up one type for each MDC key. Possible types are string, boolean, int and long. The last two result in an indexed number in your LogDNA console, which is rather interesting, as it will allow you some functions inside your graphs (sum, average, etc…​).

  • If you use time drift (<useTimeDrift>true</useTimeDrift>), the appender will send a now parameter being the source UNIX timestamp. In this case, the time stamp shown on your LogDNA dashboard will not be the same as the time stamp you sent because of time drift treatment. If you want to see the same time stamp as you post by your appender, specify false (<useTimeDrift>false</useTimeDrift>). Default value is true. For more information, consult the API reference.

  • You can try to set up a specific connectTimeout and readTimeout for the underlying JAX-RS client.

  • Although there is an automated lookup for it, you can force a specific value for the hostname that will be given to LogDNA. It will appear in the Source metadata field.

4. JSON parameters parsing

A nice feature of LogDNA is the ability to parse a JSON object at the end of your log message. For example, if you log the following message : My message { id: 1, value: 'text' }, then LogDNA will index both and id and a value searchable parameters. Check LogDNA’s documentation for more information.

Back to GitHub repository