Task

Unlike other logging systems, which uses text events to log what occurred in a system, Timbermill uses Tasks. Tasks are the basic entities in Timbermill.

Task structure

Every task has a number of fields representing info about what happened on the application it logged.

• name - Task's name given by the user at creation.
• _id - A unique ID for the task.
• env - On which environment this task was created.
• status - Current Task status.
• parentId - ID of the parent task.
• primaryId - ID of the primary task, the root.
• parentPath - Lists of names of the task's ancestors. Starting from the primary task, to the parent task.
• meta.taskBegin - Task start time.
• meta.taskEnd - Task end time.
• meta.duration - Task duration.
• ctx.*/string.*/text.*/metric.* - Custom info provided by the user.

Statuses

A task can have the following statuses:

• UNTERMINATED - Task was started but not ended yet.
• SUCCESS - Task was closed successfully.
• ERROR - Task was closed with an error.
• PARTIAL_SUCCESS - Task was closed successfully, but was not opened. Usually points to a problem in usage.
• PARTIAL_ERROR - Task was closed with an error, but was not opened. Usually points to a problem in usage.
• PARTIAL_INFO_ONLY - Info was sent to a task, but it was not opened nor closed. Usually points to a problem in usage.
• CORRUPTED - Task is corrupted. Reasons can be it was opened twice for the same ID, closed twice for the same ID or mismatch of values across its events. Corruption reason is stated under string.corruptedReason

ctx, string, text, metric

Timbermill support 4 kinds of data which a user can add to a task.

• ctx/string - Text fields, not analyzed, saved as-is, filterable, aggregatable, translate into Keyword data type in elasticsearch. Suitable of relatively short strings, e.g. mail subject.
• text - Text fields, can be “free searched”, translate into Text data type in elasticsearch. Suitable for longer strings, e.g. mail content.
• metric - Number fields.

Difference between ctx and string fields.

ctx fields are inherited, meaning a ctx value assigned to a task will also be visible on all of its children and on their children, etc. string fields will only be available on the task they were assigned to.

@TimberLogTask(name = "rest_request")
public void restRequest(Request req) {
	TimberLogger.logContext("user", req.getUser());
	TimberLogger.logString("requestType", req.getType());
	getDataFromAPI();
}

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

In this example both rest_request and get_data_from_api will show the field ctx.user with its value but only rest_request will show field requestType.