metrics 0.14.0 → 0.14.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d09fc9e1904cb72737025a01e68a6ad963fb05bfb6dc02dce39987a6b7a4877b
-  data.tar.gz: aff1567553de8db5cce01a4c0d51dc2dbf5dadc28fa34c66df7c1d390d539a93
+  metadata.gz: '08437830e8e7643c85176e29fbb2f3c6290efff4537b37e529b76c6d8d602bce'
+  data.tar.gz: 1037cc6943319a6a64d5f5ed35224efeda1fd51616bc4df3fb5f718f095e0f4e
 SHA512:
-  metadata.gz: b937797ed321ef56736eff66f632a721c29fdceec34c11d863799f24abcf237c2282f49294b3b7bec95a9538350d7ef6f591eb8b87e19bc5eefd10e000a24e10
-  data.tar.gz: 94bff04a35790e6e6f077745a47702c80803a6e01bf6e4a8d3d4d284d14b23051ee3836b714e3d8774c94f653dbe4f725b208199c9a8f577d0732c6e6cb527e3
+  metadata.gz: 74597bc51d38149c561b6447811abdd53bbde539ee1011fcd8faff35aa758dfdbc30525696c5916b00cfd54ec9e0ae9c0058711753e2a9def2ed49a58674cd00
+  data.tar.gz: 596b37c40c112acae9c232894cc155ca421a499e0f5665bfb5281ff88382bfe5e267a52f795f68a54b20882e9c7d7d8763dcc2872c3ae90339279e5d80df589e

data/context/capture.md

@@ -0,0 +1,57 @@
+# Capture
+
+This guide explains how to use `metrics` for exporting metric definitions from your application.
+
+## With Provider Metrics
+
+If your application defines one or more metrics, you can export them using the `bake metrics:document` command. This command will generate a list of metrics which you can export.
+
+```bash
+$ cd test/metrics/backend/.capture/
+$ bake metrics:capture environment metrics:capture:list output --format json
+[
+  {
+    "name": "my_metric",
+    "type": "gauge",
+    "description": "My metric",
+    "unit": "seconds",
+    "values": [
+
+    ],
+    "tags": [
+
+    ],
+    "sample_rates": [
+
+    ]
+  }
+]
+```
+
+## With Test Suite
+
+If your application has a test suite which emits metrics, you can capture those as samples for the purpose of your documentation. This includes fields like tags.
+
+```bash
+$ cd test/metrics/backend/.capture/
+$ bake metrics:capture run metrics:capture:list output --format json
+[
+  {
+    "name": "my_metric",
+    "type": "gauge",
+    "description": "My metric",
+    "unit": "seconds",
+    "values": [
+      1
+    ],
+    "tags": [
+      "environment:test"
+    ],
+    "sample_rates": [
+      1.0
+    ]
+  }
+]
+```
+
+This uses a custom task called `run` in the above example, but you should probably consider using `bake test` which runs your test suite.

data/context/getting-started.md

