Charts

Charts scheme

Each chart is identified by its fields unique id and is associated with a specific metric identified by metric_id. Other description fields include the chart’s label and its type.

The field that are needed for calibration and for the generation of the chart_url are: chart_from, chart_until and limits. Chart is calibrated in the interval of time specified and the calculated limits are saved in the limits json object. Additional acceptable fields for limits are specification_lcl and specification_ucl that represent lower and upper specification control limit that should be respected.

The chart can be calibrated or not and this is visible in its calibrated field. This value is update automatically once the chart_from and chart_until are provided and limits are calculated.

Scheme:

{
  "id": "UUID",
  "metric_id": "UUID",
  "label": "String",
  "type": "String",
  "chart_from": "AbsoluteTime",
  "chart_until": "AbsoluteTime",
  "chart_url": "String",
  "calibrated": "Boolean",
  "limits": "JSON"
}

Example chart:

{
  "type": "individual control limits",
  "metric_id": "9158ae7a-8d62-45a1-a1de-2a02869cf5ef",
  "limits": {
    "ucl": 98.34637729009803,
    "specification_ucl": 100,
    "specification_lcl": 90,
    "mean": 94.02113490833334,
    "lcl": 89.69589252656864
  },
  "label": "Individual Chart",
  "id": "c55ba185-d51e-41a0-bbcc-8aef7db46a63",
  "chart_url": "https://graphite.facts4.work/render?format=json&title=%22individual+control+limits+control+chart+-+Individual+Chart%22&target=alias(staging.staging.collectd.cpu-0.cpu-idle,%20%22X%22)&target=alias(constantLine(98.34637729009803),%20%22UCL%22)&target=alias(constantLine(89.69589252656864),%20%22LCL%22)&target=alias(constantLine(94.02113490833334),%20%22mean%22)",
  "chart_until": "10:00_20160513",
  "chart_from": "08:00_20160513",
  "calibrated": true
}

FIELD TYPES

Certain field types need to have specific values in order for the control chart limits to be usable.

Chart type

Based on the chart type field different methods will be called for the calculation of the control limits, and different rendering URL will be produced. Currently supported chart types are:

  • “individual control limits”
  • “individual moving range”

Chart from and until

The calibration of the chart is done in a precise interval defined by the chart_from and chart_until. These field have to follow specific formatting. The time is represented as absolute time in the format HH:MM_YYMMDD. Any other time format will not pass the calibration step.

Additional control is done to assure that the chart_from field is effectively before chart_until, and the calibration step will fail if bad time intervals are passed.

When chart_until is greater than now, the current time will be used instead.

Chart limits

Currently limits field can be updated with the specification control limits. The accepted subfields are:

{
  "limits": {
    "lcl": "Float",
    "specification_ucl": "Float",
    "specification_lcl": "Float",
    "mean": "Float",
    "lcl": "Float"
  }
}

When passing new specification limits with a PUT request, already calculated lcl, ucl and mean limits should be passed as they are, since the whole field gets updated. For the calculation of the control limits, use the from and until fields.

Chart Calibration

Charts are calibrated in specific time interval, and in order to recalibrate a chart a PUT request is done with the new value of chart_from and/or chart_until fields. If the request is valid, the calibration step is done and the chart is updated with new control limits.

GET methods

GET /api/v1/charts

Returns all the charts with their id and label fields.

Example request:

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

Example response:

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

{
    "data": [
        {
            "label": "t1",
            "id": "163a7f54-55d8-4eba-bac5-6731d7f0a573",
            "calibrated": false
        },
        {
            "label": "t2",
            "id": "b9d6fd2c-8d36-4c3c-b491-c18965523ae9",
            "calibrated": true
        },
        {
            "label": "one",
            "id": "d2b7df78-8224-43ed-9d9a-fd35b5ad9ec9",
            "calibrated": false
        },
        {
            "label": "two",
            "id": "43ac8a94-46e0-4523-91a1-1e1f216ba0c4",
            "calibrated": false
        },
        {
            "label": "two",
            "id": "61455b8c-6a74-4ef3-86a6-b17c18616c9a",
            "calibrated": false
        },
        {
            "label": "three",
            "id": "9f0d9617-1e5d-4d47-bde4-250c0c4df443",
            "calibrated": false
        }
    ]
}
Query Parameters:
 
  • access_token (string) – valid access token for OAuth2 authentication
