This is a read/write adapter that receives samples via Prometheus's remote write protocol and stores them in remote storage like Graphite.
It is based on remote_storage_adapter
Compiling the binary
You can either go get
it:
$ go get -d github.com/criteo/graphite-remote-adapter/...
$ cd $GOPATH/src/github.com/criteo/graphite-remote-adapter
$ make build
$ ./graphite-remote-adapter --graphite.read.url='http://localhost:8080' --graphite.write.carbon-address=localhost:2003
Or checkout the source code and build manually:
$ mkdir -p $GOPATH/src/github.com/criteo
$ cd $GOPATH/src/github.com/criteo
$ git clone https://github.com/criteo/graphite-remote-adapter.git
$ cd graphite-remote-adapter
$ make build
$ ./graphite-remote-adapter --graphite.read.url='http://localhost:8080' --graphite.write.carbon-address=localhost:2003
Running
Graphite example:
./graphite-remote-adapter \
--graphite.write.carbon-address=localhost:2001 \
--graphite.read.url='http://guest:guest@localhost:8080' \
--read.timeout=10s --write.timeout=5s \
--read.delay 3600s \
--graphite.default-prefix prometheus.
To show all flags:
./graphite-remote-adapter -h
Example
You can provide some configuration parameters either as flags or in a configuration file. If defined in both, the flag is used. In addtion, you can fill the configuration file with Graphite specific parameters. You can indeed defined customized paths/behaviors for remote-write into Graphite.
This is an example configuration that should cover most relevant aspects of the YAML configuration format.
web:
listen_address: "0.0.0.0:9201"
telemetry_path: "/metrics"
write:
timeout: 5m
read:
timeout: 5m
delay: 1h
ignore_error: true
graphite:
default_prefix: test.prefix.
enable_tags: false
read:
url: http://localhost:8888
write:
carbon_address: localhost:2003
carbon_transport: tcp
carbon_reconnect_interval: 5m
enable_paths_cache: true
paths_cache_ttl: 1h
paths_cache_purge_interval: 2h
template_data:
var1:
foo: bar
var2: foobar
rules:
- match:
owner: team-X
match_re:
service: ^(foo1|foo2|baz)$
template: '{{.var1.foo}}.graphite.path.host.{{.labels.owner}}.{{.labels.service}}{{if ne .labels.env "prod"}}.{{.labels.env}}{{end}}'
continue: true
- match:
owner: team-X
env: prod
template: 'bla.bla.{{.labels.owner | escape}}.great.{{.var2}}'
continue: true
- match:
owner: team-Z
continue: false
Support for Tags
Graphite 1.1.0 supports tags: http://graphite.readthedocs.io/en/latest/tags.html, you can
enable support for tags in the remote adapter with --graphite.enable-tags
or in the
configuration file.
Filtering tags
Using --graphite.filtered-tags
(or the filtered_tags
yaml field in configuration files), it is possible to exports as tags only a given set of label names. Other labels/values won't be exported as tags, and will still be part of the metric name. This feature is only supported for Graphite Tags (not available when using the OpenMetrics format).
Configuring Prometheus
To configure Prometheus to send samples to this binary, add the following to your prometheus.yml
:
# Remote write configuration.
remote_write:
- url: "http://localhost:9201/write"
# Remote read configuration.
remote_read:
- url: "http://localhost:9201/read"
Since the 0.0.15, a custom prefix can be set in the query string and this will replace the default one. This could be useful if you are using the graphite remote adapter for multiple Prometheus instances with different prefix.
# Remote write configuration.
remote_write:
- url: "http://localhost:9201/write?graphite.default-prefix=customprefix."
# Remote read configuration.
remote_read:
- url: "http://localhost:9201/read?graphite.default-prefix=customprefix."
Testing
You can test the graphite-remote-adapter behavior or its configuration using the second binary named ratool for remote-adapter tool. Here are two examples:
Integration test (manual end-to-end)
The remote-adapter tool will read an input file in Prometheus exposition text format; translate it in WriteRequest using compressed protobuf format; and send it to the graphite-remote-adapter url on its /write endpoint. No need to run a Prometheus instance to test it anymore:
file -> ratool -> graphite-remote-adapter -> nc
$ make build
$ cat cmd/ratool/input.metrics.example
# Use the Prometheus exposition text format
toto{foo="bar", cluster="test"} 42
toto{foo="bar", cluster="canary"} 34
# You can even force a given timestamp
toto{foo="bazz", cluster="canary"} 18 1528819131000
$ ./graphite-remote-adapter --graphite.write.carbon-address ':8888' --log.level debug &
$ nc -l 0.0.0.0 8888 -w 1 > out.txt
$ ./ratool mock-write --metrics.file cmd/ratool/input.metrics.example --remote-adapter.url 'http://localhost:9201'
$ cat out.txt
toto.cluster.test.foo.bar 42.000000 1570803131
toto.cluster.canary.foo.bar 34.000000 1570803131
toto.cluster.canary.foo.bazz 18.000000 1528819131
Unittests (automated config unittests)
If you want to unit test your configurations without requiring any network, define a file for each configuration you want to test.
Example:
config_file: config.yml
tests:
- name: "Test label"
input: |
# Use the Prometheus exposition text format
toto{foo="bar", cluster="test"} 42 1570802650000
toto{foo="bar", cluster="canary"} 34 1570802650000
toto{foo="bazz", cluster="canary"} 18 1528819131000
output: |
toto.my.templated.path.test.foo.bar.lulu 42.000000 1570802650
toto.canary.other.template.bar 34.000000 1570802650
toto.canary.other.template.bazz 18.000000 1528819131
- name: "Other test"
input: |
foo{bar="baz"} 10
output: |
foo.bar.baz.lol 10 1528819131000
The path to config_file
is relative to the test file.
Note: timestamps do not have the same unit for input and output. Input uses a regular unix timestamp in milliseconds, output is in seconds.
To run it:
$ make build
$ ./ratool unittest --test.file test_file.yml
The tool will exit with a non-zero code if the output of the remote adapter for the given configuration and the given input does not match the expected output (order of the lines is not checked).
It also prints the diff on the standard error stream.
Example of output:
./ratool unittest --config.file foo.yml --test.file bar.yml
# Testing foo.yml
## Test label
-toto.my.templated.path.test.foo.bar.lulu 42.000000 1570802650
-toto.canary.other.template.bar 34.000000 1570802650
-toto.canary.other.template.bazz 18.000000 1528819131
+toto.cluster.test.foo.bar 42.000000 1536658898
+
+toto.cluster.canary.foo.bar 34.000000 1536658898
+
+toto.cluster.canary.foo.bazz 18.000000 1528819131
## Other test
-foo.bar.baz.lol 10 1528819131000
+foo.bar.baz 10.000000 1536658898