Skip to content

Martini Services Tracker Search API

The Tracker Search API is a powerful tool within Martini, designed to provide developers with a seamless and efficient way to query data indexed by their applications. Leveraging the capabilities of Apache Solr, Martini enhances and simplifies the process of retrieving information, making it more accessible and user-friendly. This documentation outlines the key features, benefits, and how to utilize the Tracker Search API effectively.

Martini's integration with Apache Solr offers developers an extended API for querying indexed data. This functionality is crucial for applications that require frequent data retrieval based on specific criteria. Martini re-exposes Solr's API with additional endpoints, making it easier and more convenient for developers to perform document searches without directly interacting with Solr servers.

Key Features

  • Embedded Solr Core Searches: Martini supports document searches within embedded Solr cores using RESTful requests.
  • Simplified Authentication: Users authenticated with Martini do not need separate authentication for Solr queries, streamlining the process.
  • Enhanced Query Endpoints: Martini introduces additional endpoints for querying, designed to simplify and expedite data retrieval.

Use Cases

The Tracker Search API can query documents within various Solr cores, including:

  • Tracker: Martini's built-in document tracker.
  • Invoke Monitor: Monitors and logs invocation data.
  • Custom Search Indices: Any connected custom indices tailored to specific application needs.

Utilizing the Tracker Search API

To access and utilize the Tracker Search API, developers must include specific headers in their request. These headers ensure secure and authorized access to the API's functionalities.

Required Headers

Header Name Data Type Description
Authorization string Access token of an authenticated Martini user.

Path Parameters

When utilizing Martini's Solr API for querying data, it's essential to understand how to correctly specify the path to access the desired endpoints. Each endpoint within this API is structured to receive specific path parameters that direct the query to the appropriate Solr instance and core. This section provides a detailed overview of the path parameters required to use the API effectively.

API Endpoint Structure

The base path for all endpoints in Martini's Solr API is as follows:

1
/esbapi/v1/solr/<package>/<core>/

This structure is designed to ensure that queries are accurately routed to the correct package and core within your Martini instance.

Specifying Path Parameters

To use the API, you must replace <package> and <core> with the appropriate values for your query. The meaning and importance of each parameter are outlined in the table below:

Parameter Name Data Type Description
package string The name of the Martini package where the Solr instance is configured.
core string The name of the target Solr core you wish to query.
Package

The package parameter refers to the specific Martini package that contains the configured Solr instance. Martini packages serve as containers for grouping related functionalities, and each package can be configured to interact with one or more Solr cores.

Core

The core parameter specifies the Solr core within the mentioned package that you intend to query. Solr cores are essentially individual instances of Solr, each capable of managing its own set of documents and configurations. By specifying the core, you direct your query to the exact set of data you need to access.

Query Parameters

Martini's Solr Search API extends the functionality of Apache Solr's REST API, offering developers a powerful tool for querying indexed data. Understanding the available query parameters is essential for leveraging the full capabilities of the API. This section highlights key resources for familiarizing yourself with the supported parameters and outlines the usage of query parameters within the context of Martini's API.

Overview

The Martini Solr Search API supports a wide range of query parameters that are also available in Solr's REST API. These parameters enable developers to perform complex queries, such as faceting, grouping, and retrieving statistics, enhancing the ability to extract meaningful insights from indexed data.

Key Resources for Understanding Query Parameters

To effectively use the Martini Solr Search API, developers should become acquainted with the following aspects of Solr's query parameters:

  • Common Query Parameters: These are the parameters common across all Solr parsers, enabling basic query customization and control over the search results.
  • Faceting Query Parameters: Faceting parameters allow for the categorization of search results based on indexed terms. Key faceting techniques include Range faceting and Pivot faceting, which organize search results into meaningful groups.
  • Result Grouping: This feature uses specific parameters to group documents together, allowing for the retrieval of top documents within each group. It's particularly useful for collapsing search results with similar characteristics.
  • Stats Component: By utilizing the stats component, developers can append parameters to their queries to gather statistics on numeric, string, or date fields within the document set. This is invaluable for analyzing data trends and distributions.

