/api/tree

Trees are meta data used to organize time series in a hierarchical 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

  1. http://localhost:4242/api/tree

Example Response

  1. [
  2. {
  3. "name": "Test Tree",
  4. "description": "My Description",
  5. "notes": "Details",
  6. "rules": {
  7. "0": {
  8. "0": {
  9. "type": "TAGK",
  10. "field": "host",
  11. "regex": "",
  12. "separator": "",
  13. "description": "Hostname rule",
  14. "notes": "",
  15. "level": 0,
  16. "order": 0,
  17. "treeId": 1,
  18. "customField": "",
  19. "regexGroupIdx": 0,
  20. "displayFormat": ""
  21. }
  22. },
  23. "1": {
  24. "0": {
  25. "type": "METRIC",
  26. "field": "",
  27. "regex": "",
  28. "separator": "",
  29. "description": "",
  30. "notes": "Metric rule",
  31. "level": 1,
  32. "order": 0,
  33. "treeId": 1,
  34. "customField": "",
  35. "regexGroupIdx": 0,
  36. "displayFormat": ""
  37. }
  38. }
  39. },
  40. "created": 1356998400,
  41. "treeId": 1,
  42. "strictMatch": false,
  43. "storeFailures": false,
  44. "enabled": true
  45. },
  46. {
  47. "name": "2nd Tree",
  48. "description": "Other Tree",
  49. "notes": "",
  50. "rules": {
  51. "0": {
  52. "0": {
  53. "type": "TAGK",
  54. "field": "host",
  55. "regex": "",
  56. "separator": "",
  57. "description": "",
  58. "notes": "",
  59. "level": 0,
  60. "order": 0,
  61. "treeId": 2,
  62. "customField": "",
  63. "regexGroupIdx": 0,
  64. "displayFormat": ""
  65. }
  66. },
  67. "1": {
  68. "0": {
  69. "type": "METRIC",
  70. "field": "",
  71. "regex": "",
  72. "separator": "",
  73. "description": "",
  74. "notes": "",
  75. "level": 1,
  76. "order": 0,
  77. "treeId": 2,
  78. "customField": "",
  79. "regexGroupIdx": 0,
  80. "displayFormat": ""
  81. }
  82. }
  83. },
  84. "created": 1368964815,
  85. "treeId": 2,
  86. "strictMatch": false,
  87. "storeFailures": false,
  88. "enabled": false
  89. }
  90. ]

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

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

Example Response

  1. {
  2. "name": "2nd Tree",
  3. "description": "Other Tree",
  4. "notes": "",
  5. "rules": {
  6. "0": {
  7. "0": {
  8. "type": "TAGK",
  9. "field": "host",
  10. "regex": "",
  11. "separator": "",
  12. "description": "",
  13. "notes": "",
  14. "level": 0,
  15. "order": 0,
  16. "treeId": 2,
  17. "customField": "",
  18. "regexGroupIdx": 0,
  19. "displayFormat": ""
  20. }
  21. },
  22. "1": {
  23. "0": {
  24. "type": "METRIC",
  25. "field": "",
  26. "regex": "",
  27. "separator": "",
  28. "description": "",
  29. "notes": "",
  30. "level": 1,
  31. "order": 0,
  32. "treeId": 2,
  33. "customField": "",
  34. "regexGroupIdx": 0,
  35. "displayFormat": ""
  36. }
  37. }
  38. },
  39. "created": 1368964815,
  40. "treeId": 2,
  41. "strictMatch": false,
  42. "storeFailures": false,
  43. "enabled": false
  44. }

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

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

Example Response

  1. {
  2. "name": "Network",
  3. "description": "",
  4. "notes": "",
  5. "rules": null,
  6. "created": 1368964815,
  7. "treeId": 3,
  8. "strictMatch": false,
  9. "storeFailures": false,
  10. "enabled": false
  11. }

Example POST Edit Request

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

Example Response

  1. {
  2. "name": "Network",
  3. "description": "Network Device Information",
  4. "notes": "",
  5. "rules": null,
  6. "created": 1368964815,
  7. "treeId": 3,
  8. "strictMatch": false,
  9. "storeFailures": false,
  10. "enabled": false
  11. }

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

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