appoptics-api-ruby 2.1.3

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: ab5f2ec4dda081acffb747cb10f167f17751850e
+  data.tar.gz: 6f29021a2c15a03c19eb8a330e6df74a800c23e5
+SHA512:
+  metadata.gz: b62cf09a2685a4f9b3feded918b24f2b52c476edcd096a077f2e75c0dcaacb9f1b1b28b45ea37c6a46027874253c051616479dc5d49e82d555956f7d8b85f07f
+  data.tar.gz: be366b70d620f0e576731c318163a6c10e4e8d76d8b4462969638bb5c4b2338ca16b0136d66de7f82da67dc8391896edab58ab55b91ea4a518e52e803ebe264a

data/.gitignore

@@ -0,0 +1,23 @@
+.ruby-gemset
+.ruby-version
+
+.bundle
+.DS_Store
+Gemfile.lock
+*.gem
+
+# docs
+rdoc
+doc
+.yardoc
+
+# textmate
+*.tmproj
+
+# vim
+*.swp
+
+# rcov generated
+coverage
+
+test_env.sh

data/.rspec

@@ -0,0 +1,2 @@
+--color
+--require spec_helper

data/.travis.yml

@@ -0,0 +1,25 @@
+# use container-based infrastructure
+sudo: false
+
+rvm:
+  - 1.9.3
+  - 2.1.10
+  - 2.2.6
+  - 2.3.3
+  - 2.4.0
+  - jruby-19mode
+  # - rbx
+  - ruby-head
+
+matrix:
+  allow_failures:
+    - rvm: ruby-head
+
+branches:
+  except:
+    - /^v[0-9]/
+
+notifications:
+  email:
+    on_failure: change
+    on_success: never

data/CHANGELOG.md

