Providers

Providers Connectors Settings

Catalog providers can be configured with settings and filters:

Facette

Graphite

InfluxDB

Mapping parameters:

{
  "source": ["column:host"],
  "metric": ["name", "column:instance", "column:type", "column:type_instance"],
  "glue": "."
}

Note: you should either use pattern or mapping, but not both.

KairosDB

RRDtool

Provider Filters

Provider filters allow changing how sources and metrics appear in the catalog, and discard the ones you don’t want to deal with. Filter rule format:

{
  "action": "<action to perform on record (discard|rewrite|sieve)>",
  "target": "<record field to match (any|metric|source)>",
  "pattern": "<regular expression pattern>"
  "into": "<replacement value (for \"rewrite\" action)>"
}

Note: regular expressions must follow the RE2 syntax.

Create a provider

POST /api/v1/providers/

This endpoint creates a new catalog provider. Required fields:

• name (type string): provider name
• connector (type string): provider connector type, see facette -V output to find which connectors are supported

Optional fields:

• description (type string): a description for the provider
• settings (type object): connector settings
• filters (type array of objects): list of provider filters
• priority (type integer): in case multiple providers expose the same metric, the provider with higher priority wins (default: 0)
• refresh_internal (type integer): interval (in seconds) to trigger a periodic refresh of the provider (default: 0, no refresh)

Caution: in JSON you need to double the escaping character \ when writing regular expressions (e.g. \d → \\d).

Requests

Examples

Content-Type: application/json

{
  "name": "graphite",
  "description": "Metrics from Graphite",
  "connector": "graphite",
  "settings": {
    "url": "graphite.example.net:8080",
    "pattern": "(?P<source>[^\\\\.]+)\\\\.(?P<metric>.+)"
  },
  "refresh_interval": 3600,
  "filters": [
    {
      "action": "rewrite",
      "target": "source",
      "pattern": "_",
      "into": "."
    }
  ]
}

Responses

Status: 201 Created

Delete all providers

DELETE /api/v1/providers/

This endpoint deletes all providers.

If the request header X-Confirm-Action is not present or if the instance is read-only the operation will be rejected with 403 Forbidden.

Requests

Headers

Responses

Status: 204 No Content

List providers

GET /api/v1/providers/

This endpoint returns providers. If a filter query parameter is given, only providers having their name matching the filter will be returned.

This endpoint supports pagination through the offset and limit query parameters and sorting using sort query parameter (separated by commas; prefix field name with “-” to reverse sort order).

Parameters

Responses

Headers

Examples

Status: 200 OK

[
  {
    "created": "2017-06-14T06:09:19Z",
    "description": null,
    "enabled": true,
    "id": "e91ac07e-5f74-5845-6a09-4903ecd30995",
    "modified": "2017-06-14T06:12:57Z",
    "name": "collectd"
  }
]

Get a provider

GET /api/v1/providers/:id

This endpoint returns a provider given its identifier.

Parameters

Responses

Examples

Status: 200 OK

{
  "id": "4654e374-70e8-5621-afab-ac9c1ff91261",
  "name": "kairosdb",
  "description": null,
  "created": "2017-05-11T12:51:07Z",
  "modified": "2017-05-22T07:59:57Z",
  "connector": "kairosdb",
  "settings": {
    "aggregators": [
      "avg"
    ],
    "url": "http://kairosdb.example.net:8080"
  },
  "filters": [
    {
      "action": "discard",
      "target": "metric",
      "pattern": "^kairosdb\\.",
      "into": ""
    },
    {
      "action": "rewrite",
      "target": "source",
      "pattern": "_",
      "into": "."
    },
    {
      "action": "rewrite",
      "target": "metric",
      "pattern": "/avg$",
      "into": ""
    },
    {
      "action": "rewrite",
      "target": "metric",
      "pattern": "\\.value$",
      "into": ""
    },
    {
      "action": "rewrite",
      "target": "metric",
      "pattern": "^(.+)\\.(?:derive|gauge|latency)\\.(.+)",
      "into": "$1.$2"
    }
  ],
  "refresh_interval": 900,
  "priority": 0,
  "enabled": true
}

Update a provider

PUT /api/v1/providers/:id

This endpoint updates a provider given its identifier. The request body is similar to the Create a new catalog provider endpoint.

If the instance is read-only the operation will be rejected with 403 Forbidden.

Parameters

Responses

Status: 204 No Content

Partially update a provider

PATCH /api/v1/providers/:id

This endpoint partially updates a provider given its identifier. The request body is similar to the Update a provider endpoint, but only specified fields will be modified.

If the instance is read-only the operation will be rejected with 403 Forbidden.

Parameters

Responses

Status: 204 No Content

Delete a provider

DELETE /api/v1/providers/:id

This endpoint deletes a provider given its identifier.

If the instance is read-only the operation will be rejected with 403 Forbidden.

Parameters

Responses

Status: 204 No Content

Refresh a provider

POST /api/v1/providers/:id/refresh

This endpoint triggers a catalog refresh for a provider given its identifier.

Responses

Status: 204 No Content