diff --git a/docs/querying/api.md b/docs/querying/api.md index 3069cc9ce..34fc823cb 100644 --- a/docs/querying/api.md +++ b/docs/querying/api.md @@ -381,3 +381,87 @@ $ curl http://localhost:9090/api/v1/alertmanagers } } ``` + + +## TSDB Admin APIs +In 2.0, there are new APIs that expose database functionalities for the advanced user. These APIs are not enabled unless the `--web.enable-admin-api` is set. All the APIs below are experimental and might change in the future. + +We also expose a gRPC API whose definition can be found [here](https://github.com/prometheus/prometheus/blob/master/prompb/rpc.proto). + +### Snapshot +Snapshot creates a snapshot of all current data into `snapshots/-` under the TSDB's data directory and returns the directory as response. + +``` +POST /api/v2/admin/tsdb/snapshot +``` + +```json +$ curl -XPOST http://localhost:9090/api/v2/admin/tsdb/snapshot +{ + "name": "2017-11-30T15:31:59Z-2366f0a55106d6e1" +} +``` + +The snapshot now exists at `/snapshots/2017-11-30T15:31:59Z-2366f0a55106d6e1` + + +### Delete Series +DeleteSeries deletes data for a selection of series in a time range. The actual data still exists on disk and is cleaned up in future compactions or can be explicitly cleaned up by hitting the Clean Tombstones endpoint. + +``` +POST /api/v2/admin/tsdb/delete_series +``` + +Parameters (body): + +```json +{ + "min_time": "date-time(iso-8601)" // optional, defaults to minmum-time. + "max_time": "date-time(iso-8601)" // optional, defaults to maximum-time + "matchers": [LabelMatcher] +} +``` + +```json +LabelMatchers: Matcher specifies a rule, which can match or set of labels or not. + +{ + "type": "string", // One of: EQ, NEQ, RE, NRE defaults to EQ. + "name": "label-name", + "value": "label-value" +} +``` + +Example: + +```json +$ curl -X POST \ + http://localhost:9090/api/v2/admin/tsdb/delete_series \ + -H 'content-type: application/json' \ + -d '{ + "max_time": "'2017-11-30T20:18:30+05:30", + "matchers": [{ + "type": "EQ", + "name": "__name__", + "value": "up" + }] + }' + +{} +``` + + + +### Clean Tombstones +CleanTombstones removes the deleted data from disk and cleans up the existing tombstones. This can be used after deleting series to free up space. + +``` +POST /api/v2/admin/tsdb/clean_tombstones +``` + +This takes no parameters or body. + +```json +$ curl -XPOST http://localhost:9090/api/v2/admin/tsdb/clean_tombstones +{} +``` \ No newline at end of file