Navigation

  • index
  • next |
  • previous |
  • OpenTSDB 2.4 documentation »
  • HTTP API »
  • /api/search

Table of Contents

  • /api/search
    • Search API Endpoints
    • Verbs
    • Requests
      • Example Request
    • Response
    • TSMETA Response
    • TSMETA_SUMMARY Response
    • TSUIDS Response
    • UIDMETA Response
    • Annotation Response

Previous topic

/api/query/last

Next topic

/api/serializers

Quick 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

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
}

Navigation

  • index
  • next |
  • previous |
  • OpenTSDB 2.4 documentation »
  • HTTP API »
  • /api/search
© Copyright 2023, OpenTSDB. Created using Sphinx. Theme by vkvn