Martini Services Tracker Document Structure

Tracker Document

In Martini, entries within the Tracker module are referred to as documents. These documents are essential for monitoring service invocations, logging, and tracking the state changes over time. Each document is identified by a set of fields designed to capture detailed information about each service invocation or process being monitored.

Document Fields

Documents within the Tracker search index are defined by specific fields, each with its unique purpose and data type. The following table outlines these fields, their Java data types, descriptions, and corresponding SQL storage details:

Field Name	Java Data Type	Description	SQL Table	SQL Column	SQL Data Type
internalId	String	A unique identifier assigned by Tracker to distinguish documents. Used for retrieving and updating documents.	toro_tracker_document	internal_id	VARCHAR(40)
externalId	String	A user-assignable unique identifier for service invocations, differing by time or other criteria. Defaults to the Unix time at service call.	toro_tracker_document	external_id	VARCHAR(40)
type	Type	Specifies the application associated with the document, defaulting to the Martini endpoint type for HTTP-invoked services.	toro_tracker_document	doc_type_id	VARCHAR(100)
stateType	String	Denormalized from the document's most recently received state; reflects that state's stateType. Nullable, defaults to null when the latest state is unclassified.	N/A	N/A	N/A
stateName	String	Identifies the trigger source of the call, such as an IP address or Martini endpoint.	toro_tracker_document	sender_id	VARCHAR(255)
senderId	String	Similar to stateName, specifies the system, user, or address initiating the call.	toro_tracker_document	sender_id	VARCHAR(255)
receiverId	String	The system, user, or address that is the target of the invocation.	toro_tracker_document	receiver_id	VARCHAR(255)
userName	String	The name of the user who initiated the call, or "Anonymous" if not identified.	toro_tracker_document	user_name	VARCHAR(150)
timestamp	long	The creation time of the document in Tracker.	toro_tracker_document	time_received	TIMESTAMP
logs	Collection<Log>	Associated log messages for the document.	toro_tracker_document_log	N/A	N/A
properties	Collection<Property>	Custom key-value pairs associated with the document.	toro_tracker_document_property	N/A	N/A
states	Collection<State>	The list of states the document has been through.	toro_tracker_document_state	N/A	N/A
children	Collection<String>	Identifies documents where the current document is a child in a parent-child relationship.	toro_tracker_document_relationship	N/A	N/A
parents	Collection<String>	Identifies documents where the current document is a parent in a parent-child relationship.	toro_tracker_document_relationship	N/A	N/A

Working with Document Objects

Internally, Tracker documents are represented as Document objects. To interact with these documents programmatically, such as fetching, updating, or adding new logs, properties, or states, developers will utilize the getter and setter methods of the Document class.

Customizable Field Values

While Martini automatically populates document fields with default values, these values can be overridden to align with organizational preferences. This customization allows for a more tailored tracking and monitoring experience within the Tracker module.

Document Types

Document types in Martini act as tags for services, facilitating the organization and searchability of service invocations. They play a crucial role in categorizing services in a way that enhances the efficiency of tracking and monitoring within the Tracker module.

Default Document Types

When a service is invoked, if no document type has been explicitly assigned, Tracker automatically generates one. The default document type assigned by Tracker varies depending on the method of service invocation:

• Endpoints: The default document type is determined by the type of endpoint.
• Groovy-based Spring Web Services, API Endpoints, and Ad Hoc Service Endpoints: The default document type is derived from the leading path of the URL used to invoke the service.

These defaults ensure that even without manual tagging, services are logically grouped and can be easily identified and retrieved.

Representation and Fields

Document types are internally represented by Type objects, which are structured with specific fields to store and describe the document type's characteristics. The table below outlines the fields associated with document types:

Field Name	Java Data Type	Description	SQL Table	SQL Column	SQL Data Type
id	String	A unique identifier for the document type.	toro_tracker_document_type	doc_type_id	VARCHAR(100)
name	String	The descriptive name of the document type.	toro_tracker_document_type	doc_type_name	VARCHAR(100)

These fields allow for detailed definition and categorization of document types, making it easier to manage and query documents within the Tracker.

Log Messages

In the context of service monitoring and troubleshooting within Martini, log messages play a vital role in capturing detailed information about service invocations. These messages provide insights into the behavior and condition of services at specific points in time, facilitating debugging and analysis.

Log Object Structure

Log messages in Martini are encapsulated within Log objects. Each Log object comprises several fields, each designed to capture and convey specific aspects of the log message. The table below details these fields, including their data types and storage considerations:

