/api/search

/api/search

This endpoint provides a basic means of searching OpenTSDB meta data. Lookups can be performed against the tsdb-meta table when enabled. Optionally, a search plugin can be installed to send and retreive information from an external search indexing service such as Elastic Search. It is up to each search plugin to implement various parts of this endpoint and return data in a consistent format. The type of object searched and returned depends on the endpoint chosen.

Note

If the plugin is not configured or enabled, endpoints other than /api/search/lookup will return an exception.

Search API Endpoints

/api/search/lookup
/api/search/tsmeta - TSMETA Response
/api/search/tsmeta_summary - TSMETA_SUMMARY Response
/api/search/tsuids - TSUIDS Response
/api/search/uidmeta - UIDMETA Response
/api/search/annotation - Annotation Response

Verbs

GET
POST

Requests

Parameters used by the search endpoint include:

Name	Data Type	Required	Description	Default	QS	Example
query	String	Optional	The string based query to pass to the search engine. This will be parsed by the engine or plugin to perform the actual search. Allowable values depends on the plugin. Ignored for lookups.		query	name:sys.cpu.
limit	Integer	Optional	Limits the number of results returned per query so as not to override the TSD or search engine. Allowable values depends on the plugin. Ignored for lookups.	25	limit	100
startIndex	Integer	Optional	Used in combination with the `limit` value to page through results. Allowable values depends on the plugin. Ignored for lookups.	0	start_index	42
metric	String	Optional	The name of a metric or a wildcard for lookup queries		metric	tsd.hbase.rpcs
tags	Array	Optional	One or more key/value objects with tag names and/or tag values for lookup queries. See /api/search/lookup		tags	See /api/search/lookup

Example Request

Query String:

http://localhost:4242/api/search/tsmeta?query=name:*&limit=3&start_index=0

POST:

{
    "query": "name:*",
    "limit": 4,
    "startIndex": 5
}

Response

Depending on the endpoint called, the output will change slightly. However common fields include:

Name	Data Type	Description	Example
type	String	The type of query submitted, i.e. the endpoint called. Will be one of the endpoints listed above.	TSMETA
query	String	The query string submitted. May be altered by the plugin	name:sys.cpu.*
limit	Integer	The maximum number of items returned in the result set. Note that the actual number returned may be less than the limit.	25
startIndex	Integer	The starting index for the current result set as provided in the query	0
metric	String	The metric used for the lookup
tags	Array	The list of tag pairs used for lookup queries. May be an empty list.	[ ]
time	Integer	The amount of time it took, in milliseconds, to complete the query	120
totalResults	Integer	The total number of results matched by the query	1024
results	Array	The result set. The format depends on the endpoint requested.	See Below

This endpoint will almost always return a 200 with content body. If the query doesn’t match any results, the results field will be an empty array and totalResults will be 0. If an error occurs, such as the plugin being disabled or not configured, an exception will be returned.

TSMETA Response

The TSMeta endpoint returns a list of matching TSMeta objects.

{
    "type": "TSMETA",
    "query": "name:*",
    "metric": "*",
    "tags": [],
    "limit": 2,
    "time": 675,
    "results": [
        {
            "tsuid": "0000150000070010D0",
            "metric": {
                "uid": "000015",
                "type": "METRIC",
                "name": "app.apache.connections",
                "description": "",
                "notes": "",
                "created": 1362655264,
                "custom": null,
                "displayName": ""
            },
            "tags": [
                {
                    "uid": "000007",
                    "type": "TAGK",
                    "name": "fqdn",
                    "description": "",
                    "notes": "",
                    "created": 1362655264,
                    "custom": null,
                    "displayName": ""
                },
                {
                    "uid": "0010D0",
                    "type": "TAGV",
                    "name": "web01.mysite.com",
                    "description": "",
                    "notes": "",
                    "created": 1362720007,
                    "custom": null,
                    "displayName": ""
                }
            ],
            "description": "",
            "notes": "",
            "created": 1362740528,
            "units": "",
            "retention": 0,
            "max": 0,
            "min": 0,
            "displayName": "",
            "dataType": "",
            "lastReceived": 0,
            "totalDatapoints": 0
        },
        {
            "tsuid": "0000150000070010D5",
            "metric": {
                "uid": "000015",
                "type": "METRIC",
                "name": "app.apache.connections",
                "description": "",
                "notes": "",
                "created": 1362655264,
                "custom": null,
                "displayName": ""
            },
            "tags": [
                {
                    "uid": "000007",
                    "type": "TAGK",
                    "name": "fqdn",
                    "description": "",
                    "notes": "",
                    "created": 1362655264,
                    "custom": null,
                    "displayName": ""
                },
                {
                    "uid": "0010D5",
                    "type": "TAGV",
                    "name": "web02.mysite.com",
                    "description": "",
                    "notes": "",
                    "created": 1362720007,
                    "custom": null,
                    "displayName": ""
                }
            ],
            "description": "",
            "notes": "",
            "created": 1362882263,
            "units": "",
            "retention": 0,
            "max": 0,
            "min": 0,
            "displayName": "",
            "dataType": "",
            "lastReceived": 0,
            "totalDatapoints": 0
        }
    ],
    "startIndex": 0,
    "totalResults": 9688066
}

