Logging data to Tracker
Martini exposes a small API that you can use to search and store data to the Tracker search index. Using the API, you can customize the way service calls look in the Tracker interface, as well as pick and choose which data will be indexed by Tracker for searching later.
Logging HTTP calls
Martini includes a file called trackers.xml
. This configuration file is located under the conf/
directory, and is
used by Tracker to determine which requests and responses are tracked. The distribution contains the following
content by default:
1 2 3 4 5 6 7 8 |
|
The <tracker>
declaration above means that all requests that start with /api/
are matched, but
skips tracking because the scope is set to none
. To see this in action, try removing the
scope
attribute:
1 |
|
This configuration will enable tracking for all requests that start with /api/
.
The <tracker>
element also contains the following attributes, for further customization:
Attribute | Default | Description |
---|---|---|
pattern |
(required) | The URL pattern, or the exact URL to match |
method |
all |
A comma-separated value of the request methods (e.g., GET, POST) to match |
scope |
all |
Indicates whether to log the request , response , all , or none |
internal-id |
(generated) | The identifier used for the document that tracks a single request-response lifecycle |
sender-id |
Client Addr | The value to be used as the Tracker document senderId |
receiver-id |
Path Info | The value to be used as the Tracker document receiverId |
document-type |
HTTP |
The value to be used as the Tracker document type |
More example Tracker configurations
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 |
|
How granular should I get?
While tracking generally enables you to have invaluable traceability, there are certain use cases where it might not be applicable. This may be one of, but not limited to:
- Preventing the indexing of sensitive information handled by services.
- Removing the performance overhead caused by Tracker and improve Martini's overall throughput.
Note that when configuring <tracker>
elements, the order of declaration is important. The elements
should be added, with the most specific at the top, and the most general at the bottom. For
example:
1 2 3 4 5 6 |
|
In this case, the second <tracker>
, is never matched because the first <tracker>
takes priority. The
correct configuration should be:
1 2 3 4 5 6 7 8 |
|
Restrictions
Out of the box, only the following base URLs are tracked:
- The
api.rest.base-path
on your application properties (defaults to/api
) /soap
/invoke
/flux-api
Thus, Tracker pattern
s can only start with any of the above.
Logging from HTTP client services
Logging HTTP requests that invoke the
io.toro.martini.HttpFunctions
.http(...)
service is done by configuring the trackable
input model. This model can be found in the Input side of the
Mapper view when the invoke step is selected. This model also has a field called
trackingScope
which changes the scope of the tracking for the HTTP request.
Logging from Flux
The Flux engine adds a Tracker document when a Flux service is executed. A document state is added for each of the following scenarios:
- Start of execution, where the document state contains the context of the Flux service in a JSON file.
- Execution of a state, where the document state contains the context of the invoked state in a JSON file.
- Occurrence of an exception, where the document contains the stacktrace of the exception from the
{stateName}-error.log
file. - End of execution.
No tracking for certain Flux invocations
A Flux invocation will not be logged to Tracker if it is debugged or run using the IDE.
We can track Flux executions invoked via REST API by
configuring the base path /flux-api
in the trackers.xml
. For example:
1 2 3 4 |
|
Or if per-package tracking is desired:
1 2 3 4 5 |
|
Differentiating by type
The document-type
attribute defaults to HTTP
.
While this value would work for all cases, it is recommended to supply a customized, sensible value
if you want an easier time searching and filtering documents.
The above setup enables tracking, but the document will only record states
related to the request-response lifecycle, and not the Flux states.
To include Flux states in the Tracker document, declare a GloopString
input property named
$trackerId
on your Flux service.
The Tracker document may further be updated, by calling services from
TrackerMethods
and using $trackerId
from the input.
Logging from Martini endpoints
To log data processed by Martini endpoints to Tracker, the Logging property of the endpoint you want to track must be checked in the Endpoint configuration editor. You will be able to set this property when creating or configuring an endpoint. Unchecking this property means data processed by the endpoint is left unindexed.
Programmatic logging
To manually create or update Tracker documents in the
Tracker search index, developers can use the services in
Tracker
. The TrackerMethods
class is located in the
core
package, under the services/io/toro/martini
directory, as seen in the
Navigator view.
To update a Tracker document, you would need its internalId
. For certain invocations that
are already tracked, the document may be further populated by invoking functions on the internal ID injected to the
service being used. This automatically becomes available by declaring:
- a string input property named
$trackerId
in Gloop services; - a string input property named
$trackerId
in Flux services; or - a
java.lang.String
method parameter named$trackerId
in Groovy services.
Tracker ID
$trackerId
is analogous to internalId
. For backwards-compatibility, declaring internalId
as the variable name will also work, albeit only on Gloop and Groovy services.
Discrepancies
There are a few discrepancies among Tracker documents, depending on how a service is exposed. To show you these differences, the following examples below1 are provided:
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 |
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 |
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 |
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 |
|
As you may notice, Groovy service, Gloop API, and ad hoc Gloop service endpoints have fairly similar fields.
- By default, these types have set the leading URL mapping as the name and ID of the type of each document.
In the example, all endpoints are accessible via the path
/hello/{name}
, wherein the leading URL path ishello
. - The
senderId
is the IP address where the request came from. - The
receoverId
is the URL mapping where the request was received at.
Martini endpoints service invocations differ in that:
- The default name of their starting state is
"Started"
instead of"Received"
. - The
senderId
is the name of the endpoint itself. - The
receiverId
is the qualified name of the service of the endpoint.
-
Displayed JSON data are obtained via the
/tracker/document/{id}
endpoint. ↩