/api/tree

Trees are meta data used to organize time series in a heirarchical structure for browsing similar to a typical file system. A number of endpoints under the /tree root allow working with various tree related data:

Tree API Endpoints

The /tree endpoint allows for creating or modifying a tree definition. Tree definitions include configuration and meta data accessible via this endpoint, as well as the rule set accessiable via /tree/rule or /tree/rules.

Note

When creating a tree it will have the enabled field set to false by default. After creating a tree you should add rules then use the tree/test endpoint with a few TSUIDs to make sure the resulting tree will be what you expected. After you have verified the results, you can set the enabled field to true and new TSMeta objects or a tree synchronization will start to populate branches.

Verbs

GET - Retrieve one or more tree definitions
POST - Edit tree fields
PUT - Replace tree fields
DELETE - Delete the results of a tree and/or the tree definition

Requests

The following fields can be used for all tree endpoint requests:

Name	Data Type	Required	Description	Default	QS	RW	Example
treeId	Integer	Required*	Used to fetch or modify a specific tree. *When creating a new tree, the `tree` value must not be present.		treeid	RO	1
name	String	Required*	A brief, descriptive name for the tree. *Required only when creating a tree.		name	RW	Network Infrastructure
description	String	Optional	A longer description of what the tree contains		description	RW	Tree containing all network gear
notes	String	Optional	Detailed notes about the tree		notes	RW
strictMatch	Boolean	Optional	Whether or not timeseries should be included in the tree if they fail to match one or more rule levels.	false	strict_match	RW	true
enabled	Boolean	Optional	Whether or not TSMeta should be processed through the tree. By default this is set to `false` so that you can setup rules and test some objects before building branches.	false	enabled	RW	true
storeFailures	Boolean	Optional	Whether or not collisions and 'not matched' TSUIDs should be recorded. This can create very wide rows.	false	store_failures	RW	true
definition	Boolean	Optional	Used only when `DELETE` ing a tree, if this flag is set to true, then the entire tree definition will be deleted along with all branches, collisions and not matched entries	false	definition		true

Response

A successful response to a GET, POST or PUT request will return tree objects with optinally requested changes. Successful DELETE calls will return with a 204 status code and no body content. When modifying data, if no changes were present, i.e. the call did not provide any data to store, the resposne will be a 304 without any body content. If the requested tree did not exist in the system, a 404 will be returned with an error message. If invalid data was supplied an 400 error will be returned.

All Request fields will be present in the response in addition to others:

Name	Data Type	Description	Example
rules	Map	A map or dictionary with rules defined for the tree organized by `level` and `order`. If no rules have been defined yet, the value will be `null`	See Examples
created	Integer	A Unix Epoch timestamp in seconds when the tree was originally created.	1350425579

GET

A GET request to /api/tree without a tree ID will return a list of all of the trees configured in the system. The results will include configured rules for each tree. If no trees have been configured yet, the list will be empty.

Example GET All Trees Query

http://localhost:4242/api/tree

Example Response

