Skip to content
Switch branches/tags
Go to file
Cannot retrieve contributors at this time
422 lines (308 sloc) 14.8 KB

Travis Build Maven central

Aggregation Logger


The logger counts the total number of events logged by the hosting Java application with breakdown by severity level: TRACE, DEBUG, INFO, WARN, ERROR, FATAL.

The counters are flushed asyncronously to the Axibase Time Series Database every 60 seconds for long-term retention and alerting.

The logger consists of the core library and adapters for Logback, Log4j, and Log4j2 logging frameworks.

Sample Portal

Live Examples


Collected Data


Aggregation Logger collects the following metrics:

Metric Tags Type Description
log_event_total_counter level counter Total number of events logged by the application, by level.
log_event_counter level
counter Number of events raised by each logger.
Controlled with the sendLoggerCounter setting.

The metrics are continuously incrementing counters. The first derivative (delta) between two samples represents the number of events per interval.


The logger can also send a small subset of raw events to the database for triage. The index of events sent within a 10-minute period is determined using exponential backoff multipliers. The index is reset at the end of each 10-minute period.

  • INFO. Multiplier 5. Events sent: 1, 5, 25, 125, ..., 5^(n-1)
  • WARN. Multiplier 3. Events sent: 1, 3, 9, 27, ..., 3^(n-1)
  • ERROR. Multiplier 2. Events sent: 1, 2, 4, 8, ..., 2^(n-1)

ERROR-level events that inherit from java.lang.Error are sent to the database instantly, regardless of the event index.


The following java.log_aggregator.* properties are stored by logger:

Type Description
environment Current system environment.
runtime Current system properties.
settings Aggregation logger settings.
operating_system General information about the operating system.


Since counters are flushed to the database every 60 seconds, the incoming samples (or the lack thereof) can be used for heartbeat monitoring as an early warning of network outages, garbage collection freezes, and application crashes.

Heartbeat rule configuration in XML.


  • Java 1.8 and later

Supported Logging Frameworks

Supported Time Series Databases

Configuration Examples


