Metrics

Metrics scheme

Each metric is identified by its fields id, label and graph which are all unique. label field is used for further routing, while graph field is the URL of the graph representing the metric.

Scheme:

{
  "id": "UUID",
  "label": "String",
  "graph": "String"
}

Example metric:

{
  "data": {
    "label": "staging.staging.collectd.cpu-0.cpu-idle",
    "id": "9158ae7a-8d62-45a1-a1de-2a02869cf5ef",
    "graph": "https://graphite.facts4.work/render?format=json&target=staging.staging.collectd.cpu-0.cpu-idle"
  }
}

GET methods

GET /api/v1/metrics

Returns all the metrics with their relative information if at least one resource exists, otherwise returns an empty collection.

Example request:

GET /api/v1/metrics HTTP/1.1
Host: https://ccharts.hir.facts4.work/

Example response:

HTTP/1.1 200 OK
Content-type: application/json

{
  "data": [
    {
      "label": "carbon.agents.68e0f9b1a5d2-a.avgUpdateTime",
      "id": "db496d3d-c329-40af-b484-733c8b13c027",
      "graph": "https://graphite.facts4.work/render?format=json&target=carbon.agents.68e0f9b1a5d2-a.avgUpdateTime"
    },
    {
      "label": "carbon.agents.68e0f9b1a5d2-a.blacklistMatches",
      "id": "ce557ddc-0b00-43d2-a53e-f26572fc9327",
      "graph": "https://graphite.facts4.work/render?format=json&target=carbon.agents.68e0f9b1a5d2-a.blacklistMatches"
    },
    {
      "label": "carbon.agents.68e0f9b1a5d2-a.cache.bulk_queries",
      "id": "ae19a9b9-a0d0-4509-9a65-36a7a714d3fc",
      "graph": "https://graphite.facts4.work/render?format=json&target=carbon.agents.68e0f9b1a5d2-a.cache.bulk_queries"
    },
    {
      "label": "carbon.agents.68e0f9b1a5d2-a.cache.overflow",
      "id": "8a9dc890-1603-4a75-b9cd-a5801a297dde",
      "graph": "https://graphite.facts4.work/render?format=json&target=carbon.agents.68e0f9b1a5d2-a.cache.overflow"
    }
  ]
}
Query Parameters:
 
  • access_token (string) – valid access token for OAuth2 authentication
  • page (string) – page requested
  • per_page (string) – number of metrics per page
Response JSON Array of Objects:
 
  • id (string) – id of the metric
  • label (string) – unique label of the metric used for routing
  • graph (string) – URL of the graph representing the metric
Status Codes:
GET /api/v1/metrics/:label

Returns a specific metric with :label and the rest of its parameters if it exists, otherwise returns 404 error.

Example request:

GET /api/v1/metrics/carbon.agents.68e0f9b1a5d2-a.cache.overflow HTTP/1.1
Host: https://ccharts.hir.facts4.work/

Example response:

HTTP/1.1 200 OK
Content-type: application/json

{
  "data": {
    "label": "carbon.agents.68e0f9b1a5d2-a.cache.overflow",
    "id": "8a9dc890-1603-4a75-b9cd-a5801a297dde",
    "graph": "https://graphite.facts4.work/render?format=json&target=carbon.agents.68e0f9b1a5d2-a.cache.overflow"
  }
}
Parameters:
  • label (string) – metric’s unique label
Query Parameters:
 
  • access_token (string) – valid access token for OAuth2 authentication
Response JSON Array of Objects:
 
  • id (string) – id of the metric
  • label (string) – unique label of the metric used for routing
  • graph (string) – URL of the graph representing the metric
Status Codes:

METRICS REFRESH methods

POST /api/v1/metrics/refresh

Refreshes the list of metric by taking an updated list from the graphite server. Please note that this is the correct way to update the metrics and the POST and PUT methods should not be used.

Example request:

POST /api/v1/metrics/refresh HTTP/1.1
Host: https://ccharts.hir.facts4.work/

Example response:

HTTP/1.1 200 OK
Content-type: application/json

{
  "metric_refresh": "Updated all the metrics"
}
Query Parameters:
 
  • access_token (string) – valid access token for OAuth2 authentication
Status Codes:

POST methods

POST /api/v1/metrics

Adds a new metric with its label. id and graph are generated server-side. Returns the newly created resource or error message if the request was not valid.

NOTE: Please do not use this method unless necessary. All the metrics are stored on an external time-series server, and labels must match between them. The correct way to update the metrics is by using the METRICS REFRESH method.

Example request:

POST /api/v1/metrics HTTP/1.1
Host: https://ccharts.hir.facts4.work/
Content-Type: application/json

{
  "metric": {
    "label": "staging.staging.collectd.cpu-0.cpu-idle"
  }
}

Example response:

HTTP/1.1 201 Created
Content-type: application/json

{
  "data": {
    "label": "staging.staging.collectd.cpu-0.cpu-idle",
    "id": "9158ae7a-8d62-45a1-a1de-2a02869cf5ef",
    "graph": "https://graphite.facts4.work/render?format=json&target=staging.staging.collectd.cpu-0.cpu-idle"
  }
}
Query Parameters:
 
  • access_token (string) – valid access token for OAuth2 authentication
Request JSON Array of Objects:
 
  • label (string) – unique label of the metric used for routing
Response JSON Array of Objects:
 
  • id (string) – id of the metric
  • label (string) – unique label of the metric used for routing
  • graph (string) – URL of the graph representing the metric
Status Codes:

PUT methods

PUT /api/v1/metrics/:label

Updates an existing metric with new information. Returns the updated resource or an error message.

NOTE: Please do not use this method unless necessary. All the metrics are stored on an external time-series server, and labels must match between them. The correct way to update the metrics is by using the METRICS REFRESH method.

Note: All parameters must be defined with the PUT request, ie. PUT request replaces the existing resource with the modified one if it exists, or creates a new one.

Example request:

PUT /api/v1/metrics/staging.staging.collectd.cpu-0.cpu-idle HTTP/1.1
Host: https://ccharts.hir.facts4.work/
Content-Type: application/json

{
  "metric": {
    "label": "updated.label"
  }
}

Example response:

HTTP/1.1 200 OK
Content-type: application/json

{
  "data": {
    "label": "updated.label",
    "id": "9158ae7a-8d62-45a1-a1de-2a02869cf5ef",
    "graph": "https://graphite.facts4.work/render?format=json&target=updated.label"
  }
}
Parameters:
  • label (string) – metric’s unique label
Query Parameters:
 
  • access_token (string) – valid access token for OAuth2 authentication
Request JSON Array of Objects:
 
  • label (string) – unique label of the metric used for routing
Response JSON Array of Objects:
 
  • id (string) – id of the metric
  • label (string) – unique label of the metric used for routing
  • graph (string) – URL of the graph representing the metric
Status Codes:

DELETE methods

DELETE /api/v1/metrics/:label

Delete an existing metric, responds with the confirmation or error. Can only delete one resource at a time, to remove a collection of machines call the DELETE method for each element.

Example request:

DELETE /api/v1/metrics/staging.staging.collectd.cpu-0.cpu-idle HTTP/1.1
Host: https://ccharts.hir.facts4.work/

Example response:

HTTP/1.1 200 OK
Parameters:
  • label (string) – metric’s unique label
Query Parameters:
 
  • access_token (string) – valid access token for OAuth2 authentication
Status Codes: