aws-embedded-metrics-customink 0.6.0 → 0.8.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b07c505a8d7790b89bff615c824567402f3e6b613287753ea5b7fe930614ce8b
-  data.tar.gz: cd42f99bccbd143a40acdd8f7ec91e442d3fc2c6475397179561c78482e9a2de
+  metadata.gz: 1cc2867474c435e6c5de18f3c599aeffd9f589b0164e9659fecf4d26ecda8478
+  data.tar.gz: a5a7bd3e0c2f4bf710343e1f54707d69a79c889ecf38025ac9106b7fcac44cd0
 SHA512:
-  metadata.gz: 8de84739de64092a2998196e7a5348ad2a8339282eb7fdc7dfbb0773096dd70fd8ef77e853e8a812075c3d6ef2cddd74fdb9cb629643bb0efabd9fe9a8168582
-  data.tar.gz: 9892885a4debc5335e8c43cecc687e4107c8ac52efb046cb82b12c3d12c0529a40c23d73e4b9539ca51b94b6de6dfd805f417136f68a6a3551ddc684e85f72a9
+  metadata.gz: e4021d0eb717b34bd6f25421c4fc39ea65138570ace643fabdd2eac2551155314310eb2c44f7bd2755bd4a70ea51e6dde4d12e68c629b492a0e05ae9c1a87bea
+  data.tar.gz: d41ed4bf3b8ba2f0b3cbcb5d8eb5bef2b4e214cf41ce61deb151cefdb206db7a94eda3f6a3886dcff9d615a26a58be0901f6913bb7345151ddbb0c8943a0c98c

data/CHANGELOG.md

@@ -3,6 +3,22 @@
 
 See this http://keepachangelog.com link for information on how we want this documented formatted.
 
+## v0.8.0
+
+### Added
+
+- New TCP Sink. 
+- Support for `LogGroupName` and `LogStreamName`. 
+- New `Metrics::Units` constants.
+
+## v0.7.0
+
+### Added
+
+- A new `Tcp` sink is added. The `Tcp` sink can send EMF messages to any valid TCP endpoint.
+- `tcp-client` will be required at runtime if you use the `Tcp` sink. Originally a small hand-written TCP client was used but it proved unreliable and well outside the scope of this library.
+- Added the new `Units` class for easy reference to the accepted metric units.
+
 ## v0.6.0
 
 ### Fixed

data/Gemfile

@@ -8,4 +8,5 @@ gem 'rubocop'
 group :test do
   gem 'mocha'
   gem 'pry'
+  gem 'tcp-client'
 end

data/Gemfile.lock

@@ -1,41 +1,46 @@
 PATH
   remote: .
   specs:
-    aws-embedded-metrics-customink (0.6.0)
+    aws-embedded-metrics-customink (0.8.0)
       concurrent-ruby
 
 GEM
   remote: https://rubygems.org/
   specs:
-    ast (2.4.1)
+    ast (2.4.2)
     coderay (1.1.3)
-    concurrent-ruby (1.1.7)
+    concurrent-ruby (1.1.10)
+    json (2.6.3)
     method_source (1.0.0)
-    minitest (5.14.1)
-    mocha (1.11.2)
-    parallel (1.19.2)
-    parser (2.7.1.4)
+    minitest (5.17.0)
+    mocha (2.0.2)
+      ruby2_keywords (>= 0.0.5)
+    parallel (1.22.1)
+    parser (3.2.0.0)
       ast (~> 2.4.1)
-    pry (0.13.1)
+    pry (0.14.2)
       coderay (~> 1.1)
       method_source (~> 1.0)
-    rainbow (3.0.0)
-    rake (13.0.1)
-    regexp_parser (1.7.1)
-    rexml (3.2.3)
-    rubocop (0.88.0)
+    rainbow (3.1.1)
+    rake (13.0.6)
+    regexp_parser (2.6.1)
+    rexml (3.2.5)
+    rubocop (1.43.0)
+      json (~> 2.3)
       parallel (~> 1.10)
-      parser (>= 2.7.1.1)
+      parser (>= 3.2.0.0)
       rainbow (>= 2.2.2, < 4.0)
-      regexp_parser (>= 1.7)
-      rexml
-      rubocop-ast (>= 0.1.0, < 1.0)
+      regexp_parser (>= 1.8, < 3.0)
+      rexml (>= 3.2.5, < 4.0)
+      rubocop-ast (>= 1.24.1, < 2.0)
       ruby-progressbar (~> 1.7)
