API Documentation

API Documentation

Tiny Exporter supports gauge, counter, and histogram metric types for Prometheus. Out of the box there is no configuration you need to do to use the API or add metrics, you can just start issuing POST requests with your data. There are however some scenarios where you may want to configure your metrics before you start sending data to the API.

Increment a counter value

The simplest form of metric is a counter, which is just a monotonically increasing value. This value will always increase by 1 when you call this endpoint.

The HTTP request should not contain a value, and if it does it will be ignored.

If this metric has not been created with a PUT request, it will be created for you. More about

curl  -X POST http://localhost:5000/api/v2/metric/counter/test \
      -H 'Content-Type: application/json; charset=utf-8' \
      -d $'{
        "labels": {
          "example_label": "some_value",
          "another_label": "another_value"
        }
      }'

Response: 200 OK

{
  "result": "Saved",
  "status": "OK"
}

Store a gauge value

Save a gauge value to the exporter, which is a single numerical value that can go up and down over time.

curl  -X POST http://localhost:5000/api/v2/metric/gauge/test \
      -H 'Content-Type: application/json; charset=utf-8' \
      -d $'{
        "value": 100,
        "labels": {
          "example_label": "some_value",
          "another_label": "another_value"
        }
      }'

Response: 200 OK

{
  "result": "Saved",
  "status": "OK"
}

Store a histogram value

This will increment the count of buckets that the value passed fits into, which is how Prometheus expects histogram data.

If the metric buckets haven't been set with a PUT request, the buckets will default to [0.1, 0.2, 0.4, 1, 3, 8, 20, 60, 120]. These values are suitable for API response times (in seconds) and are the default from Prometheus.

curl  -X POST http://localhost:5000/api/v2/metric/histogram/test \
      -H 'Content-Type: application/json; charset=utf-8' \
      -d $'{
        "value": 100,
        "labels": {
          "example_label": "some_value",
          "another_label": "another_value"
        }
      }'

Response:

200 OK

{
  "result": "Saved",
  "status": "OK"
}

Configuring metrics

While optional, you can issue a PUT request to Tiny Exporter to pre-configure a metric before you send data to it.

You'd want to do this if you would like to customize the "HELP" text in the exported metrics to Prometheus, and if you want to set custom buckets for a histogram metric.

Important! If you issue a PUT request to a metric that already exists, all data in the exporter for that metric will be purged!

Histogram example

Most likely you'll use this endpoint to set custom buckets for your histogram metric. For example:

curl  -X PUT http://localhost:5000/api/v2/metric/histogram/pizza_delivery \
      -H 'Content-Type: application/json; charset=utf-8' \
      -d $'{
        "help": "Pizza Delivery Time (seconds)",
        "buckets": [120, 300, 1200, 2700, 3600, "+Inf"]
      }'

Response:

201 CREATED

{
  "result": "Created",
  "status": "OK"
}

"+Inf" is required for Prometheus and should always be set. The other bucket values must be numerical.

Gauge and counter example

You can also set values and re-create gauge and counter metrics. At the moment, the only values you can set are help and labels:

• help: Sets the "HELP" text in the exported metrics at /metrics
• labels: Sets a set of labels that are added to the labels passed in every POST request

This is an example of setting the help text and labels for a metric named 'temp':

curl  -X PUT http://localhost:5000/api/v2/metric/gauge/temp \
      -H 'Content-Type: application/json; charset=utf-8' \
      -d $'{
        "help": "Core Temperature (c)",
        "labels": {
          "scale": "celsius"
        }
      }'

Authentication

Since this API is meant to be lightweight, there is no authentication by design. If you want to add auth, I suggest putting it behind a reverse proxy.