Unsupported Parameters

It's important to note that the wt (writer type) query parameter is not supported by Martini's Solr Search API. Instead, the response format can be specified through the Accept header in the request, with the following commonly used options:

  • text/plain: Returns plain text responses, suitable for simple text outputs.
  • application/json: Provides responses in JSON format, ideal for web applications and services that consume JSON.
  • application/xml: Returns XML formatted responses, useful for applications that process or transform XML data.

Endpoints

Martini's Solr API significantly enhances the flexibility and efficiency of search operations by not only mirroring Apache Solr's Search API but also by introducing additional endpoints tailored for optimized search functionalities. These endpoints are designed to streamline various search and data analysis operations, providing developers with powerful tools for facet counting, term listing, statistics gathering, and advanced faceting. This section outlines the key endpoints available through Martini's Solr API and their intended use cases.

Enhanced Search Endpoints

List Facet Count

  • Purpose: This endpoint is used to retrieve a count of the facets for a given query, allowing developers to quickly understand the distribution of data across different categories.

Get Facet Count

  • Purpose: Similar to the List Facet Count, this endpoint provides the count for a specific facet within the search results, offering a more focused view on a particular category.

List Facet Terms

  • Purpose: It enables the listing of distinct facet terms found within the search results. This is particularly useful for identifying the variety of terms within a specific facet category.

List Statistics

  • Purpose: This endpoint offers a comprehensive overview of statistics for the search results, encompassing various metrics like count, min, max, sum, and mean. It's invaluable for a quick analysis of the data set.

Get Statistics

  • Purpose: For detailed insights on a specific document field, the Get Statistics endpoint provides targeted statistical information, helping in deep-dive analyses of data attributes.

Range Faceting

  • Purpose: Enables developers to perform faceted searches based on ranges within the data, such as date ranges or numerical intervals. This is useful for segmenting search results into defined buckets.

Pivot Faceting

  • Purpose: This advanced faceting technique allows for multi-dimensional analysis, where facets are nested within one another. Pivot faceting is instrumental in exploring complex relationships between different data dimensions.

Solr API

Martini's Solr API provides a direct interface to Apache Solr's powerful search functionality, enabling developers to execute sophisticated queries and retrieve indexed data efficiently. This section focuses on the primary endpoint of Martini's Solr API, which mirrors Apache Solr's native REST API, emphasizing the SearchHandler for executing search queries.

Overview

Method: GET

Path: /esbapi/v1/solr/<package>/<core>/<request-handler>

This endpoint is pivotal for accessing the capabilities of Solr's REST API through Martini, making it crucial for developers to understand Solr's operation and configuration.

Key Features

  • Mirrors Apache Solr's SearchHandler: The select request handler, which is central to querying Solr's index, is fully supported and mirrored by Martini.
  • Limited to SearchHandler: Only Solr's SearchHandler functionality is mirrored. Other handlers, like the UpdateHandler, are not supported within Martini. For these functionalities, direct interaction with Solr server is necessary.
  • Configuration Dependency: The effectiveness and availability of request handlers depend on their configuration in solrconfig.xml. Proper configuration ensures the API works as expected.

Request

Path Parameters

Parameter Name Data Type Description
request-handler string Specifies the Solr request handler to be used during the search operation.

Example Request

Using curl to query two documents from the invoke_monitor core:

1
2
3
curl -X GET \
  'http://<host>:<port>/esbapi/v1/solr/<package>/invoke_monitor/select?q=*%3A*&rows=2&cache=false' \
  -H 'Authorization: Bearer <access-token>'

Response

Content Type

Responses from Martini's Solr API can be in various formats, depending on the specified Accept header, including:

  • application/json
  • application/xml
  • text/plain

Example Response

A JSON response showcasing the search results:

 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