-      unicode-display_width (>= 1.4.0, < 2.0)
-    rubocop-ast (0.2.0)
-      parser (>= 2.7.0.1)
-    ruby-progressbar (1.10.1)
-    unicode-display_width (1.7.0)
+      unicode-display_width (>= 2.4.0, < 3.0)
+    rubocop-ast (1.24.1)
+      parser (>= 3.1.1.0)
+    ruby-progressbar (1.11.0)
+    ruby2_keywords (0.0.5)
+    tcp-client (0.11.4)
+    unicode-display_width (2.4.2)
 
 PLATFORMS
   ruby
@@ -47,6 +52,7 @@ DEPENDENCIES
   pry
   rake
   rubocop
+  tcp-client
 
 BUNDLED WITH
-   2.1.2
+   2.3.5

data/README.md

@@ -13,10 +13,8 @@ Pulled from these two projects using the [Embedded Metric Format Specification](
 
 However, unlike these projects, we differ in the following ways. Again, contributions are very much welcome if you want to see more or change this.
 
-* Initial focus on Lambda. No other sinks.
-* As such, no default Dimensions or Configuraiton for:
-  - `LogGroupName`
-  - `LogStreamName`
+* Initial focus on Lambda. A TCP sink has been added, but no UDP sink exists.
+* No default Dimensions or Configuration for:
   - `ServiceName`
   - `ServiceType`
 
@@ -29,11 +27,19 @@ gem 'aws-embedded-metrics-customink'
 ```
 ## Usage
 
+If using outside of Rails, require the gem:
+```ruby
+require 'aws-embedded-metrics-customink'
+```
+
 Simple configuration:
 
 ```ruby
 Aws::Embedded::Metrics.configure do |c|
   c.namespace = 'MyApplication'
+  # Optional
+  c.log_group_name = 'MyLogGroup'
+  c.log_stream_name = 'MyLogStream-UniqueID' 
 end
 ```
 
@@ -45,6 +51,15 @@ Aws::Embedded::Metrics.configure do |c|
 end
 ```
 
+Using the `Tcp` sink to write over a network:
+
+```ruby
+Aws::Embedded::Metrics.configure do |c|
+  c.sink = Aws::Embedded::Metrics::Sinks::Tcp.new(conn_str: "tcp://localhost:25888",
+                                                  logger: Rails.logger)
+end
+```
+
 Usage is in a scope block. All metrics are flushed afterward
 
 ```ruby

data/lib/aws-embedded-metrics-customink/config.rb

@@ -22,7 +22,10 @@ module Aws
 
         class Configuration
 
-          attr_writer :namespace, :sink
+          attr_writer :log_group_name,
+                      :log_stream_name,
+                      :namespace,
+                      :sink
 
           def reconfigure
             instance_variables.each { |var| instance_variable_set var, nil }
@@ -30,16 +33,27 @@ module Aws
             self
           end
 
+          def log_group_name
+            return @log_group_name if defined?(@log_group_name)
+
+            ENV.fetch('AWS_EMF_LOG_GROUP_NAME', nil)
+          end
+
+          def log_stream_name
+            return @log_stream_name if defined?(@log_stream_name)
+
+            ENV.fetch('AWS_EMF_LOG_STREAM_NAME', nil)
+          end
+
           def namespace
             return @namespace if defined?(@namespace)
 
-            ENV['AWS_EMF_NAMESPACE'] || 'aws-embedded-metrics'
+            ENV.fetch('AWS_EMF_NAMESPACE', 'aws-embedded-metrics')
           end
 
           def sink
             @sink ||= DEFAULT_SINK.new
           end
-
         end
       end
     end

data/lib/aws-embedded-metrics-customink/logger.rb

@@ -5,6 +5,8 @@ module Aws
 
         def initialize(sink = Config.config.sink)
           @sink = sink
+          @log_group_name = Config.config.log_group_name
+          @log_stream_name = Config.config.log_stream_name
           @namespace = Config.config.namespace
           @dimensions = Concurrent::Array.new
           @metrics = Concurrent::Array.new
@@ -50,17 +52,20 @@ module Aws
         end
 
         def message
+          aws = {
+            'Timestamp' => timestamp,
+            'CloudWatchMetrics' => [{
+              'Namespace' => @namespace,
+              'Dimensions' => [@dimensions.map(&:keys).flatten],
+              'Metrics' => @metrics
+            }]
+          }
+
+          aws['LogGroupName'] = @log_group_name if @log_group_name
+          aws['LogStreamName'] = @log_stream_name if @log_stream_name
+
           {
-            '_aws' => {
-              'Timestamp' => timestamp,
-              'CloudWatchMetrics' => [
-                {
-                  'Namespace' => @namespace,
-                  'Dimensions' => [@dimensions.map(&:keys).flatten],
-                  'Metrics' => @metrics
-                }
-              ]
-            }
+            '_aws' => aws
           }.tap do |m|
             @dimensions.each { |dim| m.merge!(dim) }
             m.merge!(@properties)

data/lib/aws-embedded-metrics-customink/sinks/sink_error.rb

@@ -0,0 +1,9 @@
+module Aws
+  module Embedded
+    module Metrics
+      module Sinks
+        class Error < StandardError; end
+      end
+    end
+  end
+end

data/lib/aws-embedded-metrics-customink/sinks/tcp.rb

@@ -0,0 +1,93 @@
+# frozen_string_literal: true
+
+gem 'tcp-client'
+require 'tcp-client'
+
+module Aws
+  module Embedded
+    module Metrics
+      module Sinks
+        #
+        # Create a sink that will communicate to a CloudWatch Log Agent over a TCP connection.
+        #
+        # See https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/CloudWatch_Embedded_Metric_Format_Generation_CloudWatch_Agent.html
+        # for configuration information
+        class Tcp
+          AWS_EMF_AGENT_ENDPOINT_ENV_VAR = 'AWS_EMF_AGENT_ENDPOINT'
+          attr_reader :queue
+          attr :client_opts
+
+          #
+          # Create a new TCP sink. It will use the +AWS_EMF_AGENT_ENDPOINT+ environment variable by default to
+          # connect to a CloudWatch Metric Agent.
+          #
+          # @param conn_str [String] A connection string, formatted like 'tcp://127.0.0.1:25888'.
+          # @param conn_timeout_secs [Numeric] The number of seconds before timing out the connection to the agent.
+          # @param write_timeout_secs [Numeric] The number of seconds to wait before timing out a write.
+          # @param logger [Logger] A standard Ruby logger to propagate warnings and errors.
+          #   Suggested to use Rails.logger.
+          def initialize(conn_str: ENV.fetch(AWS_EMF_AGENT_ENDPOINT_ENV_VAR, nil),
+                         conn_timeout_secs: 10,
+                         write_timeout_secs: 10,
+                         logger: nil)
+            if conn_str.nil?
+              raise Sinks::Error, "Must specify a connection string or set environment variable #{AWS_EMF_AGENT_ENDPOINT_ENV_VAR}"
+            end
+
+            @logger = logger
+            @cw_agent_uri = URI.parse(conn_str)
+            if @cw_agent_uri.scheme != 'tcp' || !@cw_agent_uri.host || !@cw_agent_uri.port
+              raise Sinks::Error, "Expected connection string to be in format tcp://<host>:<port>, got '#{conn_str}'"
+            end
+
+            @client_opts = TCPClient::Configuration.create(
+              buffered: true,
+              keep_alive: true,
+              reverse_lookup: true,
+              connect_timeout: conn_timeout_secs,
+              write_timeout: write_timeout_secs
+            )
+            @conn = nil
+          end
+
+          def log_warn(msg)
+            @logger&.warn(msg)
+          end
+
+          def log_err(msg)
+            @logger&.error(msg)
+          end
+
+          def create_conn(host, port, opts)
+            TCPClient.open("#{host}:#{port}", opts)
+          end
+
+          def connection
+            @conn = create_conn(@cw_agent_uri.host, @cw_agent_uri.port, @client_opts) if @conn.nil? || @conn.closed?
+            @conn
+          end
+
+          def send_message(message)
+            retries = 2
+            conn = nil
+            begin
+              conn = connection
+              conn.write(message)
+            rescue Errno::ECONNREFUSED
+              conn.close unless conn.nil? || conn.closed?
+              log_warn("Could not connect to CloudWatch Agent at #{@cw_agent_uri.scheme}://#{@cw_agent_uri.host}:#{@cw_agent_uri.port}")
+              retries -= 1
+              retry if retries >= 0
+            rescue StandardError => e
+              log_err("#{e.class}: #{e.message}: #{e.backtrace.join("\n")}")
+            end
+          end
+
+          def accept(message)
+            send_message("#{JSON.dump(message)}\n")
+          end
+        end
+      end
+    end
+  end
+end

data/lib/aws-embedded-metrics-customink/sinks.rb

@@ -1,2 +1,5 @@
 require 'aws-embedded-metrics-customink/sinks/logger'
 require 'aws-embedded-metrics-customink/sinks/stdout'
+require 'aws-embedded-metrics-customink/sinks/tcp'
+
+require 'aws-embedded-metrics-customink/sinks/sink_error'

data/lib/aws-embedded-metrics-customink/units.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+module Aws
+  module Embedded
+    module Metrics
+      class Units
+        # Time
+        SECONDS = 'Seconds'
+        MICROSECONDS = 'Microseconds'
+        MILLISECONDS = 'Milliseconds'
+
+        # Size
+        BYTES = 'Bytes'
+        KILOBYTES = 'Kilobytes'
+        MEGABYTES = 'Megabytes'
+        GIGABYTES = 'Gigabytes'
+        TERABYTES = 'Terabytes'
+
+        BITS = 'Bits'
+        KILOBITS = 'Kilobits'
+        MEGABITS = 'Megabits'
+        GIGABITS = 'Gigabits'
+        TERABITS = 'Terabits'
+
+        # Simple units
+        PERCENT = 'Percent'
+        COUNT = 'Count'
+
+        # Size over time
+        BYTES_SECOND = "#{BYTES}/Second"
+        KILOBYTES_SECOND = "#{KILOBYTES}/Second"
+        MEGABYTES_SECOND = "#{MEGABYTES}/Second"
+        GIGABYTES_SECOND = "#{GIGABYTES}/Second"
+        TERABYTES_SECOND = "#{TERABYTES}/Second"
+
+        BITS_SECOND = "#{BITS}/Second"
+        KILOBITS_SECOND = "#{KILOBITS}/Second"
+        MEGABITS_SECOND = "#{MEGABITS}/Second"
+        GIGABITS_SECOND = "#{GIGABITS}/Second"
+        TERABITS_SECOND = "#{TERABITS}/Second"
+
+        COUNT_SECOND = "#{COUNT}/Second"
+
+        # Unit-less
+        NONE = 'None'
+      end
+    end
+  end
+end

data/lib/aws-embedded-metrics-customink/version.rb

@@ -1,7 +1,7 @@
 module Aws
   module Embedded
     module Metrics
-      VERSION = '0.6.0'.freeze
+      VERSION = '0.8.0'.freeze
     end
   end
 end

data/lib/aws-embedded-metrics-customink.rb

@@ -6,6 +6,7 @@ require 'aws-embedded-metrics-customink/version'
 require 'aws-embedded-metrics-customink/sinks'
 require 'aws-embedded-metrics-customink/config'
 require 'aws-embedded-metrics-customink/logger'
+require 'aws-embedded-metrics-customink/units'
 require 'aws-embedded-metrics-customink/instance' if defined?(Rails)
 
 module Aws

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: aws-embedded-metrics-customink
 version: !ruby/object:Gem::Version
-  version: 0.6.0
+  version: 0.8.0
 platform: ruby
 authors:
 - Ken Collins
-autorequire: 
+autorequire:
 bindir: exe
 cert_chain: []
-date: 2020-08-22 00:00:00.000000000 Z
+date: 2023-04-17 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: concurrent-ruby
@@ -54,7 +54,10 @@ files:
 - lib/aws-embedded-metrics-customink/logger.rb
 - lib/aws-embedded-metrics-customink/sinks.rb
 - lib/aws-embedded-metrics-customink/sinks/logger.rb
+- lib/aws-embedded-metrics-customink/sinks/sink_error.rb
 - lib/aws-embedded-metrics-customink/sinks/stdout.rb
+- lib/aws-embedded-metrics-customink/sinks/tcp.rb
+- lib/aws-embedded-metrics-customink/units.rb
 - lib/aws-embedded-metrics-customink/version.rb
 homepage: https://github.com/customink/aws-embedded-metrics-customink
 licenses:
@@ -63,7 +66,7 @@ metadata:
   homepage_uri: https://github.com/customink/aws-embedded-metrics-customink
   source_code_uri: https://github.com/customink/aws-embedded-metrics-customink
   changelog_uri: https://github.com/customink/aws-embedded-metrics-customink/blob/master/CHANGELOG.md
-post_install_message: 
+post_install_message:
 rdoc_options: []
 require_paths:
 - lib
@@ -78,8 +81,8 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.1.2
-signing_key: 
+rubygems_version: 3.4.7
+signing_key:
 specification_version: 4
 summary: Amazon CloudWatch Embedded Metric Format Client Library
 test_files: []