Response JSON Array of Objects:
 
  • id (string) – id of the chart
  • label (string) – label of the chart
  • chart_calibrated (boolean) – if the chart that the graph refers to is calibrated
Status Codes:
GET /api/v1/metrics/:label/charts

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

Example request:

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

Example response:

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

{
  "data": [
    {
      "type": "individual control limits",
      "metric_id": "9158ae7a-8d62-45a1-a1de-2a02869cf5ef",
      "limits": {
        "ucl": 98.34637729009803,
        "specification_ucl": 100,
        "specification_lcl": 90,
        "mean": 94.02113490833334,
        "lcl": 89.69589252656864
      },
      "label": "Individual Chart",
      "id": "c55ba185-d51e-41a0-bbcc-8aef7db46a63",
      "chart_url": "https://graphite.facts4.work/render?format=json&title=%22individual+control+limits+control+chart+-+Individual+Chart%22&target=alias(staging.staging.collectd.cpu-0.cpu-idle,%20%22X%22)&target=alias(constantLine(98.34637729009803),%20%22UCL%22)&target=alias(constantLine(89.69589252656864),%20%22LCL%22)&target=alias(constantLine(94.02113490833334),%20%22mean%22)",
      "chart_until": "10:00_20160513",
      "chart_from": "08:00_20160513",
      "calibrated": true
    },
    {
      "type": "individual moving range",
      "metric_id": "9158ae7a-8d62-45a1-a1de-2a02869cf5ef",
      "limits": {
        "ucl": 7.191375975915251,
        "specification_ucl": null,
        "specification_lcl": null,
        "mean": 2.201217011299434,
        "lcl": 0
      },
      "label": "Individual Moving Range Chart",
      "id": "cfdcc314-2943-4294-a25b-804422c6983e",
      "chart_url": "https://graphite.facts4.work/render?format=json&title=%22individual+moving+range+control+chart+-+Individual+Moving+Range+Chart%22&target=alias(absolute(derivative(staging.staging.collectd.cpu-0.cpu-idle)),%20%22X%22)&target=alias(constantLine(7.191375975915251),%20%22UCL%22)&target=alias(constantLine(0.0),%20%22LCL%22)&target=alias(constantLine(2.201217011299434),%20%22mean%22)",
      "chart_until": "10:00_20160513",
      "chart_from": "09:00_20160513",
      "calibrated": true
    }
  ]
}
Query Parameters:
 
  • access_token (string) – valid access token for OAuth2 authentication
Response JSON Array of Objects:
 
  • id (string) – id of the chart
  • metric_id (string) – UUID of the metric to which the chart is associated
  • label (string) – label of the chart
  • type (string) – type of the chart, used for calibration and rendering
  • chart_from (string) – time from which the chart is calibrated
  • chart_until (string) – time until the chart is calibrated
  • calibrated (boolean) – if the chart has been calibrated or not
  • limits (json) – specification and calibration limits
Status Codes:
GET /api/v1/metrics/:label/charts/:id

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

Example request:

GET /api/v1/metrics/staging.staging.collectd.cpu-0.cpu-idle/charts/c55ba185-d51e-41a0-bbcc-8aef7db46a63 HTTP/1.1
Host: https://ccharts.hir.facts4.work/

Example response:

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

{
  "data": {
    "type": "individual control limits",
    "metric_id": "9158ae7a-8d62-45a1-a1de-2a02869cf5ef",
    "limits": {
      "ucl": 98.34637729009803,
      "specification_ucl": 100,
      "specification_lcl": 90,
      "mean": 94.02113490833334,
      "lcl": 89.69589252656864
    },
    "label": "Individual Chart",
    "id": "c55ba185-d51e-41a0-bbcc-8aef7db46a63",
    "chart_url": "https://graphite.facts4.work/render?format=json&title=%22individual+control+limits+control+chart+-+Individual+Chart%22&target=alias(staging.staging.collectd.cpu-0.cpu-idle,%20%22X%22)&target=alias(constantLine(98.34637729009803),%20%22UCL%22)&target=alias(constantLine(89.69589252656864),%20%22LCL%22)&target=alias(constantLine(94.02113490833334),%20%22mean%22)",
    "chart_until": "10:00_20160513",
    "chart_from": "08:00_20160513",
    "calibrated": true
  }
}
Parameters:
  • id (string) – chart’s unique id
