Deprecated HTTP API

Version 1.0 of OpenTSDB included a rudimentary HTTP API that allowed for querying data, suggesting metric or tag names and a means of accessing static files. The 1.0 API has been carried over to 2.0 for backwards compatibility though most of the calls have been deprecated. Below is a list of the different endpoints and how to use them.

Warning

Version 3.0 may discard these deprecated methods so if you are developing tools against the HTTP API, make sure to use the 2.0 version.

If an endpoint is marked as (Deprecated) below, it should not be used for future development work.

Generalities

Most of the endpoints can return data in one or more of the following formats:

  • Plain Test - Or ASCII, the default for many requests will return a simple page of data with the Content-Type text/plain

  • HTML - If a request is bad or there was an exception, the response will often be in HTML, hard-coded and not using templates

  • JSON - Many calls can respond in a JSON format when the json query string parameter is appended

  • PNG - Some requests, including exceptions and errors, can generate an image file. In these cases, an error is sent to GnuPlot and the resulting empty graph with a title consisting of the message is returned. Append the parameter png to the query string.

The correct Content-Type is returned for each response, e.g. text/html; charset=UTF-8 for HTML, application/json for JSON and image/png for images.

Selecting a different output format is done with the png or json query string parameter. The value for the parameter is ignored. For example you can request http://localhost:4242/suggest?type=metrics&q=sys&json to return JSON data.

/

Requests the root which is the GWT generated OpenTSDB GUI. This endpoint only returns HTML and cannot return other data.

/aggregators (Deprecated)

Returns a list of available aggregation functions in JSON format only. Other formats are ignored. This method does not accept any query string parameters.

Example Request:

http://localhost:4242/aggregators

Example Response:

["min","sum","max","avg"]

/diediedie (Deprecated)

Accessing this endpoint causes the TSD to perform a graceful shutdown and exit. A graceful shutdown prevents data loss by flushing all the buffered edits to HBase before exiting. The endpoint does not return any data and does not accept any parameters.

/dropcaches (Deprecated)

Clears all internal caches such as the UID to name and name to UID maps. It should be used if you have renamed a metric, tagk or tagv.

/logs (Deprecated)

Returns the latest lines logged by the TSD internally, returning the most recent entries first. OpenTSDB uses LogBack and the src/logback.xml file must have a Cyclic Buffer appender configured for this endpoint to function. The XML configuration determines how many lines will be returned with each call. Output defaults to plain text with message components separated by tabs, or it can be returned as JSON with the proper query string.

This endpoint can also change the logging level of ______ at runtime. The query string parameter to use is level=<logging_level>. For example, you can call http://localhost:4242/logs?level=INFO to set the log level to INFO. Valid parameter values are (from the most verbose to the least): ALL TRACE DEBUG INFO WARN ERROR OFF (names are case insensitive). Note that this method does not change the logback.xml configuration file and restarting the TSD will reload from that file.

/q (Deprecated)

Queries the TSD for data.

/s

Serves static files, such as JavaScript generated by the GWT compiler or favicon.ico. The TSD needs a --staticroot or tsd.http.staticroot argument to start. This argument is the path to a directory that contains the files served by this end point.

When a request for GET /s/queryui.nocache.js comes in, for instance, the file ${staticroot}/queryui.nocache.js is sent to the browser.

Note: The TSD will allow clients to cache static files for 1 year by default, and will report the age of the file on disk. If the file name contains nocache, then the TSD will tell clients to not cache the file (this idiom is used by GWT).

/stats (Deprecated)

Returns statistics about the running TSD

/suggest (Deprecated)

Used for auto-complete calls to match metrics, tag names or tag values on the given string. Returns JSON data only.

Parameters:

  • type - The type of value to suggest. Must be either metrics for metrics, tagk for tag names or tagv for tag values.

  • q - The string to match on. The match is case-sensitive and only matches on the first characters of each type of data. For example, type=metrics&q=sys would only return the names of metrics that start with sys such as sys.cpu.0.system

  • max - An optional maximum number of results to return. The default is 25 and given values must be greater than 0.

Both parameters are required or you will receive an exception.

Example Request:

http://localhost:4242/suggest?type=metrics&q=df

Example Response:

[
  "df.1kblocks.free",
  "df.1kblocks.total",
  "df.1kblocks.used",
  "df.inodes.free",
  "df.inodes.total",
  "df.inodes.used"
]

/version (Deprecated)

Returns version information about the build of the running TSD. Can be returned in either the default of plain-text or JSON.