long start = System.currentTimeMillis();
for (int i = 1; i <= 1000000; i++) {
    logger.error("msg " + new Date() + " : index=" + i);
long end = System.currentTimeMillis();

Filter Disabled


DONE in 5589 ms

Filter Enabled


DONE in 6002 ms


Option 1: Maven

Add the Maven dependency to one of supported logging adapters: logback, log4j, or log4j2.

Dependency to the aggregator core is imported automatically:


Option 2: Classpath

Add core and adapter libraries to classpath:

  • Download aggregation-log-filter-1.2.x.jar from Maven Central
  • Download aggregation-log-filter-{adapter}-1.2.x.jar from Maven Central
  • Add .jar files to classpath, replace x with appropriate version:
java -classpath lib/app.jar:lib/aggregation-log-filter-2.x.y.jar:lib/aggregation-log-filter-{adapter}-2.x.y.jar Main

Option 3: lib directory

Copy core and adapter libraries to the application /lib directory.

Apache ActiveMQ example:

wget --content-disposition -P /opt/apache-activemq-5.9.1/lib/ \
wget --content-disposition -P /opt/apache-activemq-5.9.1/lib/ \

Logback XML Configuration Example

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

    <appender name="FILE" class="ch.qos.logback.core.FileAppender">


        <!-- attach log aggregator to 'FILE' appender -->
        <filter class="com.axibase.tsd.collector.logback.Collector">

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

Log4j Properties Example

#attach log aggregator to 'logfile' appender -->

Log4j XML Example

<appender name="APPENDER" class="org.apache.log4j.ConsoleAppender">
    <layout class="org.apache.log4j.PatternLayout">
        <param name="ConversionPattern" value="%d [%t] %-5p %c - %m%n"/>
    <filter class="com.axibase.tsd.collector.log4j.Log4jCollector">
        <param name="url" value="tcp://atsd_hostname:tcp_port"/>

Log4j2 XML Example

        <Console name="APPENDER">
                <Collector url="tcp://atsd_hostname:tcp_port"/>
        <Logger name="com.axibase"/>
        <Root level="INFO">
            <AppenderRef ref="APPENDER"/>

MDC Context Parameters in Messages

MDC context parameters can be included in message command as tags such as job_name, task_id, etc.

message e:spbswgvml008 t:command=AxibaseCollector t:type=logger m:"Fetching error
   No files found: file:///opt/files" t:severity=ERROR t:level=ERROR t:source=com.collector.FileService
   t:job_name=snmp-prd-router t:task_id=2 t:thread=taskExecutor-1

Java Example

#MDC.put("job_name", job.getName());
MDC.put("job_name", "snmp-prd-router");
MDC.put("task_id", "2");





Configuration Settings

Name Required Default Description
url yes - Database address specified with URI syntax: scheme:[//[user:password@]host[:port]].
Supported schemes: TCP, UDP, HTTP, HTTPS.
entity no Server hostname Entity name for series and messages, usually the hostname of the machine where the application is running.
tag no - User-defined tags to be included in series and message commands, MULTIPLE.
level no TRACE Minimum level for counting events.
intervalSeconds no 60 Interval in seconds for sending collected counters.
sendMessage no - See the sendMessage config, MULTIPLE.
pattern no %m Pattern to format logging events sent to the database.
The pattern cannot include fields that are already included as tags such as logger name, level, etc.
sendLoggerCounter no true When disabled, event counts by logger are not tracked and the log_event_counter metric is not sent.
mdcTags no - User-defined tags to be included in message commands, value extracted from MDC context, MULTIPLE.
debug no false Enable logging debug information to stdout, see Troubleshooting.
messageLength no -1 Maximum event message size. No truncation is performed if the length is negative or zero.
ignoreSslErrors no true Ignore SSL errors if the SSL certificate presented by ATSD is self-signed, expired, or otherwise invalid.

Database Address

Configures a TCP, UDP, HTTP, or HTTPS writer to send statistics and messages to Axibase Time Series Database.


Name Required Default Description
host yes - database hostname or IP address, string
port no 8081 database TCP port, integer


Name Required Default Description
host yes - database hostname or IP address, string
port no 8082 database UDP port, integer


Name Required Default Description
username yes - username, string
password yes - password, string
host yes - database hostname or IP address, string
port no 80/443 database HTTP/HTTPS port, integer
Note that ATSD is listening on ports 8088/HTTP and 8443/HTTPS by default.



Same settings as HTTP scheme.


Configures which log events are sent to the database.

Name Required Default Value Description
level no WARN Trace level to which this configuration applies. Note, that lower level settings do not apply to upper levels. Each level is configured separately.
stackTraceLines no 0; ERROR: -1 Number of stacktrace lines included in the message, -1 -- all lines.
sendMultiplier no INFO: 5
Determines index of events sent each period (10 minutes). Determined as sendMultiplier^(n-1).

Location Fields

If the appender pattern contains location fields, such as %L (line) and %M (method), these fields are added to messages as tags.

<layout class="org.apache.log4j.PatternLayout">
   <param name="ConversionPattern" value="%d [%t] %-5p %c - %m%n %L"/>

Message command example with location fields:

message e:nurswgvml007 t:command=com.axibase.tsd.Server t:type=logger m:"Initialization complete"
    t:severity=INFO t:level=INFO t:source=com.axibase.tsd.InitLogger t:thread=main
    t:line=145 t:method=initBase


Add the debug = true parameter to display logger errors and commands.

Logback: add under <filter>.


Log4j: add the JVM setting -Dlog4j.debug and add the DEBUG setting to the file.


Log4j2: add debug under <Collector> and set status="DEBUG" under Configuration:

<Configuration status="DEBUG">
        <Console name="APPENDER">
            <PatternLayout pattern="%d [%t] %-5p %c - %m%n"/>
                <Collector url="tcp://atsd_hostname:tcp_port" debug="true" />
        <Logger name="com.axibase"/>
        <Root level="INFO">
            <AppenderRef ref="APPENDER"/>