43
44
45
46
47
48
49
50
{
    "responseHeader": {
        "status": 0,
        "QTime": 1,
        "params": {
            "q": "*:*",
            "cache": "false",
            "rows": "2",
            "wt": "json",
            "version": "2.2"
        }
    },
    "response": {
        "numFound": 29,
        "start": 0,
        "docs": [
            {
                "id": "64db237c-7523-4ba1-8bf7-404b30c59a5e",
                "ruleId": -1,
                "timeReceived": "2018-01-24T00:48:15.780Z",
                "packageName": "examples",
                "endpointName": "public java.lang.Object SnoopScript.snoopRequest(javax.servlet.http.HttpServletRequest,javax.servlet.http.HttpServletResponse)",
                "endpointType": "http",
                "serviceName": "public java.lang.Object SnoopScript.snoopRequest(javax.servlet.http.HttpServletRequest,javax.servlet.http.HttpServletResponse)",
                "url": "/invoke/examples/groovy/SnoopScript/public java.lang.Object SnoopScript.snoopRequest(javax.servlet.http.HttpServletRequest,javax.servlet.http.HttpServletResponse)",
                "user": "user",
                "success": false,
                "cost": 1,
                "responseTime": 20,
                "_version_": 1590432781769375744
            },
            {
                "id": "ffad11c0-3669-4afe-844b-68413cd22134",
                "ruleId": -1,
                "timeReceived": "2017-08-18T03:07:31.263Z",
                "trackerId": "37bf1014-09c0-427f-89a5-9ef54f5157ab",
                "packageName": "examples",
                "endpointName": "public java.lang.Object SQLExamples.getEmployees()",
                "endpointType": "http",
                "serviceName": "public java.lang.Object SQLExamples.getEmployees()",
                "url": "/invoke/examples/groovy/SQLExamples/public java.lang.Object SQLExamples.getEmployees()",
                "user": "user@example.com",
                "success": true,
                "cost": 1,
                "responseTime": 7,
                "_version_": 1576036625380540416
            }
        ]
    }
}

List Facet Count

The List Facet Count endpoint in Martini's Solr API is a focused tool designed to query the Solr index for facet counts based on specified document fields. It is an essential feature for aggregating and summarizing data, providing a high-level overview of the distribution of values within the index.

Endpoint Details

  • Method: GET
  • Path: /esbapi/v1/solr/<package>/<core>/facets

This endpoint facilitates the generation of facet counts by analyzing the specified facet.field terms within the indexed documents.

Request

Query Parameters

To effectively use the "List Facet Count" endpoint, specific query parameters must be included in your request. The most crucial parameter is facet.field, which determines which document fields to analyze for facet counts.

Parameter Name Data Type Required Description
facet.field string true Identifies the document field to be treated as a facet. Multiple facet.field parameters can be used.

Additional faceting query parameters may be employed to refine the results further, tailoring the facet counts to meet specific analytical needs.

Example Request

Below is an example of how to structure a cURL request to this endpoint:

1
2
3
curl -X GET \
  'http://<host>:<port>/esbapi/v1/solr/<package>/invoke_monitor/facets?q=endpointType%3Aftp-server&facet.field=packageName&facet.field=endpointName' \
  -H 'Authorization: Bearer <access-token>'

This request specifies that facet counts should be generated for documents where endpointType is ftp-server, focusing on the packageName and endpointName fields.

Response

Content Type

The API can return responses in various formats, including:

  • application/json
  • application/xml
  • text/plain

Example Response

A sample JSON response illustrating the facet counts for packageName and endpointName might look like:

 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
{
    "facet_field": {
        "packageName": {
            "name": "packageName",
            "facet_count": 3,
            "count": 895,
            "facet": [
                {
                    "name": "Package_00",
                    "count": 335
                },
                {
                    "name": "Package_01",
                    "count": 282
                },
                {
                    "name": "Package_02",
                    "count": 278
                }
            ]
        },
        "endpointName": {
            "name": "endpointName",
            "facet_count": 3,
            "count": 895,
            "facet": [
                {
                    "name": "Endpoint_02",
                    "count": 309
                },
                {
                    "name": "Endpoint_00",
                    "count": 306
                },
                {
                    "name": "Endpoint_01",
                    "count": 280
                }
            ]
        }
    }
}

Get Facet Count

