/api/search/lookup

Note

Available in 2.1

Lookup queries use either the meta data table or the main data table to determine what time series are associated with a given metric, tag name, tag value, tag pair or combination thereof. For example, if you want to know what metrics are available for a tag pair host=web01 you can execute a lookup to find out. Lookups do not require a search plugin to be installed.

Note

Lookups are performed against the tsdb-meta table. You must enable real-time meta data creation or perform a metasync using the uid command in order to retreive data from a lookup. Lookups can be executed against the raw data table using the CLI command only: search

Verbs

  • GET
  • POST

Requests

Parameters used by the lookup endpoint include:

Name Data Type Required Description Default QS RW Example
query String Required A lookup query as defined below.   m   tsd.hbase.rpcs{type=*}
useMeta Boolean Optional Whether or not to use the meta data table or the raw data table. The raw table will be much slower. true use_meta   false
limit Integer Optional The maximum number of items returned in the result set. 25     100
startIndex Integer Optional Ignored for lookup queries, always the default. 0     10

Lookup Queries

A lookup query consists of at least one metric, tag name (tagk) or tag value (tagv). Each value must be a literal name in the UID table. If a given name cannot be resolved to a UID, an exception will be returned. Only one metric can be supplied per query but multiple tagk, tagv or tag pairs may be provided.

Normally, tags a provided in the format <tagk>=<tagv> and a value is required on either side of the equals sign. However for lookups, one value may an asterisk *, i.e. <tagk>=* or *=<tagv>. In these cases, the asterisk acts as a wildcard meaning any time series with the given tagk or tagv will be returned. For example, if we issue a query for host=* then we will get all of the time series with a host tagk such as host=web01 and host=web02.

For complex queries with multiple values, each type is AND'd with the other types and OR'd with its own type.

<metric> AND (<tagk1>=[<tagv1>] OR <tagk1>=[<tagv2>]) AND ([<tagk2>]=<tagv3> OR [<tagk2>]=<tagv4>)

For example, the query tsd.hbase.rpcs{type=*,host=tsd1,host=tsd2,host=tsd3} would return only the time series with the metric tsd.hbase.rpcs and the type tagk with any value and a host tag with either tsd1 or tsd2 or tsd3. Unlike a data query, you may supply multiple tagks with the same name as seen in the example above. Wildcards always take priority so if your query looked like tsd.hbase.rpcs{type=*,host=tsd1,host=tsd2,host=*}, then the query would effectively be treated as tsd.hbase.rpcs{type=*,host=*}.

To retreive a list of all time series with a specific tag value, e.g. a particular host, you could issue a query like {*=web01} that will return all time series with a tag value of web01. This can be useful in debugging tag name issues such as some series having host=web01 or server=web01.

Example Request

Query String:

http://localhost:4242/api/search/lookup?m=tsd.hbase.rpcs{type=*}

POST:

JSON requests follow the search query format on the /api/search page. Limits and startNote that tags are supplied as a list of objects. The value for the key should be a tagk and the value for value should be a tagv or wildcard.

{
    "metric": "tsd.hbase.rpcs",
    "tags":[
        {
            "key": "type",
            "value": "*"
        }
    ]
}

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. LOOKUP
query String Ignored for lookup queries.  
limit Integer The maximum number of items returned in the result set. 25
startIndex Integer Ignored for lookup queries, always the default. 0
metric String The metric used for the lookup *
tags Array The list of tag pairs used for the lookup. 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 with the TSUID, metric and tags for each series. 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 a failure to resolve a metric or tag name to a UID, an exception will be returned.

Example Response

{
    "type": "LOOKUP",
    "metric": "tsd.hbase.rpcs",
    "tags":[
        {
            "key": "type",
            "value": "*"
        }
    ]
    "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
}