Query Parameters:
 
  • access_token (string) – valid access token for OAuth2 authentication
Response JSON Array of Objects:
 
  • id (string) – id of the chart
  • metric_id (string) – UUID of the metric to which the chart is associated
  • label (string) – label of the chart
  • type (string) – type of the chart, used for calibration and rendering
  • chart_from (string) – time from which the chart is calibrated
  • chart_until (string) – time until the chart is calibrated
  • calibrated (boolean) – if the chart has been calibrated or not
  • limits (json) – specification and calibration limits
Status Codes:
GET /api/v1/metrics/:label/charts/:id/errors

Returns the errors of a chart :id. Error is a JSON object with :type and :datapoints. Each datapoint is a combination of a UNIX timestamp and a value. Each type of error is relevant to the control chart.

Errors are: out_of_limits, in_range, unbalanced, monotonic, sequence_on_a_side, out_of_specifics, inside_sigma_2_3, outside_sigma

Example request:

GET /api/v1/metrics/staging.staging.collectd.cpu-0.cpu-idle/charts/c55ba185-d51e-41a0-bbcc-8aef7db46a63/errors HTTP/1.1
Host: https://ccharts.hir.facts4.work/

Example response:

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

{
  "data": [
    {
      "type": "out_of_limits",
      "datapoints": [
        [
          14.634533333333337,
          1493856000
        ]
      ]
    },
    {
      "type": "out_of_limits",
      "datapoints": [
        [
          13.721900000000002,
          1493860200
        ]
      ]
    },
    {
      "type": "unbalanced",
      "datapoints": [
        [
          0.5744999999999999,
          1493848920
        ],
        [
          0.3056,
          1493848980
        ],
        [
          0.2525999999999997,
          1493849040
        ]
    }
  ]
}
Parameters:
  • id (string) – chart’s unique id
Query Parameters:
 
  • access_token (string) – valid access token for OAuth2 authentication
Response JSON Array of Objects:
 
  • type (string) – type of error
  • datapoints (array) – array of tuples with UNIX timestamp and value
Status Codes:

POST methods

POST /api/v1/metrics/:label/charts

Adds a new chart. The only required field is type that will produce a chart that is not calibrated and all the rest of the fields will be default. Otherwise these additional fields can be provided: chart_from and chart_until, specification_lcl and specification_ucl for the limits field, while the rest of the fields in the limits (ucl, lcl, and mean).

The id, label and chart_url fields are generated and calculated server side. The calibration is done automatically by calling the time-series server and calculating the respective limits.

For information on how to calibrate the chart please look at the calibration section.

Returns the newly created resource or error message if the request was not valid.

NOTE: Please follow the instructions at the beginning of this page for correct field formatting such as chart_from and chart_until fields, and the accepted type fields for charts.

Example request uncalibrated:

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

{
    "chart": {
        "type": "individual moving range",
    }
}

Example response:

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

{
  "data": {
    "type": "individual moving range",
    "metric_id": "9158ae7a-8d62-45a1-a1de-2a02869cf5ef",
    "limits": null,
    "label": "staging.staging.collectd.cpu-0.cpu-idle",
    "id": "e9433658-0760-4bd7-909d-6c143865366f",
    "chart_url": "https://graphite.facts4.work/render?format=json&title=%22individual+moving+range+control+chart+-+New+moving+range+control+chart%22&target=alias(absolute(derivative(staging.staging.collectd.cpu-0.cpu-idle)),%20%22X%22)&target=alias(constantLine(3.1120018228588235),%20%22UCL%22)&target=alias(constantLine(0.0),%20%22LCL%22)&target=alias(constantLine(0.9525564196078432),%20%22mean%22)",
    "chart_until": null,
    "chart_from": null,
    "calibrated": false
  }
}

Example request calibrated:

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

{
    "chart": {
        "type": "individual moving range",
        "chart_from": "08:00_20160513",
        "chart_until": "11:00_20160513"
    }
}

Example response:

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

{
  "data": {
    "type": "individual moving range",
    "metric_id": "9158ae7a-8d62-45a1-a1de-2a02869cf5ef",
    "limits": {
      "ucl": 3.1120018228588235,
      "specification_ucl": null,
      "specification_lcl": null,
      "mean": 0.9525564196078432,
      "lcl": 0
    },
    "label": "staging.staging.collectd.cpu-0.cpu-idle",
    "id": "e9433658-0760-4bd7-909d-6c143865366f",
    "chart_url": "https://graphite.facts4.work/render?format=json&title=%22individual+moving+range+control+chart+-+New+moving+range+control+chart%22&target=alias(absolute(derivative(staging.staging.collectd.cpu-0.cpu-idle)),%20%22X%22)&target=alias(constantLine(3.1120018228588235),%20%22UCL%22)&target=alias(constantLine(0.0),%20%22LCL%22)&target=alias(constantLine(0.9525564196078432),%20%22mean%22)",
    "chart_until": "11:00_20160513",
    "chart_from": "08:00_20160513",
    "calibrated": true
  }
}
Query Parameters:
 
  • access_token (string) – valid access token for OAuth2 authentication
Request JSON Array of Objects:
 
  • type (string) – type of the chart, used for calibration and rendering
  • chart_from (string) – time from which the chart is calibrated
  • chart_until (string) – time until the chart is calibrated
  • limits (json) – specification and calibration limits
Response JSON Array of Objects:
 
  • id (string) – id of the chart
  • metric_id (string) – UUID of the metric to which the chart is associated
  • label (string) – label of the chart
  • type (string) – type of the chart, used for calibration and rendering
  • chart_from (string) – time from which the chart is calibrated
  • chart_until (string) – time until the chart is calibrated
  • calibrated (boolean) – if the chart has been calibrated or not
  • limits (json) – specification and calibration limits
Status Codes:

PUT methods

PUT /api/v1/metrics/:label/charts/:id

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

For information on how to calibrate the chart please look at the calibration section.

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/charts/e9433658-0760-4bd7-909d-6c143865366f HTTP/1.1
Host: https://ccharts.hir.facts4.work/
Content-Type: application/json

{
  "chart": {
    "type": "individual moving range",
    "limits": {
      "ucl": 3.1120018228588235,
      "specification_ucl": 3.3,
      "specification_lcl": 0.1,
      "mean": 0.9525564196078432,
      "lcl": 0
    },
    "label": "New moving range control chart",
    "chart_until": "11:00_20160513",
    "chart_from": "08:00_20160513",
    "calibrated": true
  }
}

Example response:

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

{
  "data": {
    "type": "individual moving range",
    "metric_id": "9158ae7a-8d62-45a1-a1de-2a02869cf5ef",
    "limits": {
      "ucl": 3.1120018228588235,
      "specification_ucl": 3.1,
      "specification_lcl": 0.1,
      "mean": 0.9525564196078432,
      "lcl": 0
    },
    "label": "New moving range control chart",
    "id": "e9433658-0760-4bd7-909d-6c143865366f",
    "chart_url": "https://graphite.facts4.work/render?format=json&title=%22individual+moving+range+control+chart+-+New+moving+range+control+chart%22&target=alias(absolute(derivative(staging.staging.collectd.cpu-0.cpu-idle)),%20%22X%22)&target=alias(constantLine(3.1120018228588235),%20%22UCL%22)&target=alias(constantLine(0.0),%20%22LCL%22)&target=alias(constantLine(0.9525564196078432),%20%22mean%22)",
    "chart_until": "11:00_20160513",
    "chart_from": "08:00_20160513",
    "calibrated": true
  }
}
Parameters:
  • label (string) – metric’s unique label
  • id (string) – chart’s unique id
Query Parameters:
 
  • access_token (string) – valid access token for OAuth2 authentication
Request JSON Array of Objects:
 
  • type (string) – type of the chart, used for calibration and rendering
  • chart_from (string) – time from which the chart is calibrated
  • chart_until (string) – time until the chart is calibrated
  • limits (json) – specification and calibration limits
Response JSON Array of Objects:
 
  • id (string) – id of the chart
  • metric_id (string) – UUID of the metric to which the chart is associated
  • label (string) – label of the chart
  • type (string) – type of the chart, used for calibration and rendering
  • chart_from (string) – time from which the chart is calibrated
  • chart_until (string) – time until the chart is calibrated
  • calibrated (boolean) – if the chart has been calibrated or not
  • limits (json) – specification and calibration limits
Status Codes:

DELETE methods

DELETE /api/v1/metrics/:label/charts/:id

Delete an existing chart, 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/charts/e9433658-0760-4bd7-909d-6c143865366f HTTP/1.1
Host: https://ccharts.hir.facts4.work/

Example response:

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