Field Name	Java Data Type	Description	SQL Table	SQL Column	SQL Data Type
id	Long	A unique identifier for the log message.	toro_tracker_document_log	document_log_id	INT(10)
timeReceived	long	The timestamp when the message was logged.	toro_tracker_document_log	time_received	TIMESTAMP
type	String	The category or type of log message.	toro_tracker_document_log	log_type	VARCHAR(10)
message	String	The actual content of the log message.	toro_tracker_document_log	log_message	VARCHAR(1024)

Field Descriptions

• id: Serves as the primary key for each log message, ensuring that every log entry can be uniquely identified.
• timeReceived: Indicates the exact moment the log message was created, which is crucial for chronological troubleshooting and analysis.
• type: Categorizes the log message into different types (e.g., INFO, ERROR, DEBUG), allowing for easier sorting and filtering based on severity or purpose.
• message: Contains the descriptive text of the log message, providing details about the service invocation's condition, errors encountered, or other relevant information.

Properties

Properties serve as key-value pairs that enrich documents with additional or custom information. These properties are instrumental in providing context, details, and metadata associated with a document, thereby enhancing its descriptive capacity beyond the standard fields.

Structure of Properties

Properties are represented as simple key-value pairs, where each pair consists of a unique key and its corresponding value. This structure allows for flexible and dynamic association of information with documents. The table below outlines the fields that define a property:

Field Name	Data Type	Description	SQL Table	SQL Column	SQL Data Type
key	String	The name of the property, acting as a unique identifier.	toro_tracker_document_property	property_key	VARCHAR(30)
value	String	The value associated with the key, providing specific information or context.	toro_tracker_document_property	property_value	VARCHAR(100)

Field Descriptions

• key: Serves as the identifier for the property. It is a unique string that specifies the nature or category of the information being stored.
• value: Contains the actual data or information associated with the key. The value provides the specific detail or context for the property key.

States

The concept of "states" is used to track the lifecycle of a document through the service invocation process. States provide a chronological record of the various phases a service invocation undergoes, from initiation to completion, including any errors encountered along the way. This feature is key to understanding the progression and outcome of service invocations within Martini.

State Object Structure

States are encapsulated within State objects, each representing a specific point in the service invocation process. The following table details the fields within a State object, including their data types and descriptions:

Field Name	Data Type	Description	SQL Table	SQL Column	SQL Data Type
id	Long	A unique identifier for the state, auto-generated by Martini.	toro_tracker_document_state	document_state_id	INT(10)
name	String	The name of the state, indicating its role or phase in the invocation process.	toro_tracker_document_state	state_name	VARCHAR(50)
timeReceived	long	The timestamp marking when this state was recorded.	toro_tracker_document_state	time_received	TIMESTAMP
canBeResubmitted	boolean	N/A	N/A	N/A	N/A
contentFileName	String	N/A	N/A	N/A	N/A
contentSize	long	N/A	N/A	N/A	N/A
indexed	boolean	N/A	N/A	N/A	N/A
stateType	String	The visual and semantic type of the state. Nullable; defaults to null when the state is unclassified.	N/A	N/A	N/A

State types

The runtime supports the following state types:

Value	Intended use
INFO	Informational progress or status
SUCCESS	A successfully completed step
WARNING	A step completed with a non-fatal condition
ERROR	A failed step or error condition

State types are optional when creating a state. Existing calls that omit stateType remain valid; when supplied, use one of the values above.

Null and default behaviour

stateType is nullable on Document.State and defaults to null when a state is added without one—for example, through a call to addDocumentState or addDocument that omits the parameter. A document's own stateType field is denormalized from its most recently received state, so it always mirrors the latest state's classification (or null, if the latest state is unclassified).

System-generated states

States that Martini generates automatically during service and workflow execution are classified as follows:

System state	stateType
Started	INFO
Finished	SUCCESS
Failed	ERROR

Pre-existing data

Introducing stateType does not migrate or backfill existing Tracker data. States and documents created before this feature was available keep a null stateType, and are excluded whenever a search or filter targets a specific stateType value (for example, filtering for ERROR only returns documents or states explicitly classified as ERROR, never pre-existing unclassified ones).

Datastore support

stateType filtering is supported across all Tracker-backed datastores: Nitrite, Cassandra, and DynamoDB, as well as the Solr search index. For details on addDocumentState/addDocument and the current lack of a stateType parameter on TrackerMethods.searchTracker, see Martini Tracker Functions.