TSMETA_SUMMARY Response

The TSMeta Summary endpoint returns just the basic information associated with a timeseries including the TSUID, the metric name and tags. The search is run against the same index as the TSMeta query but returns a subset of the data.

{
    "type": "TSMETA_SUMMARY",
    "query": "name:*",
    "metric": "*",
    "tags": [],
    "limit": 3,
    "time": 565,
    "results": [
        {
            "tags": {
                "fqdn": "web01.mysite.com"
            },
            "metric": "app.apache.connections",
            "tsuid": "0000150000070010D0"
        },
        {
            "tags": {
                "fqdn": "web02.mysite.com"
            },
            "metric": "app.apache.connections",
            "tsuid": "0000150000070010D5"
        },
        {
            "tags": {
                "fqdn": "web03.mysite.com"
            },
            "metric": "app.apache.connections",
            "tsuid": "0000150000070010D6"
        }
    ],
    "startIndex": 0,
    "totalResults": 9688066
}

TSUIDS Response

The TSUIDs endpoint returns a list of TSUIDS that match the query. The search is run against the same index as the TSMeta query but returns a subset of the data.

{
    "type": "TSUIDS",
    "query": "name:*",
    "metric": "*",
    "tags": [],
    "limit": 3,
    "time": 517,
    "results": [
        "0000150000070010D0",
        "0000150000070010D5",
        "0000150000070010D6"
    ],
    "startIndex": 0,
    "totalResults": 9688066
}

UIDMETA Response

The UIDMeta endpoint returns a list of UIDMeta objects that match the query.

{
    "type": "UIDMETA",
    "query": "name:*",
    "metric": "*",
    "tags": [],
    "limit": 3,
    "time": 517,
    "results": [
        {
            "uid": "000007",
            "type": "TAGK",
            "name": "fqdn",
            "description": "",
            "notes": "",
            "created": 1362655264,
            "custom": null,
            "displayName": ""
        },
        {
            "uid": "0010D0",
            "type": "TAGV",
            "name": "web01.mysite.com",
            "description": "",
            "notes": "",
            "created": 1362720007,
            "custom": null,
            "displayName": ""
        },
        {
            "uid": "0010D5",
            "type": "TAGV",
            "name": "web02.mysite.com",
            "description": "",
            "notes": "",
            "created": 1362720007,
            "custom": null,
            "displayName": ""
        }
    ],
    "startIndex": 0,
    "totalResults": 9688066
}

Annotation Response

The Annotation endpoint returns a list of Annotation objects that match the query.

{
    "type": "ANNOTATION",
    "query": "description:*",
    "metric": "*",
    "tags": [],
    "limit": 25,
    "time": 80,
    "results": [
        {
            "tsuid": "000001000001000001",
            "description": "Testing Annotations",
            "notes": "These would be details about the event, the description is just a summary",
            "custom": {
                "owner": "jdoe",
                "dept": "ops"
            },
            "endTime": 0,
            "startTime": 1369141261
        }
    ],
    "startIndex": 0,
    "totalResults": 1
}