https://github.com/kamon-io/kamon-opentsdb
https://github.com/kamon-io/kamon-opentsdb
kamon metrics opentsdb
Last synced: 9 days ago
JSON representation
- Host: GitHub
- URL: https://github.com/kamon-io/kamon-opentsdb
- Owner: kamon-io
- License: apache-2.0
- Created: 2017-03-11T17:07:58.000Z (about 8 years ago)
- Default Branch: master
- Last Pushed: 2017-07-17T08:29:31.000Z (almost 8 years ago)
- Last Synced: 2025-04-05T01:32:19.302Z (about 1 month ago)
- Topics: kamon, metrics, opentsdb
- Language: Scala
- Size: 23.4 KB
- Stars: 2
- Watchers: 3
- Forks: 4
- Open Issues: 1
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
OpenTSDB Integration 
========================================================================================================
[](https://gitter.im/kamon-io/Kamon?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge)
[](https://maven-badges.herokuapp.com/maven-central/io.kamon/kamon-opentsdb_2.11)
Reporting Metrics to OpenTSDB
=============================
[OpenTSDB] is a high performance open source database for handling time series
data. It uses hbase to allow it to store and serve massive amounts of time series data
without losing granularity.
Installation
------------
Add the `kamon-opentsdb` dependency to your project and ensure that it is in
your classpath at runtime. Kamon's module loader will detect that
the OpenTSDB module is in the classpath and automatically starts it.
### Getting Started
Kamon OpenTSDB module is currently available for Scala 2.10, 2.11 and 2.12.
It support version 1.3.0 of OpenTSDB
Supported releases and dependencies are shown below.
| kamon-opentsdb | status | jdk | scala |
|:------:|:------:|:----:|------------------|
| 0.6.7 | stable | 1.8+ | 2.10, 2.11, 2.12 |
To get started with SBT, simply add the following to your `build.sbt`
file:
```scala
libraryDependencies += "io.kamon" %% "kamon-opentsdb" % "0.6.7"
```
Configuration
-------------
Please refer to the [reference configuration](src/main/resources/reference.conf) for more details.
#### Common actions (i.e. TLDR)
Connect to OpenTSDB - Set `kamon.opentsdb.direct.quorum` to your zookeeper quorum
Set application name - Set `kamon.opentsdb.rules.application.value`
Override host name - Set `kamon.opentsdb.rules.host.value`
Set precision of timestamps - Set `kamon.opentsdb.default.timestamp` to 'seconds' or 'milliseconds'
#### Connection
Although OpenTSDB provides a REST interface, at this time the project
stores data directly to hbase using the TSDB api. Set the `kamon.opentsdb.direct.quorum` to
a comma separated list of zookeeper servers.
#### Subscriptions
You can configure the metric categories to which this
module will subscribe using the `kamon.opentsdb.subscriptions` key. By default,
the following subscriptions are included:
```typesafeconfig
kamon.opentsdb {
subscriptions {
histogram = [ "**" ]
min-max-counter = [ "**" ]
gauge = [ "**" ]
counter = [ "**" ]
trace = [ "**" ]
trace-segment = [ "**" ]
akka-actor = [ "**" ]
akka-dispatcher = [ "**" ]
akka-router = [ "**" ]
system-metric = [ "**" ]
http-server = [ "**" ]
}
}
```
#### Metric Name
Names are generated by concatenating the results of several [rules](#rules) together
```typesafeconfig
kamon.opentsdb.default.name = [application, category, entity, metric, stat]
```
This design allows you to easily customize the metric name by reordering,
adding, and removing [rules](#rules) as you see fit. `kamon.opentsdb.name.separator` is inserted between each rule who result is non-empty.
Empty rules are removed from the metric name
#### Metric Tags
All tags associated with the kamon metric will be passed through to OpenTSDB.
Additional tags may be added by mapping tag names to [rules](#rules).
A tag will be named the exact value listed in the config, if you would like
a different name, create a new rule (See [Extensibility](#extensibility))
```typesafeconfig
kamon.opentsdb.default.tags = [ application, host ]
```
#### Stats
Many statistics can be calculated for each Kamon metric, and ,by default,
each statistic will be stored as a separate OpenTSDB metric.
```typesafeconfig
kamon.opentsdb.default.stats = [ count, rate, min, max, median, mean, 90, 99 ]
```
Most statistics can only be used with histograms, however assigning them
to a counter is harmless.
__Counter stats__
* __count__: The value of the counter
* __rate__: The value of the counter divided by the tick length in seconds
__Histogram Stats__
* __count__: The number of values stored in the histogram
* __rate__: The number of values stored in the histogram divided by the tick length in seconds
* __mean__: The average of all values stored during the tick
* __max__: The largest value stored during the tick
* __min__: The smallest value stored during the tick
* __median__: The median value (synonym for "50")
Additionally, numeric values in the stat list, will generate percentile statistics in the OpenTSDB database.
* __50__: 50th percentile
* __70.5__: 70.5th percentile
* __90__: 90th percentile
See [Extensibility](#extensibility) to learn how to create your own stats.
#### Rules
* __category__: The entity's category.
* __entity__: The entity's name.
* __metric__: The metric name assigned in the entity recorder.
* __stat__: The name of the statistic
* __host__: The local host name
* __application__ : The name of the application. Undefined by default.
See [Extensibility](#extensibility) to learn how to create your own rules.
#### Idle metrics
if `filterIdle` is true, don't send values to opentsdb for inactive metrics,
as opposed to sending 0 for all stats.
### Customization
Metrics can be customized at the global, category, and individual metric level.
To make alteration at the global level, alter the children of `kamon.opentsdb.default`
To make alteration at a category level, add entries to `kamon.opentsdb.category`.
Any values not set on the category level, will be inherited from the defaults.
```typesafeconfig
kamon.opentsdb.category.counter = { name = [ metric ], stats = [count ] }
```
This configuration will change the [name](#metric-name) and [stats](#stats) recorded for counter metrics, but
the [tags](#metric-tags) and *timestamp* from `kamon.opentsdb.default` will be used.
To make alterations for a specific metric, add entries to `kamon.opentsdb.metrics`.
Any values not set on the metric level, will be inherited from the category and defaults.
```typesafeconfig
kamon.opentsdb.metrics."my.metric.name" = { stats = [ 90, 95, 99, 99.9, 99.999 ], filterIdle = false }
```
Here the [name](#metric-name), [tags](#metric-tags), and *timestamp* from the defaults will be used, unless
the metric is a "counter", in which case the [name](#metric-name) and [stats](#stats) from above will be used.
### Extensibility
You can add static values to your metric names and tags by adding
entries of the format `kamon.opentsdb.rules..value = "some string"`
These values can be referenced in [name](#metric-name) and [tags](#metric-tags) by using *rule-name*
EX.
```typesafeconfig
kamon.opentsdb.rules.cluster.value = "EC2"
kamon.opentsdb.default.name = [ cluster, application, category, entity, metric, stat]
```
You can create your own dynamic rules by subclassing `kamon.opentsdb.Rule` and adding
an entry of the format `kamon.opentsdb.rules..generator = "fully.qualified.class.name"`
EX.
```typesafeconfig
kamon.opentsdb.rules.timezone.generator = "leider.ken.application.TimezoneRule"
kamon.opentsdb.tags = { host = host, tz = timezone }
```
You can create you own stats by subclassing `kamon.opentsdb.Stat` and adding
an entry of the format `kamon.opentsdb.stats. = "fully.qualified.class.name"`
EX.
```typesafeconfig
kamon.opentsdb.stats.integral = "leider.ken.application.IntegralStat"
kamon.opentsdb.counter.stats = [ count, rate, integral ]
```
[OpenTSDB]: http://opentsdb.net/