Update Readme with tags only documentation

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,115 +193,36 @@ 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.
 
 Both options are driven by the addition of measurements. *If you are adding measurements irregularly (less than once per second), time-based submission may lag past your specified interval until the next measurement is added.*
 
 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:
 
     # 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,30 +243,27 @@ 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
 
 The `librato-metrics` gem currently does not do internal locking for thread safety. When used in multi-threaded applications, please add your own [mutexes](http://www.ruby-doc.org/core-2.0/Mutex.html) for sensitive operations.
 
 ## 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.