ddmetrics 1.0.0rc1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: e96210a080bfe9dbf1c20f2a5f55e9eb1229e5f98387d0872525183d2425020f
+  data.tar.gz: 5fedbc494b37439e8fddcab62c1a204ed42f39caca85a9c0a3b40f6901e404c8
+SHA512:
+  metadata.gz: 15e3710ac05fe1d383bc7dfcc03c95184179f5ba0888c07c7050e8d42e1588b2bab01193233df2116ed4cb58578f237472937f90afbf985ef2315d4326cfab6b
+  data.tar.gz: 6ec53e7fffc7cdf67cae32191f312881fa9db810f2afabcf57fdb2d82f251fccdcc91a92ab67dda70d9b27313e3d6567d96a1898f335cbb3a5bd0354d98d4cfd

data/.gitignore

@@ -0,0 +1,5 @@
+.DS_Store
+*.gem
+/.vscode/
+/coverage/
+/Gemfile.lock

data/.rspec

@@ -0,0 +1,3 @@
+-r ./spec/spec_helper.rb
+--format Fuubar
+--color

data/.rubocop.yml

@@ -0,0 +1,59 @@
+# ----- CONFIGURED -----
+
+AllCops:
+  TargetRubyVersion: 2.3
+  DisplayCopNames: true
+
+Style/TrailingCommaInArguments:
+  EnforcedStyleForMultiline: comma
+
+Style/TrailingCommaInLiteral:
+  EnforcedStyleForMultiline: comma
+
+Layout/IndentArray:
+  EnforcedStyle: consistent
+
+# Documentation lives elsewhere, and not everything needs to be documented.
+Style/Documentation:
+  Enabled: false
+
+# This doesn’t work well with RSpec.
+Lint/AmbiguousBlockAssociation:
+  Exclude:
+    - spec/**/*_spec.rb
+
+
+
+# ----- DISABLED (metrics) -----
+
+# Cops for metrics are disabled because they should not cause tests to fail.
+
+Metrics/AbcSize:
+  Enabled: false
+
+Metrics/BlockLength:
+  Enabled: false
+
+Metrics/BlockNesting:
+  Enabled: false
+
+Metrics/ClassLength:
+  Enabled: false
+
+Metrics/CyclomaticComplexity:
+  Enabled: false
+
+Metrics/LineLength:
+  Enabled: false
+
+Metrics/MethodLength:
+  Enabled: false
+
+Metrics/ModuleLength:
+  Enabled: false
+
+Metrics/ParameterLists:
+  Enabled: false
+
+Metrics/PerceivedComplexity:
+  Enabled: false

data/.travis.yml

@@ -0,0 +1,21 @@
+language: ruby
+
+rvm:
+  - "2.3"
+  - "2.4"
+  - "2.5"
+
+branches:
+  only:
+    - "master"
+
+before_install:
+  - gem update --system
+  - gem install bundler -v 1.16.0
+
+cache: bundler
+
+sudo: false
+
+git:
+  depth: 10

data/CODE_OF_CONDUCT.md