@@ -0,0 +1,184 @@
+## Changelog
+
+### Version 2.1.3
+* Update to support the AppOptics API
+
+### Version 2.1.2
+* Add `Faraday` 0.8.x support to `ExpectsStatus` (#138, George Ogata)
+
+### Version 2.1.1
+* Fix `#empty?` to check queued payload (#137, Cyril David)
+
+### Version 2.1.0
+* Add support for tagged measurements (#121)
+
+### Version 2.0.2
+* Filter sensitive headers in exception output (#130, Yannick Schutz)
+
+### Version 2.0.1
+* Fix SmartJSON delegation bug for ruby 2.3.1 (#123)
+
+### Version 2.0.0
+* Remove support for deprecated methods (#117)
+* Upgrade rspec from 2.6 to 3.5 (#118)
+* Remove support for ruby 1.8 (#119)
+* Remove `MultiJson` runtime dependency (#119)
+* Relax `Faraday` runtime dependency (#119)
+
+### Version 1.6.1
+* Fix bugs with listing sources (#116)
+
+### Version 1.6.0
+* Add HTTP proxy support (#112) (Genki Sugawara)
+
+### Version 1.5.1
+* Fix bug causing incompatible dates when annotating with block form (#109)
+
+### Version 1.5.0
+* Add #get_composite for easier fetching of composite measurements
+
+### Version 1.4.0
+* Add support for snapshots
+
+### Version 1.3.2
+* Fix queue autosubmission to fire if needed after #merge! calls
+
+### Version 1.3.1
+* Fix auto-chunking for large measurements sets with a global source
+
+### Version 1.3.0
+* Add support for working with sources as a first-class entity
+
+### Version 1.2.0
+* Give metric-facing methods more explicit names & deprecate priors
+* Documentation improvements
+
+### Version 1.1.1
+* Move gem sign code to rake task, fixes bug bundling in some environments
+
+### Version 1.1.0
+* Add ability to update annotation events
+* Add ability to fetch annotation events
+* Add block form of annotation
+* Add metric batch update support
+* Add support for pattern-based metric deletes
+* Add set of code examples
+* Sign gem when building
+* Documentation improvements
+
+### Version 1.0.4
+* Ensure sane default timeouts for all requests
+
+### Version 1.0.3
+* Fix bug where retries of POST requests could 400
+* Network related exceptions capture response state better
+
+### Version 1.0.2
+* Fix bug with some versions of MultiJson (Thomas Dippel)
+* Use delegation for JSON handling
+* Improve integration tests
+
+### Version 1.0.1
+* Fix Forwardable dependency loading bug
+
+### Version 1.0.0
+* Add support for annotation submission, listing, management
+* Auto-convert Time objects anywhere a time is accepted
+* Don't raise exception anymore for empty queue submission
+
+### Version 0.7.5
+* Catch a broader range of connection failures for retrying
+* Add Metrics.faraday_adapter config option (Mathieu Ravaux)
+
+### Version 0.7.4
+* Support global measure_time option for Queues/Aggregators
+* Support all versions of multi_json so we can relax version constraint
+
+### Version 0.7.3
+* Allow prefixes to be changed after instantiation on Queues/Aggregators
+
+### Version 0.7.2
+* Extend prefix option support to Aggregators
+
+### Version 0.7.1
+* Add prefix option to Queues
+
+### Version 0.7.0
+* Add ability to update metric properties (Christoph Bünte)
+* Add ability to merge queue and aggregator data into a queue
+* Aggregator supports custom source by measurement
+* Add option to clear queued measurements after failed submit
+* Custom user agent support
+* Documentation improvements
+
+### Version 0.6.1
+* Loosen restrictions to older versions of faraday and multi_json
+* Fix symbol casting issue in jruby with metric delete
+* client#new_queue now respects passed options
+* Queue objects support default source properly
+
+### Version 0.6.0
+* Add Aggregator class for aggregating measurements client-side
+* Queue and Aggregator can auto-submit on a time interval
+* Queue can auto-submit on a specified volume of measurements
+* Support deleting individual metrics
+* Validate user-specified measurement times
+* Update to MultiJSON 1.3 syntax
+* Run tests for rubinius and jruby in both 1.8 and 1.9 modes
+* Include request body in output for failed requests
+* Documentation improvements
+
+### Version 0.5.0
+* Support using multiple accounts simultaneously via Client
+* Switch network library to faraday for broader platform support and flexibility
+* Automatically break large submissions into multiple requests for better performance
+* Automatic retry support
+* Consolidate connection functions in Connection
+* Documentation improvements
+
+### Version 0.4.3
+* Bump excon to 0.13x to fix proxy support
+
+### Version 0.4.2
+* Fix SSL verify peer issues with JRuby (Sean Porter)
+
+### Version 0.4.1
+* Fix issues with auth encoding whitespace
+
+### Version 0.4.0
+* Add ability to set agent_identifier for use with developer program (Sean Porter)
+* Documentation improvements
+
+### Version 0.3.1
+* Upgrade excon to 0.9.5 to fix intermittent socket errors
+
+### Version 0.3.0
+* Add auto-pagination support to metric listing (Nuno Valente)
+* Add #size/#length to Queue objects (Michael Gorsuch)
+* Add #empty? to Queue objects
+* Remove deprecated .json extensions from API URIs
+* Use new singular route for metric GETs
+* README improvements
+* Add #clear as alias to Queue's #flush
+* Switch to multi_json for better cross-platform json handling
+* Set up basic integration testing suite
+* Improve testing rake tasks
+
+### Version 0.2.3
+* Fix broken user-agent string in 1.8.7 (Sean Porter)
+* Update outdated spec
+
+### Version 0.2.2
+* Fix abstract persistence instantiation in Ruby 1.8/REE
+
+### Version 0.2.1
+* Add better handling for start_time and end_time params when fetching measurements
+
+### Version 0.2.0
+* Fix bug with stale excon connections not reconnecting
+* Add custom User-Agent
+* Items added to Queue objects have their measure_time set automatically
+* Metric 'type' key can be string or symbol (Neil Mock)
+
+### Version 0.1.0
+* Initial release

data/Gemfile

@@ -0,0 +1,36 @@
+source "https://rubygems.org"
+
+platforms :jruby do
+  gem 'jruby-openssl'
+end
+
+platforms :ruby_19 do
+  # make available for yard under C rubies
+  gem 'redcarpet'
+end
+
+platforms :rbx do
+   # rubinius stdlib
+  gem 'rubysl', '~> 2.0'
+  gem 'rubinius-developer_tools'
+end
+
+gem 'rake'
+gem 'aggregate'
+gem 'faraday'
+
+# docs
+gem 'yard'
+
+# debugging
+gem 'pry'
+
+# easily generate test data
+gem 'quixote'
+
+group :test do
+  gem 'rspec', '~> 3.5.0'
+  gem 'sinatra'
+  gem 'popen4'
+  gem 'multi_json'
+end

data/LICENSE

@@ -0,0 +1,24 @@
+Copyright (c) 2017. Solarwinds, Inc.
+All rights reserved.
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+    * Redistributions of source code must retain the above copyright
+      notice, this list of conditions and the following disclaimer.
+    * Redistributions in binary form must reproduce the above copyright
+      notice, this list of conditions and the following disclaimer in the
+      documentation and/or other materials provided with the distribution.
+    * Neither the name of Solarwinds nor the names of project contributors
+      may be used to endorse or promote products derived from this software
+      without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
+ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
+WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL Solarwinds BE LIABLE FOR ANY
+DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
+(INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
+LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
+ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
+SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

data/README.md

@@ -0,0 +1,271 @@
+AppOptics API Ruby
+=======
+
+Ruby bindings for the AppOptics API
+
+This gem provides granular control for scripting interactions with the API. It is well suited for integrations, scripts, workers & background jobs.
+
+## Installation
+
+In your shell:
+
+    gem install appoptics-api-ruby
+
+Then, in your application or script:
+
+    require 'appoptics/metrics'
+
+### Optional steps
+
+For best performance we recommend installing [yajl-ruby](https://github.com/brianmario/yajl-ruby):
+
+    gem install yajl-ruby
+
+If you are using jruby, you need to ensure [jruby-openssl](https://github.com/jruby/jruby-ossl) is available:
+
+    gem install jruby-openssl
+
+## Quick Start
+
+If you are looking for the quickest possible route to getting a data into Metrics, you only need two lines:
+
+    Appoptics::Metrics.authenticate 'api_key'
+    Appoptics::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 AppOptics](https://www.appoptics.com/) and then authenticate with your email and API key (on your account page):
+
+    Appoptics::Metrics.authenticate 'api_key'
+
+
+## Sending Measurements
+
+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 metric named `temperature`:
+
+    queue = Appoptics::Metrics::Queue.new
+    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 = Appoptics::Metrics::Queue.new(tags: { service: 'auth', environment: 'prod', host: 'auth-prod-1' })
+    queue.add my_metric: 10
+    queue.submit
+
+### Per-Measurement Tags
+
+Optionally, you can submit per-measurement tags by passing a tags Hash when adding measurements:
+
+    queue.add my_other_metric: { value: 25, tags: { db: 'rr1' } }
+    queue.submit
+
+For more information, visit the [API documentation](https://docs.appoptics.com/api/#create-a-measurement).
+
+
+## Querying Metrics
+
+Get name and properties for all metrics you have in the system:
+
+    metrics = Appoptics::Metrics.metrics
+
+Get only metrics whose name includes `time`:
+
+    metrics = Appoptics::Metrics.metrics name: 'time'
+
+
+## Retrieving 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*"
+}
+Appoptics::Metrics.get_series :exceptions, query
+```
+
+For more information, visit the [API documentation](https://docs.appoptics.com/api/#retrieve-a-measurement).
+
+
+## Aggregate Measurements
+
+If you are measuring something very frequently e.g. per-request in a web application (order mS)  you may not want to send each individual measurement, but rather periodically send a [single aggregate measurement](https://docs.appoptics.com/api/#gauge-specific-parameters), spanning multiple seconds or even minutes. Use an `Aggregator` for this.
+
+Aggregate a simple gauge metric named `response_latency`:
+
+    aggregator = Appoptics::Metrics::Aggregator.new
+    aggregator.add response_latency: 85.0
+    aggregator.add response_latency: 100.5
+    aggregator.add response_latency: 150.2
+    aggregator.add response_latency: 90.1
+    aggregator.add response_latency: 92.0
+
+Which would result in a gauge measurement like:
+
+    {name: "response_latency", count: 5, sum: 517.8, min: 85.0, max: 150.2}
+
+You can specify a source during aggregate construction:
+
+    aggregator = Appoptics::Metrics::Aggregator.new(tags: { service: 'auth', environment: 'prod', host: 'auth-prod-1' })
+
+You can aggregate multiple metrics at once:
+
+    aggregator.add app_latency: 35.2, db_latency: 120.7
+
+Send the currently aggregated metrics to Metrics:
+
+    aggregator.submit
+
+## Benchmarking
+
+If you have operations in your application you want to record execution time for, both `Queue` and `Aggregator` support the `#time` method:
+
+    aggregator.time :my_measurement do
+      # do work...
+    end
+
+The difference between the two is that `Queue` submits each timing measurement individually, while `Aggregator` submits a single timing measurement spanning all executions.
+
+If you need extra attributes for a `Queue` timing measurement, simply add them on:
+
+    queue.time :my_measurement do
+      # do work...
+    end
+
+## Annotations
+
+Annotation streams are a great way to track events like deploys, backups or anything else that might affect your system. They can be overlaid on any other metric stream so you can easily see the impact of changes.
+
+At a minimum each annotation needs to be assigned to a stream and to have a title. Let's add an annotation for deploying `v45` of our app to the `deployments` stream:
+
+    Appoptics::Metrics.annotate :deployments, 'deployed v45'
+
+There are a number of optional fields which can make annotations even more powerful:
+
+    Appoptics::Metrics.annotate :deployments, 'deployed v46', source: 'frontend',
+        start_time: 1354662596, end_time: 1354662608,
+        description: 'Deployed 6f3bc6e67682: fix lotsa bugs…'
+
+You can also automatically annotate the start and end time of an action by using `annotate`'s block form:
+
+    Appoptics::Metrics.annotate :deployments, 'deployed v46' do
+      # do work..
+    end
+
+More fine-grained control of annotations is available via the `Annotator` object:
+
+    annotator = Appoptics::Metrics::Annotator.new
+
+    # list annotation streams
+    streams = annotator.list
+
+    # fetch a list of events in the last hour from a stream
+    annotator.fetch :deployments, start_time: (Time.now.to_i-3600)
+
+    # delete an event
+    annotator.delete_event 'deployments', 23
+
+See the documentation of `Annotator` for more details and examples of use.
+
+## Auto-Submitting Metrics
+
+Both `Queue` and `Aggregator` support automatically submitting measurements on a given time interval:
+
+	# submit once per minute
+	timed_queue = Appoptics::Metrics::Queue.new(autosubmit_interval: 60)
+
+	# submit every 5 minutes
+	timed_aggregator = Appoptics::Metrics::Aggregator.new(autosubmit_interval: 300)
+
+`Queue` also supports auto-submission based on measurement volume:
+
+	# submit when the 400th measurement is queued
+	volume_queue = Appoptics::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/appoptics/appoptics-api-ruby/blob/master/examples/submit_every.rb).
+
+## Setting Metric Properties
+
+Setting custom [properties](https://docs.appoptics.com/api/#metric-attributes) on your metrics is easy:
+
+    # assign a period and default color
+    Appoptics::Metrics.update_metric :temperature, period: 15, attributes: { color: 'F00' }
+
+## 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'
+	Appoptics::Metrics.delete_metrics :temperature, :humidity
+
+You can also delete using wildcards:
+
+    # delete metrics that start with cpu. except for cpu.free
+    Appoptics::Metrics.delete_metrics names: 'cpu.*', exclude: ['cpu.free']
+
+Note that deleted metrics and their measurements are unrecoverable, so use with care.
+
+## Using Multiple Accounts Simultaneously
+
+If you need to use metrics with multiple sets of authentication credentials simultaneously, you can do it with `Client`:
+
+    joe = Appoptics::Metrics::Client.new
+    joe.authenticate 'api_key1'
+
+    mike = Appoptics::Metrics::Client.new
+    mike.authenticate 'api_key2'
+
+All of the same operations you can call directly from `Appoptics::Metrics` are available per-client:
+
+	# list Joe's metrics
+	joe.metrics
+
+There are two ways to associate a new queue with a client:
+
+	# these are functionally equivalent
+	joe_queue = Appoptics::Metrics::Queue.new(client: joe)
+	joe_queue = joe.new_queue
+
+Once the queue is associated you can use it normally:
+
+	joe_queue.add temperature: { value: 65.2, tags: { city: 'san francisco' } }
+	joe_queue.submit
+
+## Thread Safety
+
+The `appoptics-api-ruby` 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
+
+`appoptics-api-ruby` 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/appoptics/appoptics-api-ruby) for more.
+
+We also maintain a set of [examples of common uses](https://github.com/appoptics/appoptics-api-ruby/tree/master/examples) and appreciate contributions if you have them.
+
+## Contribution
+
+* Check out the latest master to make sure the feature hasn't been implemented or the bug hasn't been fixed yet.
+* Check out the issue tracker to make sure someone already hasn't requested it and/or contributed it.
+* Fork the project and submit a pull request from a feature or bugfix branch.
+* Please review our [code conventions](https://github.com/appoptics/appoptics-api-ruby/wiki/Code-Conventions).
+* Please include specs. This is important so we don't break your changes unintentionally in a future version.
+* Please don't modify the gemspec, Rakefile, version, or changelog. If you do change these files, please isolate a separate commit so we can cherry-pick around it.
+
+## Copyright
+
+Copyright (c) 2011-2017 [Solarwinds, Inc.](http://www.solarwinds.com) See LICENSE for details.