module Barnes

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

CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION

WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION

WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION

WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION

WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION

WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

A note on GAUGE_COUNTERS.

The sample_rate argument allows for the parameterization of instruments that decide to report data as gauges, that would typically be reported as counters.

Aggregating counters is typically done simply with the `+` operator, which doesn't preserve the number of unique reporters that contributed to the count, or allow for one to learn the average of the counts posted.

A gauge is typically aggregated by simply replacing the previous value, however, some systems do more with gauges when aggregating across multiple sources of that gauge, like, average, or compute stdev.

This is problematic, however, when a gauge is being used as a counter, to preserve the average / stdev computational properties from above, because the interval that the gauge is being read it, affects the derivative of the increasing count. Instead of the derivative over 60s, the derivative is taken every 10s, giving us a derivative value that's approximately 1/6th of the actual derivative over 60s.

We compensate for this by allowing Instruments to correct for this, and ensure that, even though it's an estimate, the data is scaled appropriately to the target aggregation interval, not just the collection interval.

CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION

WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION

WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION

WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION

WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

Constants

DEFAULT_AGGREGATION_PERIOD
DEFAULT_INTERVAL
DEFAULT_PANELS
DEFAULT_STATSD
GAUGES
VERSION

Public Class Methods

start(interval: DEFAULT_INTERVAL, aggregation_period: DEFAULT_AGGREGATION_PERIOD, statsd: DEFAULT_STATSD, panels: DEFAULT_PANELS) click to toggle source

Starts the reporting client

Arguments:

- interval: How often, in seconds, to instrument and report
- aggregation_period: The minimal aggregation period in use, in seconds.
- statsd: The statsd reporter. This should be an instance of statsd-ruby
- panels: The instrumentation "panels" in use. See `resource_usage.rb` for
  an example panel, which is the default if none are provided.

# File lib/barnes.rb, line 40
def self.start(interval: DEFAULT_INTERVAL, aggregation_period: DEFAULT_AGGREGATION_PERIOD, statsd: DEFAULT_STATSD, panels: DEFAULT_PANELS)
  require 'statsd'
  statsd_client = statsd
  panels        = panels
  sample_rate   = interval.to_f / aggregation_period.to_f

  if statsd_client == :default && ENV["PORT"]
    statsd_client = Statsd.new('127.0.0.1', ENV["PORT"])
  end

  if statsd_client && statsd_client != :default
    reporter = Barnes::Reporter.new(statsd: statsd_client, sample_rate: sample_rate)

    unless panels.length > 0
      panels << Barnes::ResourceUsage.new(sample_rate)
    end

    Periodic.new(
      reporter:    reporter,
      sample_rate: sample_rate,
      panels:      panels,
      debug:       ENV['BARNES_DEBUG']
    )
  end
end