salesforce / timbermill

A better logging service

Timbermill

A Task-Based, Context-Aware Logging service

Timbermill is an advanced, open-source logging service built for Elasticsearch.
Timbermill collects all events sent to it, processes them, and sends them to your elasticsearch cluster in a task-based, context-aware manner which gives an easy way to search, analyze and monitor your system. (mainly by using Kibana)

Task-based, Context-Aware, cool. What's that?

Task-based:

Timbermill logs are not just lines of text, they are Tasks.

Task characteristics:

• Represented by a specific name.
• Has a unique ID.
• Represents multiple Events that were called for it.
  • Start event that open the Task.
  • Zero or more info events (Strings/Texts/Context/Metrics) that add properties values to the task.
  • Closing event that closes the Task either successfully or with an error (Success/Error), note that as long as an event is in the works its status is Unterminated
• Has a start-time, end-time and duration.

Context-Aware:

System events doesn't occur in a void.

Events always have context. When did this event happen? Why did it happen? What was the path of events leading to this event? What were the values we encountered along the path? It's rarely enough just to know that something happened and simple logging just doesn't let us know a lot more than that.

Timbermill does.

Every task in Timbermill points to a parent task and automatically keeps important information from it:

• Complete path of tasks leading to this task.
• Important properties from its ancestors.
• More!

Getting Started

Requirements

• Elasticsearch cluster
• Java project (1.8+)
• Add dependency to maven

How to use Timbermill

Timbermill is designed to be plug-and-play out-of-the-box.

    public void main() {
        TimberLogger.bootstrap();
        
        log();
        
    }

    @TimberLog(name = "hello_world")
    public void log() {
        LogParams params = LogParams.create().string("foo", "bar").text("text", "This is a text!").metric("number", 42);
        TimberLogger.logParams(params);
        /**
         *  Your Code
         */
    }

This code bootstraps Timbermill with a local default Elasticsearch cluster (http://localhost:9200). It will write one task of name hello_world with the above properties to elasticsearch.

• A custom Elasticsearch URL (along with other configurations) can be defined using LocalOutputPipeConfig.

LocalOutputPipeConfig.Builder builder = new LocalOutputPipeConfig.Builder().url("https://elasticsearch:9200");
LocalOutputPipeConfig config = builder.build();
TimberLog.bootstrap(config);

What can I do next?

Get familiar with our wiki so you get a better sense on how to properly use Timbermill.

timbermill's Issues

Write a wiki

Complete Timbermill's wiki

Timbermill - elasticsearch mapping template

• create mapping template for timbermill indices
• PUT the template every time timbermill startsup

Change Timbermill indices to Rollover indices

Rollover index instead of one per day
https://www.elastic.co/guide/en/elasticsearch/reference/current/indices-rollover-index.html

Generic TimberLog annotations

Create a REST Timbermill server

Reporting a vulnerability

Hello!

I hope you are doing well!

We are a security research team. Our tool automatically detected a vulnerability in this repository. We want to disclose it responsibly. GitHub has a feature called Private vulnerability reporting, which enables security research to privately disclose a vulnerability. Unfortunately, it is not enabled for this repository.

Can you enable it, so that we can report it?

Thanks in advance!

PS: you can read about how to enable private vulnerability reporting here: https://docs.github.com/en/code-security/security-advisories/repository-security-advisories/configuring-private-vulnerability-reporting-for-a-repository