Tracker document
We refer to entries in the index as documents. Documents have a particular set of fields. In the Tracker search index, documents are configured to have the following fields:
Field name | Java data type | Description | SQL Table | SQL Column | SQL Data Type |
---|---|---|---|---|---|
internalId |
String |
A unique string used to tell documents apart. This is assigned by Tracker and is used to retrieve the document in future sessions, such as when you would like to update it by adding a new state to it. | toro_tracker_document |
internal_id |
VARCHAR(40) |
externalId |
String |
A unique string used to identify service invocations apart. A service call made during a certain date at 02:43 PM is different from the call made during 11:45 PM . This ID is assignable by users although by default, this is the current Unix time at which the service was called. |
toro_tracker_document |
external_id |
VARCHAR(40) |
type |
Type |
The name of the application you want the document to be associated with. By default, when a service is invoked by a Martini endpoint, the document type is the type of that Martini endpoint; services invoked via HTTP will have a document type after the name of leading path the call was directed at. | toro_tracker_document |
doc_type_id |
VARCHAR(100) |
stateName |
String |
The name of the system, user, or address that triggered the call. This can be the IP address where the HTTP inbound request came from or which Martini endpoint invoked the service. | toro_tracker_document |
sender_id |
VARCHAR(255) |
senderId |
String |
The name of the system, user, or address that triggered the call. This can be the IP address where the HTTP inbound request came from or which Martini endpoint invoked the service. | toro_tracker_document |
sender_id |
VARCHAR(255) |
receiverId |
String |
The name of the system, user, or address that is the eventual recipient of the invocation. If the invocation is triggered by an endpoint, then that endpoint's service is marked as the receiver. For HTTP endpoints, this is their relative request URL mapping. | toro_tracker_document |
receiver_id |
VARCHAR(255) |
userName |
String |
The user who initiated the call. This can be set to "Anonymous" if the caller is anonymous, or the name of a Marketplace user or Martini user, if known. |
toro_tracker_document |
user_name |
VARCHAR(150) |
timestamp |
long |
The time the document was created in Tracker. | toro_tracker_document |
time_received |
TIMESTAMP |
logs |
Collection< Log > |
Log messages that should be associated with the document. | toro_tracker_document_log |
||
properties |
Collection< Property > |
Key-value pairs that define additional or custom properties associated to a document. | toro_tracker_document_property |
||
states |
Collection< State > |
A list of states the document was in throughout the service invocation. | toro_tracker_document_state |
||
children |
Collection< String> |
Parent-child relationship listings wherein the document of interest is the child. | toro_tracker_document_relationship |
||
parents |
Collection< String> |
Parent-child relationship listings wherein the document of interest is the parent. |
Tracker documents are represented internally by Document
objects.
This is the same type you'll have to work with if you plan to fetch or set Tracker document properties in your code
(e.g. adding your own log messages, properties, or states); in which you'll use the aforementioned class's getter and
setter methods.
Customizable field values
Whilst Martini tries its best to automatically populate document fields with default values, they can still be overridden so that it conforms to your organization's preference.
Document types
A document type serves as a 'tag' for services, making it easier for you to organize and search for service invocations. If no document type is assigned, Tracker automatically creates one for you and uses that newly created document type when creating the Tracker document for the service that was invoked. The default document type differs depending on the type of service invocation that was done.
- For endpoints, the default document type is the type of endpoint.
- For Groovy-based Spring web services, Gloop API endpoints, and ad hoc Gloop service endpoints, the default document type is the leading path of the URL that was used to invoke the service.
Document types are represented by Type
objects and contain the following fields:
Field Name | Java Data Type | Description | SQL Table | SQL Column | SQL Data Type |
---|---|---|---|---|---|
id |
String |
The identifier for the document type. | toro_tracker_document_type |
doc_type_id |
VARCHAR(100) |
name |
String |
The name of the document type. | toro_tracker_document_type |
doc_type_name |
VARCHAR(100) |
It is possible to create, edit, and delete custom document types in Martini:
Log messages
Log messages are represented by Log
objects, which are composed of the following fields:
Field Name | Java Data Type | Description | SQL Table | SQL Column | SQL Data Type |
---|---|---|---|---|---|
id |
Long |
The identifier for the log message. | toro_tracker_document_log |
document_log_id |
INT(10) |
timeReceived |
long |
The time at which the message was logged. | toro_tracker_document_log |
time_received |
TIMESTAMP |
type |
String |
The type of log message. | toro_tracker_document_log |
log_type |
VARCHAR(10) |
message |
String |
The content of the log message itself. | toro_tracker_document_log |
log_message |
VARCHAR(1024) |
Ideally, document log messages should tell us about the service invocation's condition during certain time frames.
Properties
Key-value pairs that define additional or custom properties associated to a document.
Field Name | Data Type | Description | SQL Table | SQL Column | SQL Data Type |
---|---|---|---|---|---|
key |
String |
The name of the property. | toro_tracker_document_property |
property_key |
VARCHAR(30) |
value |
String |
The value of the property. | toro_tracker_document_property |
property_value |
VARCHAR(100) |
States
A list of states the document was in throughout the service invocation. States are so called because they let us know the different states the service invocation transitioned through whilst Martini was processing it. With states, the data present at certain points of the process (of invoking the service) is made known to us, like when it encounters an error, is starting the invocation, or has successfully completed the task.
States are represented internally by State
objects.
This type is comprised of the following fields:
Field Name | Data Type | Description | SQL | SQL Column | SQL Data Type |
---|---|---|---|---|---|
id |
Long |
The auto-generated, unique number used to identify document states. | toro_tracker_document_state |
document_state_id |
INT(10) |
name |
String |
The name of the state; does not have to be unique. | toro_tracker_document_state |
time_received |
TIMESTAMP |
timeReceived |
long |
The time at which this state was achieved. | toro_tracker_document_state |
state_name |
VARCHAR(50) |
canBeResubmitted |
boolean |
||||
contentFileName |
String |
||||
contentSize |
long |
||||
indexed |
boolean |
Document states are an important feature of Tracker. Document state records allow you to store binary and textual data within a document. This means you can save JSON or XML data, spreadsheets, or even PDF and word processor files. What's more, the data is all indexed in a search engine. This means that you can literally do a search within the Tracker search index and see which services are being used, as well as search for the data that's going into them.
Tracker uses Apache Tika to extract data from binary files, which Tracker then indexes to make such data queryable. Tracker will be able to index the data as long as its format is supported by Tika.
A document state's content typically comes in the form of message bodies. A message body is the payload of the message received and sent by Martini. For service invocations triggered by HTTP, this is the HTTP request and HTTP response1 bodies by default2. For services triggered by Martini endpoints, state contents will vary by type. For example, with email endpoints, the starting state can be the files attached in the received email or the body of the email itself; whilst the final state may contain the endpoint's reply to the email.
-
Before enabling request and/or response data logging, there are privacy and security concerns that should be addressed by the application developers. ↩
-
It's possible to add your own states to a document, but Martini by default, puts states of its own from the data received and sent by the endpoint. ↩