/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

Verbs

  • GET
  • POST

Requests

Parameters used by the search endpoint include:

Name Data Type Required Description Default QS RW 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
}

© 2010–2016 The OpenTSDB Authors
Licensed under the GNU LGPLv2.1+ and GPLv3+ licenses.
http://opentsdb.net/docs/build/html/api_http/search/index.html