TNT4J: Intro, Concepts, Mission & Build Guide

This article introduces TNT4J, explains its key concepts and mission, and walks you through building it.

About TNT4J

Track and Trace for Java (TNT4J) is an application logging framework for correlation, diagnostics, and tracking of application activities within and across multiple applications, runtimes, servers, and geolocations. The API is designed specifically to troubleshoot distributed, concurrent, multithreaded, composite applications, and includes activity correlation, application state dumps, performance metrics, and user-defined metrics.

Here is a short list of TNT4J features:

• Simple programming model to facilitate fast root-cause analysis and log analysis

• Automated timing of application activities and sub-activities (elapsed time, idle time, message age)

• Application state dump framework for reporting internal variables and data structures

• Granular conditional logging based on application tokens and patterns that can be shared across applications and runtimes

• Share logging context across application, thread, and runtime boundaries

• Inter-log correlation of log entries (correlators and tags) between multiple related applications

• Intra-log correlation of related activities and sub-activities between multiple applications and threads

• Event location tags such as GPS and server

• Message-flow direction for composite applications that exchange messages (e.g., SOAP, JMS, SQL, etc.)

• User-defined properties such as CPU and memory logging, thread statistics per process/thread

• Extensible activity, sink, and error listeners for pre- and post-event processing

• Granular context such as thread ID, process ID, server, and application name

See Getting Started for a quick reference on TNT4J. A Wiki is also available.

TNT4J Mission

• Provide an easy way to track application behavior and activities across users, apps, servers, devices, and threads

• Dramatically reduce the time it takes to troubleshoot application behavior using a logging paradigm

• Capture performance metrics and application state to reduce diagnostic time

• Offer a simple programming model for ease of use

• Improve the quality and readability of logs to accelerate diagnostics

• Enrich log entries for automated analysis (manual analysis is often painfully long)

• Decrease or eliminate custom code required to track behavior and activities

• Remain independent of the underlying storage and formats

TNT4J Concepts

TNT4J is a plug-and-play tracking, tracing, and logging framework that consists of the following basic constructs:

• Tracker — High-level object that allows developers to track, trace, and log application activities.

• Activity — A collection of related tracking events (TrackingEvent) and other sub-activities. The relationship is established by developer-defined grouping or correlators (across thread and application boundaries). Activities may have properties grouped into property snapshots (PropertySnapshot).

• Tracking Event — A message with associated start/stop timestamps, severity, user-defined message, correlator, tag, location (such as GPS, server, etc.), and other event properties.

• Property — A single user-defined key/value/type pair for reporting a custom metric or attribute. Properties can be attached to an event, activity, or snapshot.

• Property Snapshot — A collection of properties with a category, name, and a timestamp associated with when the snapshot is taken. Activities may have one or more property snapshots.

• Formatter — Formats TNT4J objects (Activity, Tracking Event) into strings. It can be defined globally for a source using the event.formatter property, or per sink using event.sink.factory.Formatter.

• Tracking Selector — An object associated with a Tracker that performs conditional logging based on severity/key/value combinations. These combinations are stored in a token repository.

• Token Repository — Underlying storage used by the tracking selector to store and maintain severity/key/value combinations. It can be backed by a file, cache, memory, or other medium. Token repositories can be shared across application boundaries so conditional logging can span multiple applications, runtimes, and geolocations.

• Sink — A destination where objects can be written (e.g., file, socket, HTTP).

• Event Sink — A destination where events, activities, and messages are recorded (e.g., file, socket). Sinks use formatters to format objects before writing.

• Dump Sink — A sink where application dumps are recorded.

• Dump — A property snapshot that represents application state (name/value pairs). Applications can generate user-defined dumps to report application-specific metrics during diagnostics, on demand, or at VM shutdown.

• Dump Provider — A user-defined implementation that generates application dumps.

How to Build TNT4J