The Get Facet Count endpoint is a specialized feature within Martini's Solr API that focuses on generating a facet count for a single specified facet field. This targeted approach allows for a more refined analysis of data within a particular field of interest.

Endpoint Details

  • Method: GET
  • Path: /esbapi/v1/solr/<package>/<core>/facet/<facet-field>

This endpoint simplifies the process of obtaining facet counts by concentrating on one facet field at a time, making it ideal for detailed analysis of specific data aspects.

Request

Path Parameters

To effectively use the "Get Facet Count" endpoint, you must specify the facet field of interest in the path parameters. This identifies the document field to be treated as a facet for counting purposes.

Parameter Name Data Type Required Description
facet-field string true The document field designated for facet counting.

Additional query parameters can be utilized to further tailor the search and facet counting process, enhancing the specificity and relevance of the results.

Example Request

Below is an example of how to structure a cURL request to this endpoint:

1
2
3
curl -X GET \
  'http://<host>:<port>/esbapi/v1/solr/<package>/invoke_monitor/facet/packageName?q=user%3AUser_016' \
  -H 'Authorization: Bearer <access-token>'

This request filters documents by the user field with a value of User_016 and retrieves the facet count for the packageName field.

Response

Content Type

The API can return the facet count information in various formats, including:

  • application/json
  • application/xml
  • text/plain

Example Response

A sample JSON response illustrating the facet count for the packageName field might look like:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
{
    "name": "packageName",
    "facet_count": 3,
    "count": 895,
    "facet": [
        {
            "name": "Package_00",
            "count": 335
        },
        {
            "name": "Package_01",
            "count": 282
        },
        {
            "name": "Package_02",
            "count": 278
        }
    ]
}

List Facet Terms

The List Facet Terms endpoint within Martini's Solr API is a valuable feature that allows for the enumeration of all terms associated with a specified facet field. This capability is instrumental in understanding the diversity of data within a particular facet, facilitating comprehensive data analysis and insight generation.

Endpoint Details

  • Method: GET
  • Path: /esbapi/v1/solr/<package>/<core>/facet/<facet-field>/names

This endpoint is designed to list all terms under a given facet field, providing a clear view of the variety of data points within that field.

Request

Path Parameters

To leverage the "List Facet Terms" endpoint, the specific facet field of interest must be identified in the path parameters. This parameter dictates which document field will be analyzed to list its terms.

Parameter Name Data Type Required Description
facet_field string true Specifies the document field to be examined for facet terms.

Additional query parameters may be utilized to fine-tune the search criteria and result customization, enhancing the relevance and specificity of the output.

Example Request

Here's how to construct a cURL request for this endpoint:

1
2
3
curl -X GET \
  'http://<host>:<port>/esbapi/v1/solr/<package>/invoke_monitor/facet/packageName/names?q=*%3A*' \
  -H 'Authorization: Bearer <access-token>'

In this example, the q query parameter is set to *:* to match all documents, aiming to list all terms of the packageName facet field across the entire document set.

Response

Content Type

Responses from this endpoint can be delivered in various formats, including:

  • application/json
  • application/xml
  • text/plain

Example Response

A simple JSON array response listing the terms for the packageName facet field might appear as follows:

1
2
3
4
5
[
    "Package_01",
    "Package_00",
    "Package_02"
]

List Statistics

The List Statistics endpoint in Martini's Solr API provides a comprehensive tool for generating detailed statistics on numeric, string, and date fields within a document set. By specifying stats.field, users can obtain a wide array of statistical data, offering valuable insights into their indexed content.

Endpoint Details

  • Method: GET
  • Path: /esbapi/v1/solr/<package>/<core>/stats

This endpoint allows for the calculation of statistics over specified fields in the Solr index, facilitating the analysis of data distributions, frequencies, and other statistical measures.

Request

Query Parameters

The use of specific query parameters enables the customization of statistical data retrieval, catering to various analytical needs.

Parameter Name Data Type Required Description
stats.field string true Specifies the document field for which statistics are to be generated. Multiple fields can be indicated for comprehensive statistical analysis.
stats.calcdistinct boolean false Determines whether distinct count and values are calculated. This can be resource-intensive for fields with high cardinality and is thus disabled by default for performance reasons.