@@ -0,0 +1,93 @@
+# Getting Started
+
+This guide explains how to use `metrics` for capturing run-time metrics.
+
+## Installation
+
+Add the gem to your project:
+
+~~~ bash
+$ bundle add metrics
+~~~
+
+## Core Concepts
+
+`metrics` has several core concepts:
+
+- A {ruby Metrics::Provider} which implements custom logic for extracting metrics from existing code.
+- A {ruby Metrics::Backend} which connects metrics to a specific backend system for processing.
+
+## Usage
+
+There are two main aspects to integrating within this gem.
+
+1. Libraries and applications must expose metrics.
+2. Those metrics must be consumed or emitted somewhere.
+
+### Exposing Metrics
+
+Adding metrics to libraries requires the use of {ruby Metrics::Provider}:
+
+~~~ ruby
+require 'metrics'
+
+class MyClass
+	def my_method
+		puts "Hello World"
+	end
+end
+
+# If metrics are disabled, this is a no-op.
+Metrics::Provider(MyClass) do
+	CALL_COUNT = Metrics.metric('call_count', :counter, description: 'Number of times invoked.')
+	
+	def my_method
+		CALL_COUNT.emit(1)
+		
+		super
+	end
+end
+
+MyClass.new.my_method
+~~~
+
+This code by itself will not create any metrics. In order to execute it and output metrics, you must set up a backend to consume them.
+
+#### Class Methods
+
+You can also expose metrics for class methods:
+
+~~~ ruby
+require 'metrics'
+
+class MyClass
+	def self.my_method
+		puts "Hello World"
+	end
+end
+
+Metrics::Provider(MyClass.singleton_class) do
+	CALL_COUNT = Metrics.metric('call_count', :counter, description: 'Number of times invoked.')
+	
+	def my_method
+		CALL_COUNT.emit(1)
+		
+		super
+	end
+end
+
+MyClass.my_method
+~~~
+
+### Consuming Metrics
+
+Consuming metrics means proving a backend implementation which can record those metrics to some log or service. There are several options, but two backends are included by default:
+
+- `metrics/backend/test` does not emit any metrics, but validates the usage of the metric interface.
+- `metrics/backend/console` emits metrics using the [`console`](https://github.com/socketry/console) gem.
+
+In order to use a specific backend, set the `METRICS_BACKEND` environment variable, e.g.
+
+~~~ shell
+$ METRICS_BACKEND=metrics/backend/console ./my_script.rb
+~~~

data/context/index.yaml

@@ -0,0 +1,19 @@
+# Automatically generated context index for Utopia::Project guides.
+# Do not edit then files in this directory directly, instead edit the guides and then run `bake utopia:project:agent:context:update`.
+---
+description: Application metrics and instrumentation.
+metadata:
+  documentation_uri: https://socketry.github.io/metrics/
+  source_code_uri: https://github.com/socketry/metrics.git
+files:
+- path: getting-started.md
+  title: Getting Started
+  description: This guide explains how to use `metrics` for capturing run-time metrics.
+- path: capture.md
+  title: Capture
+  description: This guide explains how to use `metrics` for exporting metric definitions
+    from your application.
+- path: testing.md
+  title: Testing
+  description: This guide explains how to write assertions in your test suite to validate
+    `metrics` are being emitted correctly.

data/context/testing.md

@@ -0,0 +1,43 @@
+# Testing
+
+This guide explains how to write assertions in your test suite to validate `metrics` are being emitted correctly.
+
+## Application Code
+
+In your application code, you should emit metrics, e.g.
+
+```ruby
+require 'metrics/provider'
+
+class MyApplication
+	def work
+		# ...
+	end
+	
+	Metrics::Provider(self) do
+		WORK_METRIC = Metrics.metric('my_application.work.count', :counter, description: 'Work counter')
+		
+		def work
+			WORK_METRIC.emit(1)
+			super
+		end
+	end
+end
+```
+
+## Test Code
+
+In your test code, you should assert that the metrics are being emitted correctly, e.g.
+
+```ruby
+ENV['METRICS_BACKEND'] ||= 'metrics/backend/test'
+
+require_relative 'app'
+
+describe MyApplication do
+	it 'should emit metrics' do
+		expect(MyApplication::WORK_METRIC).to receive(:emit).with(1)
+		MyApplication.new.work
+	end
+end
+```

data/lib/metrics/provider.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 # Released under the MIT License.
-# Copyright, 2021-2024, by Samuel Williams.
+# Copyright, 2021-2025, by Samuel Williams.
 
 require_relative "backend"
 

data/lib/metrics/version.rb

@@ -4,5 +4,5 @@
 # Copyright, 2021-2025, by Samuel Williams.
 
 module Metrics
-	VERSION = "0.14.0"
+	VERSION = "0.14.1"
 end

data/lib/metrics.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 # Released under the MIT License.
-# Copyright, 2021-2024, by Samuel Williams.
+# Copyright, 2021-2025, by Samuel Williams.
 
 require_relative "metrics/version"
 require_relative "metrics/provider"

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: metrics
 version: !ruby/object:Gem::Version
-  version: 0.14.0
+  version: 0.14.1
 platform: ruby
 authors:
 - Samuel Williams
@@ -44,6 +44,10 @@ extra_rdoc_files: []
 files:
 - bake/metrics/capture.rb
 - bake/metrics/provider.rb
+- context/capture.md
+- context/getting-started.md
+- context/index.yaml
+- context/testing.md
 - lib/metrics.rb
 - lib/metrics/backend.rb
 - lib/metrics/backend/capture.rb