User Interface

DalmatinerFE serves as both an API endpoint and a user interface for ad-hoc query capabilities. It also allows one to explore the available buckets and the metrics stored in those buckets.

Browser API

Listing buckets

From browser use:

http://127.0.0.1:8080/buckets/

For JSON output use:

curl -H 'accept: application/json' 'http://127.0.0.1:8080/buckets'

Example of JSON output:

[{"grace":0,"name":"my_opentsdb_bucket","ppf":604800,"resolution":1000,"ttl":604800},
{"grace":0,"name":"dalmatinerdb","ppf":604800,"resolution":1000,"ttl":"infinity"}]

grace: TODO: not clear meaning of parameter

ppf: points per file, default value 604800 is configured in dalmatinerdb.conf

resolution: resolution of bucket in milliseconds, default is 1000

ttl: How long data is kept by default, measured either in points or infinity for not deleting old data. As ppf, set by dalmatinerdb.conf and is infinity by default

Bucket dalmatinerdb is always present by default, and considering that ddb_proxy doesn't have logs for writes (for lowering the load purposes), it might be a very convenient source of information (for example, mps value shows the amount of writes in all buckets of dalmatinerdb database)

Listing metrics

endpoint which lists all actual metrics (with tags if there are any) stored. From browser use:

http://127.0.0.1:8080/buckets/my_opentsdb_bucket

For JSON output use:

curl -H 'accept: application/json' 'http://127.0.0.1:8080/buckets/my_opentsdb_bucket'

If there's PostgreSQL backend enabled, the output could be huuuuuuuge and it's very likely that dalmatiner frontend won't be able to handle this amount of data. But if it does, you'll get something like this:

["'host_metric_1'.'host=10.91.136.251'",
"'host_metric_1'.'host=10.91.136.250'",
"'host_metric_2'.'host=10.91.136.251'",
"'host_metric_2'.'host=10.91.136.250'",
...,
]

So, "'host_metric_1'.'host=10.91.136.251'" and "'host_metric_1'.'host=10.91.136.250'", for example, is the same metric with different tag values, but we're seeing as many lines with it as there are unique values for each of it's tags. Easy to see why this endpoint returns a huge amount of data.

On a plus side, you can use each line for running queries because it's already a full name of some metric with all of it's tags.
See this page for examples of running queries for metrics.

JSON API for PostgreSQL (not accessible in any other way)

This is actual only if PostgreSQL backend is enabled.
In PostgreSQL backend there's a collection with the same name as corresponding bucket, storing namespaces, metrics and tags, along with all possible tag values.

Listing buckets (collections)

Lists collections of metrics added to PostgreSQL. Unlike /buckets endpoint, it doesn't include the default dalmatinerdb bucket.

curl -H 'accept: application/json'  'http://127.0.0.1:8080/collections'

Example output:

["my_opentsdb_bucket"]

Listing metrics

Returns only unique metric names without tags:

curl -H 'accept: application/json' 'http://127.0.0.1:8080/collections/my_opentsdb_bucket/metrics'

Example output:

[
{"key":"CWNhbmNlbF93cg==","parts":["metric_name_1"]},
{"key":"CGNwdV9ub29w","parts":["metric_name_2"]},
{"key":"CWNwdV9zdGFsbA==","parts":["metric_name_3"]},
{"key":"CWNwdV91c2FnZQ==","parts":["metric_name_4"]}
]

This endpoint helps to see that dalmatiner doesn't use actual names of metrics for referencing data, instead it uses hash keys computed from metric names.

Listing namespaces for collection

curl -H 'accept: application/json' 'http://127.0.0.1:8080/collections/my_opentsdb_bucket/namespaces/'

Example output:

["","ddb"]

In this case, empty namespace is the one where all our metrics are stored, and ddb namespace has some service data (TODO: document data from ddb namespace)

Listing all tags in the namespace

As our namespace is empty, we're just using // to specify it. In case your namespace has name, add it's name between those slashes:

curl -H 'accept: application/json' 'http://127.0.0.1:8080/collections/my_opentsdb_bucket/namespaces//tags'

Example output:

["host","vm_instance"]

So, here we have 2 possible tags for any metric in namespace (which doesn't mean that both of them will be used for each metric).

Listing all values for particular tags

curl -H 'accept: application/json' 'http://127.0.0.1:8080/collections/my_opentsdb_bucket/namespaces//tags/host/values

Example output:

["10.91.136.250","10.91.136.251"]

Listing all tags used for particular metric

Important thing to note is that you can only use metric key here instead of metric name. For example, to get all tags used for metric cpu_noop we first need to get it's key from /collections/sardina_metrics/metrics endpoint which is:

{"key":"CGNwdV9ub29w","parts":["metric_name_2"]}

Then we use this key to query this endpoint:

curl -H 'accept: application/json' 'http://127.0.0.1:8080/collections/my_opentsdb_bucket/metrics/CGNwdV9ub29w/namespaces//tags'

Example output:

["host","vm_instance"]

Listing all values for particular tag of particular metric

The same as above, can only use metric key. Querying for all values of tag host for metric metric_name_2:

curl -H 'accept: application/json' 'http://127.0.0.1:8080/collections/my_opentsdb_bucket/metrics/CGNwdV9ub29w/namespaces//tags/host/values'

Example output:

["10.91.136.250","10.91.136.251"]