Additional parameters may be employed to further tailor the statistical output, enhancing the detail and relevance of the analysis.

Example Request

Below is an example of how to structure a request to this endpoint:

1
2
3
curl -X GET \
  'http://<host>:<port>/esbapi/v1/solr/<package>/invoke_monitor/stats?stats.field=%7B!func%7Dtermfreq('\''packageName'\''%2C'\''Package_01'\'')&stats.field=%7B!func%7Dtermfreq('\''endpointType'\''%2C'\''ftp-server'\'')&q=*%3A*' \
  -H 'Authorization: Bearer <access-token>'

This request utilizes function queries within stats.field to generate statistics based on the frequency of specific values within the packageName and endpointType fields.

Response

Content Type

Statistical results can be output in various formats to accommodate different processing requirements:

  • application/json
  • application/xml
  • text/plain

Example Response

A sample JSON response showcasing statistics for the endpointType and packageName fields might look like:

 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
{
    "stats": {
        "termfreq('endpointType','ftp-server')": {
            "name": "termfreq('endpointType','ftp-server')",
            "min": 0,
            "max": 1,
            "sum": 895,
            "count": 10032,
            "missing": 0,
            "mean": 0.089214513556619,
            "sumOfSquares": 895,
            "stddev": 0.28506733335231
        },
        "termfreq('packageName','Package_01')": {
            "name": "termfreq('packageName','Package_01')",
            "min": 0,
            "max": 1,
            "sum": 3365,
            "count": 10032,
            "missing": 0,
            "mean": 0.33542663476874,
            "sumOfSquares": 3365,
            "stddev": 0.47216292752283
        }
    }
}

Get Statistics

The Get Statistics endpoint within Martini's Solr API focuses on generating detailed statistics for a single specified field within the document set. This targeted approach allows users to delve deeply into the characteristics of a particular field, offering insights that are crucial for data analysis and decision-making.

Endpoint Details

  • Method: GET
  • Path: /esbapi/v1/solr/<package>/<core>/stats/<stats-field>

Contrary to the "List Statistics" endpoint, "Get Statistics" concentrates on providing statistical data for only one field at a time, offering a more focused analysis.

Request

Path Parameters

The request must include the specific field for which statistics are to be generated, as indicated by the stats-field parameter.

Parameter Name Data Type Required Description
stats-field string true The document field for which statistics should be generated.

Query Parameters

In addition to the path parameter, the request can include query parameters to further customize the statistical output.

Parameter Name Data Type Required Description
stats.calcdistinct boolean false If set to true, calculates distinct count and values for the field. This operation can be resource-intensive and is disabled by default.

Example Request

Here's an example cURL request to this endpoint:

1
2
3
curl -X GET \
  'http://<host>:<port>/esbapi/v1/solr/<package>/invoke_monitor/stats/cost?q=*%3A*' \
  -H 'Authorization: Bearer <access-token>'

This request aims to generate statistics for the cost field across all documents in the specified core.

Response

Content Type

The API supports various response formats to accommodate different use cases:

  • application/json
  • application/xml
  • text/plain

Example Response

A sample JSON response providing statistics for the cost field might look as follows:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
{
    "name": "cost",
    "min": 321,
    "max": 59482,
    "sum": 984732,
    "count": 10032,
    "missing": 0,
    "mean": 3,
    "sumOfSquares": 3245,
    "stddev": 2
}

Range Faceting

The Range Faceting endpoint in Martini's Solr API offers a nuanced approach to data analysis by allowing users to perform faceted searches across specified ranges within date or numeric fields. This feature is particularly beneficial for breaking down data into manageable segments, such as time periods or price ranges.

Endpoint Details

  • Method: GET
  • Path: /esbapi/v1/solr/<package>/<core>/rangefacet/<facet-range>

Based on Solr's documentation, range faceting supports both date and numeric fields, enabling users to construct a series of range queries to explore data distributions within specified bounds.

