/api/tree/branch

A branch represents a level in the tree heirarchy and contains information about child branches and/or leaves. Branches are immutable from an API perspective and can only be created or modified by processing a TSMeta through tree rules via a CLI command or when a new timeseries is encountered or a TSMeta object modified. Therefore the branch endpoint only supports the GET verb.

A branch is identified by a branchId, a hexadecimal encoded string that represents the ID of the tree it belongs to as well as the IDs of each parent the branch stems from. All branches stem from the ROOT branch of a tree and this is usually the starting place when browsing. To fetch the ROOT just call this endpoingt with a valid treeId. The root branch ID is also a 4 character encoding of the tree ID.

Verbs

  • GET

Requests

The following fields can be used to request a branch. Only one or the other may be used.

Name Data Type Required Description Default QS RW Example
treeId Integer Optional Used to fetch the root branch of the tree. If used in combination with a branchId, the tree ID will be ignored. treeid RO 1
branch String Required A hexadecimal representation of the branch ID, required for all but the root branch request branch RO 000183A21C8F

Response

A successful response to a request will return the branch object using the requested serializer. If the requested tree or branch did not exist in the system, a 404 will be returned with an error message.

Fields returned with the response include:

Name Data Type Description Example
treeId Integer The ID of the tree the branch belongs to 1
displayName String Name of the branch as determined by the rule set sys
branchId String Hexadecimal encoded ID of the branch 00010001BECD
depth Integer Depth of the branch within the tree, starting at 0 for the root branch 1
path Map List of parent branch names and their depth. See Below
branches Array An array of child branch objects. May be null. See Below
leaves Array An array of child leaf objects. May be null. See Leaves Below

Leaves

If a branch contains child leaves, i.e. timeseries stored in OpenTSDB, their metric, tags, TSUID and display name will be contained in the results. Leaf fields are as follows:

Name Data Type Description Example
metric String The name of the metric for the timeseries sys.cpu.0
tags Map A list of tag names and values representing the timeseries See Below
tsuid String Hexadecimal encoded timeseries ID 000001000001000001
displayName String A name as parsed by the rule set user

GET

Example Root GET Query

http://localhost:4242/api/tree/branch?treeid=1

Example Response

{
  "leaves": null,
  "branches": [
    {
      "leaves": null,
      "branches": null,
      "path": {
        "0": "ROOT",
        "1": "sys"
      },
      "treeId": 1,
      "displayName": "sys",
      "branchId": "00010001BECD",
      "depth": 1
    }
  ],
  "path": {
    "0": "ROOT"
  },
  "treeId": 1,
  "displayName": "ROOT",
  "branchId": "0001",
  "depth": 0
}

Example Branch GET Query

http://localhost:4242/api/tree/branch?branchid=00010001BECD000181A8

Example Response

{
  "leaves": [
    {
      "metric": "sys.cpu.0.user",
      "tags": {
        "host": "web01"
      },
      "tsuid": "000001000001000001",
      "displayName": "user"
    }
  ],
  "branches": [
    {
      "leaves": null,
      "branches": null,
      "path": {
        "0": "ROOT",
        "1": "sys",
        "2": "cpu",
        "3": "mboard"
      },
      "treeId": 1,
      "displayName": "mboard",
      "branchId": "00010001BECD000181A8BF992A99",
      "depth": 3
    }
  ],
  "path": {
    "0": "ROOT",
    "1": "sys",
    "2": "cpu"
  },
  "treeId": 1,
  "displayName": "cpu",
  "branchId": "00010001BECD000181A8",
  "depth": 2
}

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