Skip to content

Overview

Concepts and Principles

Development

Overview

IDEs

API Explorer

Releases

Release Notes

TORO Integrate

Coder Studio

Coder Cloud

Bug Reports

Search

Logging Data to Tracker

TORO Integrate 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 integrations look in the Tracker UI, as well as pick and choose which data will be indexed by Tracker for searching later.

Logging to Tracker from Gloop

HTTP, Tracker, and Gloop

By default, all HTTP requests that map to a Gloop service are logged. To disable this, you can change the HTTP logging property.

To manually create or update Tracker documents in the Tracker search index, integration developers can use the services in TrackerMethods. The TrackerMethods class is located in the core package, under the services/io/toro/integrate code directory, as seen in the Coder Navigator view.

Coder showing the available methods in Gloop for Tracker

Coder showing the available methods in Gloop for Tracker

To update a Tracker document, you would need to have its internalId. A Gloop service invoked over HTTP and whose tracking is also enabled makes this property available via the presence of an input property called $internalId.

Logging to Tracker from Groovy

TORO Integrate has a custom annotation for tracking the data of Groovy services invoked via HTTP. To use this, annotate the service that you wanted to track with the @Track annotation. For example:

1
2
3
4
@Track
public String greeting(String name) {
    return "Hello, ${name}!"
}

Furthermore, the scope of the tracking can be customized to track the request only, the response only, both, or none at all. This can be done by setting the value property of the @Track annotation.

1
2
3
4
5
6
7
8
9
@Track(TrackMethod.REQUEST) // This would track the request only
public String greeting(String name) {
    return "Hello, ${name}!"
}

@Track(TrackMethod.RESPONSE) // This would track the response only
public String greeting (String name) {
    return "Hello, ${name}!"
}

If TORO Integrate created a document for you and you need the internalId, simply add a String parameter to your method called internalId, and TORO Integrate will map it for you. For example:

1
2
3
4
5
6
@Track
public String greeting(String name, String internalId) {
    "The internal ID is ${internalId}".info()
    internalId.addDocumentProperty('name', name)
    return "Hello, ${name}!"
}

The TrackerMethods class contains many one-liners which you can use to add and update the Tracker search index.

Logging Data Processed By Endpoints to Tracker

To log data processed by Integrate 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.

Endpoint logging property

Endpoint logging property

Using Tracker with Flux

If your integration invokes Flux and you want to update an existing document, add an input property to your service called $fluxTrackerId to get ahold of the document's internalId.

Logging HTTP Requests Made by Gloop Services to Tracker

Logging HTTP requests that invoke the io.toro.integrate.HttpMethods.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.

HTTP invoke step showing the trackable input property

HTTP invoke step showing the trackable input property

Default HTTP Logging

TORO Integrate uses an application property that can be configured to enable and disable logging to Tracker for HTTP requests it receives. This property is called http.invoke.track.enable and it accepts a boolean value. The default value for this true, and thus, all HTTP requests are being logged to Tracker by default.

Adding Geo IP data to your Tracker Documents

TORO Integrate can also automatically add geolocation data to a Tracker document from an HTTP request. It uses the MaxMind Geo IP database to do so. You can either install the databases yourself in the data/geoip directory, or have TORO Integrate download and update them for you.

Installation Using the UI

To have TORO Integrate download the Geo IP database for you, hover over the Configuration menu item in the Server Admin UI, then click on Geo. IP Database.

Downloading the Geo IP database

Once the file has been downloaded, a dialog will appear telling you that it has completed:

Prompt showing successful download of the Geo IP database

Installation Using REST Endpoints

TORO Integrate also provides REST endpoints for downloading and updating the Geo IP Database. Send a POST request to the following endpoint to download the database: <host>:<port>/esbapi/tracker/geoip/initialize.

The easiest way to do this is to use the API Explorer.

API Explorer after downloading the Geo IP database

TORO Integrate will also log messages similar to the ones below outlining that the database has been downloaded.

1
2
3
4
14/09/18 16:33:31.750 INFO  [MaxmindGeoIpService] Starting download on http://geolite.maxmind.com/download/geoip/database/GeoLite2-City.mmdb.gz
14/09/18 16:33:42.833 INFO  [MaxmindGeoIpService] GeoIP database http://geolite.maxmind.com/download/geoip/database/GeoLite2-City.mmdb.gz downloaded to /opt/toro-integrate/data/geoip/GeoIP2-City.mmdb.gz
14/09/18 16:33:42.839 INFO  [MaxmindGeoIpService] Starting download on http://geolite.maxmind.com/download/geoip/database/GeoLite2-Country.mmdb.gz
14/09/18 16:33:43.664 INFO  [MaxmindGeoIpService] GeoIP database http://geolite.maxmind.com/download/geoip/database/GeoLite2-Country.mmdb.gz downloaded to /opt/toro-integrate/data/geoip/GeoIP2-Country.mmdb.gz

Geo IP Properties

Once the database is installed, any subsequent document that was created from an HTTP request will have the Request City, Request Coordinates, and Request Country properties added, as shown below:

Server Admin UI showing Geo IP properties

Google Maps Integration

TORO Integrate can also show a map of the Geo IP location. To enable this, get a Google Maps API key, and add it to the tracker.maps.google.apiKey application property. Once this is done, the Server Admin UI will also display a map of the location for all existing and new documents with the related Geo IP properties.

Server Admin UI showing Geo IP map

Disabling Logging