From 6bdee09039576259c204754ad5f248f28b733fc4 Mon Sep 17 00:00:00 2001 From: Greg McKeever Date: Thu, 5 Oct 2017 14:43:02 -0700 Subject: [PATCH] Update Readme with tags only documentation --- README.md | 186 ++++++++++++++++++------------------------------------ 1 file changed, 61 insertions(+), 125 deletions(-) diff --git a/README.md b/README.md index 932f66d..a7b24f7 100644 --- a/README.md +++ b/README.md @@ -40,56 +40,74 @@ If you are using jruby, you need to ensure [jruby-openssl](https://github.com/jr If you are looking for the quickest possible route to getting a data into Metrics, you only need two lines: Librato::Metrics.authenticate 'email', 'api_key' - Librato::Metrics.submit my_metric: 42, my_other_metric: 1002 - -Unspecified metrics will send a *gauge*, but if you need to send a different metric type or include additional properties, simply use a hash: - - Librato::Metrics.submit my_metric: {type: :counter, value: 1002, source: 'myapp'} + Librato::Metrics.submit my_metric: { value: 42, tags: { host: 'localhost' } } While this is all you need to get started, if you are sending a number of metrics regularly a queue may be easier/more performant so read on... + ## Authentication -Make sure you have [an account for Metrics](https://metrics.librato.com/) and then authenticate with your email and API key (on your account page): +Make sure you have [an account for Librato](https://metrics.librato.com/) and then authenticate with your email and API key (on your account page): Librato::Metrics.authenticate 'email', 'api_key' + ## Sending Measurements -If you are sending very many measurements or sending them very often, it will be much higher performance to bundle them up together to reduce your request volume. Use `Queue` for this. +A measurement includes a metric name, value, and one or more tags. Tags include a name/value pair that describe a particular data stream. Each unique tag set creates an individual metric stream which can later be filtered and aggregated along. -Queue up a simple gauge metric named `temperature`: +Queue up a simple metric named `temperature`: queue = Librato::Metrics::Queue.new - queue.add temperature: 32.2 + queue.add temperature: {value: 77, tags: { city: 'oakland' }} + queue.submit + +### Top-Level Tags + +You can initialize `Queue` and/or `Aggregator` with top-level tags that will be applied to every measurement: + + queue = Librato::Metrics::Queue.new(tags: { service: 'auth', environment: 'prod', host: 'auth-prod-1' }) + queue.add my_metric: 10 + queue.submit + +### Per-Measurement Tags -While symbols are used by convention for metric names, strings will work just as well: +Optionally, you can submit per-measurement tags by passing a tags Hash when adding measurements: - queue.add 'myapp.request_time' => 86.7 + queue.add my_other_metric: { value: 25, tags: { db: 'rr1' } } + queue.submit -If you are tracking measurements over several seconds/minutes, the queue will handle storing measurement time for you (otherwise all metrics will be recorded as measured when they are submitted). +For more information, visit the [API documentation](https://www.librato.com/docs/api/#create-a-measurement). -If you want to specify a time other than queuing time for the measurement: - # use a epoch integer - queue.add humidity: {measure_time: 1336508422, value: 48.2} +## Querying Metrics - # use a Time object to correct for a 5 second delay - queue.add humidity: {measure_time: Time.now-5, value: 37.6} +Get name and properties for all metrics you have in the system: -You can queue multiple metrics at once. Here's a gauge (`load`) and a counter (`visits`): + metrics = Librato::Metrics.metrics - queue.add load: 2.2, visits: {type: :counter, value: 400} +Get only metrics whose name includes `time`: -Queue up a metric with a specified source: + metrics = Librato::Metrics.metrics name: 'time' - queue.add cpu: {source: 'app1', value: 92.6} -A complete [list of metric attributes](https://www.librato.com/docs/api/#metric-attributes) is available in the [API documentation](https://www.librato.com/docs/api/). +## Retrieving Measurements -Send currently queued measurements to Metrics: +Get the series for `exceptions` in **production** grouped by **sum** within the **last hour**: + +```ruby +query = { + resolution: 1, + duration: 3600, + group_by: "environment", + group_by_function: "sum", + tags_search: "environment=prod*" +} +Librato::Metrics.get_series :exceptions, query +``` + +For more information, visit the [API documentation](https://www.librato.com/docs/api/#retrieve-a-measurement). - queue.submit ## Aggregate Measurements @@ -110,7 +128,7 @@ Which would result in a gauge measurement like: You can specify a source during aggregate construction: - aggregator = Librato::Metrics::Aggregator.new(source: 'foobar') + aggregator = Librato::Metrics::Aggregator.new(tags: { service: 'auth', environment: 'prod', host: 'auth-prod-1' }) You can aggregate multiple metrics at once: @@ -132,7 +150,7 @@ The difference between the two is that `Queue` submits each timing measurement i If you need extra attributes for a `Queue` timing measurement, simply add them on: - queue.time :my_measurement, source: 'app1' do + queue.time :my_measurement do # do work... end @@ -175,16 +193,16 @@ See the documentation of `Annotator` for more details and examples of use. Both `Queue` and `Aggregator` support automatically submitting measurements on a given time interval: - # submit once per minute - timed_queue = Librato::Metrics::Queue.new(autosubmit_interval: 60) + # submit once per minute + timed_queue = Librato::Metrics::Queue.new(autosubmit_interval: 60) - # submit every 5 minutes - timed_aggregator = Librato::Metrics::Aggregator.new(autosubmit_interval: 300) + # submit every 5 minutes + timed_aggregator = Librato::Metrics::Aggregator.new(autosubmit_interval: 300) `Queue` also supports auto-submission based on measurement volume: - # submit when the 400th measurement is queued - volume_queue = Librato::Metrics::Queue.new(autosubmit_count: 400) + # submit when the 400th measurement is queued + volume_queue = Librato::Metrics::Queue.new(autosubmit_count: 400) These options can also be combined for more flexible behavior. @@ -192,83 +210,6 @@ Both options are driven by the addition of measurements. *If you are adding meas If your goal is to collect metrics every _x_ seconds and submit them, [check out this code example](https://github.com/librato/librato-metrics/blob/master/examples/submit_every.rb). -## Submitting tagged measurements - -Librato Metrics supports tagged measurements that are associated with a metric, one or more tag pairs, and a point in time. - -**Tags** are a set of name=value tag pairs that describe the particular data stream. Tags behave as extra dimensions that data streams can be filtered and aggregated along. - -### Top-Level Tags - -You can initialize `Queue` and/or `Aggregator` with top-level tags that will be applied to every measurement: - -```ruby -queue = Librato::Metrics::Queue.new(tags: { service: 'auth', environment: 'prod', host: 'auth-prod-1' }) -queue.add my_metric: 10 -``` - -### Per-Measurement Tags - -Optionally, you can submit per-measurement tags by passing a tags Hash when adding measurements: - -```ruby -queue.add my_other_metric: { value: 25, tags: { db: 'rr1' } } -``` - -For more information, visit the [API documentation](https://www.librato.com/docs/api/#create-a-measurement). - -## Querying Metrics - -Get name and properties for all metrics you have in the system: - - metrics = Librato::Metrics.metrics - -Get only metrics whose name includes `time`: - - metrics = Librato::Metrics.metrics name: 'time' - -## Querying Metric Data - -Get attributes for metric `temperature`: - - data = Librato::Metrics.get_metric :temperature - -Get the 20 most recent data points for `temperature`: - - data = Librato::Metrics.get_measurements :temperature, count: 20 - -Get the 20 most recent data points for `temperature` from a specific source: - - data = Librato::Metrics.get_measurements :temperature, count: 20, source: 'app1' - -Get the 20 most recent 15 minute data point rollups for `temperature`: - - data = Librato::Metrics.get_measurements :temperature, count: 20, resolution: 900 - -Get the 5 minute moving average for `temperature` for the last hour, assuming temperature is submitted once per minute: - - data = Librato::Metrics.get_composite 'moving_average(mean(series("temperature", "*"), {size: "5"}))', start_time: Time.now.to_i - 60*60, resolution: 300 - -There are many more options supported for querying, take a look at the -[REST API docs](https://www.librato.com/docs/api/#retrieve-metrics) or the individual method documentation for more details. - -## Retrieving tagged measurements - -Get the series for `exceptions` in **production** grouped by **sum** within the **last hour**: - -```ruby -query = { - resolution: 1, - duration: 3600, - group_by: "environment", - group_by_function: "sum", - tags_search: "environment=prod*" -} -Librato::Metrics.get_series :exceptions, query -``` - -For more information, visit the [API documentation](https://www.librato.com/docs/api/#retrieve-a-measurement). - ## Setting Metric Properties Setting custom [properties](https://www.librato.com/docs/api/#metric-attributes) on your metrics is easy: @@ -276,14 +217,12 @@ Setting custom [properties](https://www.librato.com/docs/api/#metric-attributes) # assign a period and default color Librato::Metrics.update_metric :temperature, period: 15, attributes: { color: 'F00' } -It is also possible to update properties for multiple metrics at once, see the [`#update_metric` method documentation](http://rubydoc.info/github/librato/librato-metrics/master/Librato/Metrics/Client#update_metric-instance_method) for more information. - ## Deleting Metrics If you ever need to remove a metric and all of its measurements, doing so is easy: - # delete the metrics 'temperature' and 'humidity' - Librato::Metrics.delete_metrics :temperature, :humidity + # delete the metrics 'temperature' and 'humidity' + Librato::Metrics.delete_metrics :temperature, :humidity You can also delete using wildcards: @@ -304,22 +243,19 @@ If you need to use metrics with multiple sets of authentication credentials simu All of the same operations you can call directly from `Librato::Metrics` are available per-client: - # list Joe's metrics - joe.metrics - - # fetch the last 20 data points for Mike's metric, humidity - mike.get_measurements :humidity, count: 20 + # list Joe's metrics + joe.metrics There are two ways to associate a new queue with a client: - # these are functionally equivalent - joe_queue = Librato::Metrics::Queue.new(client: joe) - joe_queue = joe.new_queue + # these are functionally equivalent + joe_queue = Librato::Metrics::Queue.new(client: joe) + joe_queue = joe.new_queue Once the queue is associated you can use it normally: - joe_queue.add temperature: {source: 'sf', value: 65.2} - joe_queue.submit + joe_queue.add temperature: { value: 65.2, tags: { city: 'san francisco' } } + joe_queue.submit ## Thread Safety @@ -327,7 +263,7 @@ The `librato-metrics` gem currently does not do internal locking for thread safe ## More Information -`librato-metrics` is sufficiently complex that not everything can be documented in the README. Additional options are documented regularly in the codebase. You are encouraged to take a quick look through the [docs](http://rubydoc.info/github/librato/librato-metrics/frames) and [source](https://github.com/librato/librato-metrics) for more. +`librato-metrics` is sufficiently complex that not everything can be documented in the README. Additional options are documented regularly in the codebase. You are encouraged to take a quick look through the [source](https://github.com/librato/librato-metrics) for more. We also maintain a set of [examples of common uses](https://github.com/librato/librato-metrics/tree/master/examples) and appreciate contributions if you have them. @@ -342,4 +278,4 @@ We also maintain a set of [examples of common uses](https://github.com/librato/l ## Copyright -Copyright (c) 2011-2017 [Librato Inc.](http://librato.com) See LICENSE for details. +Copyright (c) 2011-2017 [Solarwinds, Inc.](http://www.solarwinds.com) See LICENSE for details.