Usage

@TimberLogTask

The most simple and recommended API to create Timbermill tasks is the @TimberLogTask annotation.

Following is an example of a simple application with each of its operations being logged to Timbermill:

@TimberLogTask(name = "rest_request")
public void restRequest(Request req){
    Data data = getDataFromAPI(req);
    writeDataToDB(data);
}

@TimberLogTask(name = "get_data_from_api")
private Data getDataFromAPI(Request req) {
   validateUser(req);
   ...
}

@TimberLogTask(name = "validate_user")
private void validateUser(Request req) {
   ...
}

@TimberLogTask(name = "write_data_to_db")
private void writeDataToDB(Data data) {
   ...
}

As long as the methods are being executed in the same thread, a parent-child relationship will be formed between an open task and all tasks being called inside of it. In the above example, rest_request will be the parent of both get_data_from_api and write_data_to_db while get_data_from_api will be the parent of validate_user. All tasks will have rest_request as their primary task, as it is the root of this "tree".

Each task has a name specified by the user, a unique ID, its status, an (optional) parent ID and a primary ID. The status will be ERROR if the method threw an exception and SUCCESS otherwise.

TimberLoggerAdvanced

Timbermill also support opening a task in one thread and closing it in another using the TimberLoggerAdvanced class.

String taskId = TimberLoggerAdvanced.start("across_thread_task");
new Thread(() -> {
	TimberLoggerAdvanced.success(taskId);
}).run();

TimberLoggerAdvanced.start(name) return its task ID and they user can use that to add data or close the task manually, with either TimberLoggerAdvanced.success(id) or TimberLoggerAdvanced.error(id)

It's important to note that TimberLoggerAdvanced will not be a part parent-child relationship resolution on a thread, so any task opened after it will not get it as their parentId.

TimberLogger

Another class used to create Timbermill tasks is TimberLogger but this class is not recommended as it's prone to error due to misuse. It's basically does what @TimberLogTask, only manually. The only two cases you might consider using it is when you don't want to set the task STATUS as ERROR when an exception is thrown from the formula or when the name of the Task is not a constant but a variable. If you decided to use it we suggest you use the following structure:

TimberLogger.start("rest_request");
try {
    ...
    TimberLogger.success();
} catch (Throwable t) {
    TimberLogger.error(t);
    throw t;
}

This will ensure the task will be closed when exiting this block, even if an exception was thrown.

Task Properties

Properties can be added to a Timbermill task. They can be added to both a TimberLog/@TimberLogTask or a TimberLogAdvanced task.

LogParams logParams = LogParams.create().context("userId", userId).string("email", email).text("emailContent", emailContent).metric("emailsAmount", emailAmount);

TimberLogger.logParams(logParams);

TimberLoggerAdvanced.logParams(tasklogParams);

Spot tasks

Timbermill also include an API for creating Spot Task, which are tasks that are opened and closed in the same method. They are useful for logging events when their duration is not required.

TimberLogger.spot("server_startup", logParams);
TimberLogger.spotError("server_filaed", exception);

spot will be closed with a SUCCESS status and spotError with an ERROR

Manual Parent ID

Both TimberLogger and TimberLoggerAdvanced APIs support manually provide a specify parent ID for a task

TimberLogger.start("rest_request", parentId, logParams);
TimberLoggerAdvanced.start("rest_request", parentId, logParams);

If you want to specify a parent ID for @TimberLogTask use the following example:

public void restRequest(Request req) {
    try (TimberLogContext context = new TimberLogContext(taskId)) {
        getDataFromAPI();
    }
}

@TimberLogTask(name = "get_data_from_api")
private Data getDataFromAPI(){
    ...
}

Every task directly inside the try clause will be a child of taskId.