@@ -0,0 +1,74 @@
+# Contributor Covenant Code of Conduct
+
+## Our Pledge
+
+In the interest of fostering an open and welcoming environment, we as
+contributors and maintainers pledge to making participation in our project and
+our community a harassment-free experience for everyone, regardless of age, body
+size, disability, ethnicity, gender identity and expression, level of experience,
+nationality, personal appearance, race, religion, or sexual identity and
+orientation.
+
+## Our Standards
+
+Examples of behavior that contributes to creating a positive environment
+include:
+
+* Using welcoming and inclusive language
+* Being respectful of differing viewpoints and experiences
+* Gracefully accepting constructive criticism
+* Focusing on what is best for the community
+* Showing empathy towards other community members
+
+Examples of unacceptable behavior by participants include:
+
+* The use of sexualized language or imagery and unwelcome sexual attention or
+advances
+* Trolling, insulting/derogatory comments, and personal or political attacks
+* Public or private harassment
+* Publishing others' private information, such as a physical or electronic
+  address, without explicit permission
+* Other conduct which could reasonably be considered inappropriate in a
+  professional setting
+
+## Our Responsibilities
+
+Project maintainers are responsible for clarifying the standards of acceptable
+behavior and are expected to take appropriate and fair corrective action in
+response to any instances of unacceptable behavior.
+
+Project maintainers have the right and responsibility to remove, edit, or
+reject comments, commits, code, wiki edits, issues, and other contributions
+that are not aligned to this Code of Conduct, or to ban temporarily or
+permanently any contributor for other behaviors that they deem inappropriate,
+threatening, offensive, or harmful.
+
+## Scope
+
+This Code of Conduct applies both within project spaces and in public spaces
+when an individual is representing the project or its community. Examples of
+representing a project or community include using an official project e-mail
+address, posting via an official social media account, or acting as an appointed
+representative at an online or offline event. Representation of a project may be
+further defined and clarified by project maintainers.
+
+## Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be
+reported by contacting the project team at denis.defreyne@stoneship.org. All
+complaints will be reviewed and investigated and will result in a response that
+is deemed necessary and appropriate to the circumstances. The project team is
+obligated to maintain confidentiality with regard to the reporter of an incident.
+Further details of specific enforcement policies may be posted separately.
+
+Project maintainers who do not follow or enforce the Code of Conduct in good
+faith may face temporary or permanent repercussions as determined by other
+members of the project's leadership.
+
+## Attribution
+
+This Code of Conduct is adapted from the [Contributor Covenant][homepage], version 1.4,
+available at [http://contributor-covenant.org/version/1/4][version]
+
+[homepage]: http://contributor-covenant.org
+[version]: http://contributor-covenant.org/version/1/4/

data/Gemfile

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+source 'https://rubygems.org'
+
+gemspec
+
+group :devel do
+  gem 'codecov', require: false
+  gem 'fuubar'
+  gem 'rake'
+  gem 'rspec'
+  gem 'rspec-its'
+  gem 'rubocop', '~> 0.52'
+  gem 'timecop', '~> 0.9'
+end

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2017 Denis Defreyne
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/NEWS.md

@@ -0,0 +1,23 @@
+# DDMetrics news
+
+## 1.0.0rc1 (2018-01-04)
+
+Changes:
+
+* Renamed to DDMetrics (from DDTelemetry)
+
+## 1.0.0a3 (2017-12-25)
+
+Changes:
+
+* Made labels be a hash
+
+## 1.0.0a2 (2017-12-18)
+
+Changes:
+
+* Many API changes to make usage simpler
+
+## 1.0.0a1 (2017-12-02)
+
+Initial release.

data/README.md

@@ -0,0 +1,260 @@
+[![Gem version](https://img.shields.io/gem/v/ddmetrics.svg)](http://rubygems.org/gems/ddmetrics)
+[![Gem downloads](https://img.shields.io/gem/dt/ddmetrics.svg)](http://rubygems.org/gems/ddmetrics)
+[![Build status](https://img.shields.io/travis/ddfreyne/ddmetrics.svg)](https://travis-ci.org/ddfreyne/ddmetrics)
+[![Code Climate](https://img.shields.io/codeclimate/github/ddfreyne/ddmetrics.svg)](https://codeclimate.com/github/ddfreyne/ddmetrics)
+[![Code Coverage](https://img.shields.io/codecov/c/github/ddfreyne/ddmetrics.svg)](https://codecov.io/gh/ddfreyne/ddmetrics)
+
+# DDMetrics
+
+_DDMetrics_ is a Ruby library for recording and analysing measurements in short-running Ruby processes.
+
+If you are looking for a full-featured timeseries monitoring system, look no further than [Prometheus](https://prometheus.io/).
+
+## Example
+
+Take the following (naïve) cache implementation as a starting point:
+
+```ruby
+class Cache
+  def initialize
+    @map = {}
+  end
+
+  def []=(key, value)
+    @map[key] = value
+  end
+
+  def [](key)
+    @map[key]
+  end
+end
+```
+
+To start instrumenting this code, require `ddmetrics`, create a counter, and record some metrics:
+
+```ruby
+require 'ddmetrics'
+
+class Cache
+  attr_reader :counter
+
+  def initialize
+    @map = {}
+    @counter = DDMetrics::Counter.new
+  end
+
+  def []=(key, value)
+    @counter.increment(type: :set)
+
+    @map[key] = value
+  end
+
+  def [](key)
+    if @map.key?(key)
+      @counter.increment(type: :get_hit)
+    else
+      @counter.increment(type: :get_miss)
+    end
+
+    @map[key]
+  end
+end
+```
+
+Let’s construct a cache and exercise it:
+
+```ruby
+cache = Cache.new
+
+cache['greeting']
+cache['greeting']
+cache['greeting'] = 'Hi there!'
+cache['greeting']
+cache['greeting']
+cache['greeting']
+```
+
+Finally, get the recorded values:
+
+```ruby
+cache.counter.get(type: :set)      # => 1
+cache.counter.get(type: :get_hit)  # => 3
+cache.counter.get(type: :get_miss) # => 2
+```
+
+Or even print all stats:
+
+```ruby
+puts cache.counter
+```
+
+```
+              │ count
+──────────────┼──────
+type=get_miss │     2
+     type=set │     1
+ type=get_hit │     3
+```
+
+## Scope
+
+* No timeseries: Metrics are not recorded over time. If you want to record timeseries data, consider using [Prometheus](https://prometheus.io/).
+
+* Not intended for long-running processes: Metrics data (particularly summary metrics) can accumulate in memory and cause memory pressure. This project is not suited for long-running processes, such as servers. For monitoring long-running processes, consider using [Prometheus](https://prometheus.io/).
+
+* Not thread-safe: The implementation is not thread-safe. If you require thread safety, consider wrapping the functionality provided.
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'ddmetrics'
+```
+
+And then execute:
+
+    $ bundle
+
+Or install it yourself as:
+
+    $ gem install ddmetrics
+
+## Usage
+
+_DDMetrics_ provides two metric types:
+
+* A **counter** is an integer metric that only ever increases. Examples: cache hits, number of files written, …
+
+* A **summary** records observations, and provides functionality for describing the distribution of the observations through quantiles. Examples: outgoing request durations, size of written files, …
+
+Each metric is recorded with a label, which is a hash that is useful to further refine the kind of data that is being recorded. For example:
+
+```ruby
+cache_hits_counter.increment(target: :file_cache)
+request_durations_summary.observe(1.07, api: :weather)
+```
+
+### Counters
+
+To create a counter, instantiate `DDMetrics::Counter`:
+
+```ruby
+counter = DDMetrics::Counter.new
+```
+
+To increment a counter, call `#increment` with a label:
+
+```ruby
+counter.increment(target: :file_cache)
+```
+
+To get the value for a certain label, use `#get`:
+
+```ruby
+counter.get(target: :file_cache)
+# => 1
+```
+
+### Summaries
+
+To create a summary, instantiate `DDMetrics::Summary`:
+
+```ruby
+summary = DDMetrics::Summary.new
+```
+
+To observe a value, call `#observe` with the value to observe, along with a label:
+
+```ruby
+summary.observe(0.88, api: :weather)
+summary.observe(1.07, api: :weather)
+summary.observe(0.91, api: :weather)
+```
+
+To get the list of observations for a certain label, use `#get`, which will return a `DDMetrics::Stats` instance:
+
+```ruby
+summary.get(api: :weather)
+# => <DDMetrics::Stats>
+```
+
+The following methods are available on `DDMetrics::Stats`:
+
+* `#count`: returns the number of values
+* `#sum`: returns the sum of all values
+* `#avg`: returns the average of all values
+* `#min`: returns the minimum value
+* `#max`: returns the maximum value
+* `#quantile(fraction)`: returns the quantile at the given fraction (0.0 – 1.0)
+
+### Printing metrics
+
+To print a metric, use `#to_s`. For example:
+
+```ruby
+summary = DDMetrics::Summary.new
+
+summary.observe(2.1, filter: :erb)
+summary.observe(4.1, filter: :erb)
+summary.observe(5.3, filter: :haml)
+
+puts summary
+```
+
+Output:
+
+```
+            │ count    min    .50    .90    .95    max    tot
+────────────┼────────────────────────────────────────────────
+ filter=erb │     2   2.10   3.10   3.90   4.00   4.10   6.20
+filter=haml │     1   5.30   5.30   5.30   5.30   5.30   5.30
+```
+
+### Stopwatch
+
+The `DDMetrics::Stopwatch` class can be used to measure durations. Use `#start` and `#stop` to start and stop the stopwatch, respectively, and `#duration` to read the value of the stopwatch:
+
+```ruby
+stopwatch = DDMetrics::Stopwatch.new
+
+stopwatch.start
+sleep 1
+stopwatch.stop
+puts "That took #{stopwatch.duration}s."
+# Output: That took 1.006831s.
+```
+
+A stopwatch, once created, will never reset its duration. Running the stopwatch again will add to the existing duration:
+
+```ruby
+stopwatch.start
+sleep 1
+stopwatch.stop
+puts "That took #{stopwatch.duration}s."
+# Output: That took 2.012879s.
+```
+
+You can query whether or not a stopwatch is running using `#running?`; `#stopped?` is the opposite of `#running?`.
+
+## Development
+
+Install dependencies:
+
+    $ bundle
+
+Run tests:
+
+    $ bundle exec rake
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/ddfreyne/ddmetrics. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [Contributor Covenant](http://contributor-covenant.org) code of conduct.
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](http://opensource.org/licenses/MIT).
+
+## Code of Conduct
+
+Everyone interacting in the DDMetrics project’s codebases, issue trackers, chat rooms and mailing lists is expected to follow the [code of conduct](https://github.com/ddfreyne/ddmetrics/blob/master/CODE_OF_CONDUCT.md).