[
  {
    "name": "Test Tree",
    "description": "My Description",
    "notes": "Details",
    "rules": {
      "0": {
        "0": {
          "type": "TAGK",
          "field": "host",
          "regex": "",
          "separator": "",
          "description": "Hostname rule",
          "notes": "",
          "level": 0,
          "order": 0,
          "treeId": 1,
          "customField": "",
          "regexGroupIdx": 0,
          "displayFormat": ""
        }
      },
      "1": {
        "0": {
          "type": "METRIC",
          "field": "",
          "regex": "",
          "separator": "",
          "description": "",
          "notes": "Metric rule",
          "level": 1,
          "order": 0,
          "treeId": 1,
          "customField": "",
          "regexGroupIdx": 0,
          "displayFormat": ""
        }
      }
    },
    "created": 1356998400,
    "treeId": 1,
    "strictMatch": false,
    "storeFailures": false,
    "enabled": true
  },
  {
    "name": "2nd Tree",
    "description": "Other Tree",
    "notes": "",
    "rules": {
      "0": {
        "0": {
          "type": "TAGK",
          "field": "host",
          "regex": "",
          "separator": "",
          "description": "",
          "notes": "",
          "level": 0,
          "order": 0,
          "treeId": 2,
          "customField": "",
          "regexGroupIdx": 0,
          "displayFormat": ""
        }
      },
      "1": {
        "0": {
          "type": "METRIC",
          "field": "",
          "regex": "",
          "separator": "",
          "description": "",
          "notes": "",
          "level": 1,
          "order": 0,
          "treeId": 2,
          "customField": "",
          "regexGroupIdx": 0,
          "displayFormat": ""
        }
      }
    },
    "created": 1368964815,
    "treeId": 2,
    "strictMatch": false,
    "storeFailures": false,
    "enabled": false
  }
]

To fetch a specific tree, supply a ``treeId' value. The response will include the tree object if found. If the requested tree does not exist, a 404 exception will be returned.

Example GET Single Tree

http://localhost:4242/api/treeId?tree=1

Example Response

{
  "name": "2nd Tree",
  "description": "Other Tree",
  "notes": "",
  "rules": {
    "0": {
      "0": {
        "type": "TAGK",
        "field": "host",
        "regex": "",
        "separator": "",
        "description": "",
        "notes": "",
        "level": 0,
        "order": 0,
        "treeId": 2,
        "customField": "",
        "regexGroupIdx": 0,
        "displayFormat": ""
      }
    },
    "1": {
      "0": {
        "type": "METRIC",
        "field": "",
        "regex": "",
        "separator": "",
        "description": "",
        "notes": "",
        "level": 1,
        "order": 0,
        "treeId": 2,
        "customField": "",
        "regexGroupIdx": 0,
        "displayFormat": ""
      }
    }
  },
  "created": 1368964815,
  "treeId": 2,
  "strictMatch": false,
  "storeFailures": false,
  "enabled": false
}

POST/PUT

Using the POST or PUT methods, you can create a new tree or edit most of the fields for an existing tree. New trees require a name value and for the treeId' value to be empty. Existing trees require a valid ``treeId ID and any fields that require modification. A successful request will return the modified tree object.

Note

A new tree will not have any rules. Your next call should probably be to /tree/rule or /tree/rules.

Example POST Create Request

http://localhost:4242/api/tree?name=Network%20Tree&method_override=post

Example Response

{
  "name": "Network",
  "description": "",
  "notes": "",
  "rules": null,
  "created": 1368964815,
  "treeId": 3,
  "strictMatch": false,
  "storeFailures": false,
  "enabled": false
}

Example POST Edit Request

http://localhost:4242/api/tree?treeId=3&description=Network%20Device%20Information&method_override=post

Example Response

{
  "name": "Network",
  "description": "Network Device Information",
  "notes": "",
  "rules": null,
  "created": 1368964815,
  "treeId": 3,
  "strictMatch": false,
  "storeFailures": false,
  "enabled": false
}

DELETE

Using the DELETE method will remove only collisions, not matched entries and branches for the given tree from storage. This endpoint starts a delete. Because the delete can take some time, the endpoint will return a successful 204 response without data if the delete completed. If the tree was not found, it will return a 404. If you want to delete the tree definition itself, you can supply the defintion flag in the query string with a value of true and the tree and rule definitions will be removed as well.

Warning

This method cannot be undone. Once executed, the purge will continue running unless the TSD is shutdown.

Note

Before executing a DELETE query, you should make sure that a manual tree syncronization is not running somehwere on your data. If it is, there may be some orphaned branches or leaves stored during the purge. Use the _____ CLi tool sometime after the delete to cleanup left over branches or leaves.

Example DELETE Request

http://localhost:4242/api/tree?tree=1&method_override=delete

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