Request

Path Parameters

The request must include the field on which to perform range faceting, as denoted by the facet-range parameter.

Parameter Name Data Type Required Description
facet_range string true The field to facet by range.

Query Parameters

To define the scope of the range faceting, several query parameters must be specified:

Parameter Name Data Type Required Description
facet.range.start date true The lower bound of the ranges.
facet.range.end date true The upper bound of the ranges.
facet.range.gap string true The span of each range, expressed in DateMathParser syntax for date fields.

Additional Solr parameters can be utilized to refine the faceting operation.

Example Request

Below is an example cURL request to the "Range Faceting" endpoint:

1
2
3
curl -X GET \
  'http://<host>:<port>/esbapi/v1/solr/<package>/invoke_monitor/rangefacet/timeReceived?facet.range.start=2020-01-01T00:00:00Z&facet.range.end=2020-01-02T00:00:00Z&facet.range.gap=%2B8HOUR&q=*%3A*' \
  -H 'Authorization: Bearer <access-token>'

This request seeks to perform range faceting on the timeReceived field, with 8-hour intervals starting from January 1, 2020.

Response

Content Type

The response to a range faceting query can be formatted as:

  • application/json
  • application/xml
  • text/plain

Example Response

A sample JSON response, illustrating the segmented counts for the timeReceived field, might look as follows:

 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
{
    "name": "timeReceived",
    "start": 1577836800000,
    "end": 1577923200000,
    "gap": "+8HOUR",
    "range_value": [
        "2020-01-01T00:00:00Z",
        "2020-01-01T08:00:00Z",
        "2020-01-01T16:00:00Z"
    ],
    "range_count": [
        19,
        19,
        24
    ],
    "counts": [
        {
            "value": "2020-01-01T00:00:00Z",
            "count": 19
        },
        {
            "value": "2020-01-01T08:00:00Z",
            "count": 19
        },
        {
            "value": "2020-01-01T16:00:00Z",
            "count": 24
        }
    ]
}

Pivot Faceting

Pivot faceting in Martini's Solr API is a sophisticated method for summarizing and analyzing data by creating a nested hierarchy of facet counts. It combines multiple fields into a hierarchical structure, enabling a deep dive into the data relationships and distributions.

Endpoint Details

  • Method: GET
  • Path: /esbapi/v1/solr/<package>/<core>/pivots

Solr documentation describes pivot faceting as a tool for sorting, counting, totaling, or averaging data stored in a table, with results typically displayed in a summarized table format. This feature allows for an intricate summary of results by pivoting documents by multiple fields.

Request

Query Parameters

To utilize pivot faceting, specific query parameters need to be defined, focusing on the fields to pivot.

Parameter Name Data Type Required Description
facet.pivot boolean true Specifies the fields for the pivot. Separate multiple fields with a comma to create nested pivots within the response.

Additional parameters can be employed to refine the request further, enhancing the pivot faceting operation.

Example Request

Here's an example cURL command to perform pivot faceting:

1
2
3
curl -X GET \
  'http://<host>:<port>/esbapi/v1/solr/<package>/invoke_monitor/pivots?facet.pivot=packageName%2CendpointName&q=*' \
  -H 'Authorization: Bearer <access-token>'

This request aims to pivot facet the data first by packageName and then by endpointName, applying to all documents as indicated by the query parameter q=*.

Response

Content Type

Responses can be formatted in various ways, depending on the specified content type:

  • application/json
  • application/xml
  • text/plain

Example Response

A sample JSON response illustrating the pivot faceting results might look as follows:

 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
{
    "facet_pivot": {
        "packageName,endpointName": {
            "field_name": "packageName,endpointName",
            "pivot": [
                {
                    "value": "Package_01",
                    "field": "packageName",
                    "pivot": [
                        {
                            "value": "Endpoint_03",
                            "field": "endpointName",
                            "count": 3205
                        },
                        {
                            "value": "Endpoint_02",
                            "field": "endpointName",
                            "count": 2304
                        }
                    ],
                    "count": 5509
                }
            ]
        }
    }
}