signalfx-lambda 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b7d5d079150c49b6b3b43e8a457cc5b4165ffe38e58dfa884a47f49f0a39bf6c
-  data.tar.gz: ccd63f18a2caaf898bc40ce792930adc896e952a62a368730c40c6aa2e08f414
+  metadata.gz: 66109fc8dcb960d2debc31c6fc37b741bf3b4f55508c0b23c4032da3fe0e94ef
+  data.tar.gz: 0f0a82a5c16fe67584de6c1ad5e89ffa910166e2f4bfc7f9f7b494fe1374ae63
 SHA512:
-  metadata.gz: c9af39140b055a4e4cb7728786b1c4a7de991b517e5302f448ccceadb165d3c32152a69817e1d978c4bb87e6ac6a38a01116c35495f228d97cb1e9b953b70686
-  data.tar.gz: 7cb0f4ffe5863e00e2c63eec53d621f7c1c526eb20318534a0c56d0fee338a3aeb22ba8b2afce900585ab38dbf59f7e82e3a964634a5ea5c22bb097b5169fea6
+  metadata.gz: 8221f2148e1811c23b86bc365f2ac78c0335a48623a2fafcbabb8eb7eae5fe184af4405dde005a6331d4f40d410d42440c98294543e7cdaf82021e7c5478f3fe
+  data.tar.gz: 5dc457153fd2e4ea1acce699f9228ddfd37cad23a1657d1c73161c4533ec37fd64f39d644bad414884b32ceac2aed70eb6c9f7001af246f8c1b1092817757700

data/README.md

@@ -1,7 +1,7 @@
 # SignalFx::Lambda
 
-This gem provides a simplified way to trace AWS Lambda functions written for the
-Ruby 2.5 runtime.
+This gem provides a simplified way to get metrics and traces from AWS Lambda
+functions written for the Ruby 2.5 runtime.
 
 ## Installation
 
@@ -34,32 +34,80 @@ def handler(event:, context:)
     JSON.generate(body)
 end
 
-SignalFx::Lambda::Tracing.register_handler(&method(:handler))
+SignalFx::Lambda.register_handler(metrics: true, tracing: true, &method(:handler))
 ```
 
 `register_handler` will accept any block.
 
+If passing in a block parameter, it must be the last argument.
+
+It also takes these optional arguments:
+- `metrics`: Enable reporting of metrics. Default: `true`
+- `tracing`: Enable tracing. Default: `true`
+
+### Endpoint configuration
+
+If metrics and traces should be reported to a common endpoint, as is the case
+when using the Smart Gateway, a single environment variable should be set:
+
+```
+SIGNALFX_ENDPOINT_URL=<gateway_url>
+```
+
+If the component-specific URLs below are set, they will take precedence over
+`SIGNALFX_ENDPOINT_URL` for those components.
+
+By default, the metrics and traces will be reported to the `us0` realm. If you are
+not in this realm you will need to set the `SIGNALFX_TRACING_URL` and
+`SIGNALFX_METRICS_URL` environment variables, as described below.
+
 ### Tracer configuration
 
 The tracer used by the function is configured through environment variables:
 
 ```
 SIGNALFX_ACCESS_TOKEN
-SIGNALFX_INGEST_URL
 SIGNALFX_SERVICE_NAME
+SIGNALFX_TRACING_URL
 ```
 
-In production, `SIGNALFX_INGEST_URL` should be pointing to your [Smart Gateway](https://docs.signalfx.com/en/latest/apm/apm-deployment/smart-gateway.html).
+In production, `SIGNALFX_TRACING_URL` should be pointing to your [Smart Gateway](https://docs.signalfx.com/en/latest/apm/apm-deployment/smart-gateway.html).
 When pointing to the Smart Gateway, an access token is not needed. When not
 configured, the ingest URL defaults to `https://ingest.signalfx.com/v1/trace`,
 which requires an access token to be configured.
 
+The default `SIGNALFX_TRACING_URL` points to the `us0` realm. If you are not in
+this realm, you will need to set the environment variable to the correct realm
+ingest endpoint (https://ingest.{REALM}.signalfx.com/v1/trace). To determine what realm
+you are in, check your profile page in the SignalFx web application (click the
+avatar in the upper right and click My Profile).
+
 The tracer will be persisted across invocations to the same context, reducing
 the time needed for tracer initialization.
 
+### SignalFx client configuration
+
+The SignalFx client requires the following environment variables to be set:
+
+```
+SIGNALFX_ACCESS_TOKEN
+SIGNALFX_METRICS_URL
+```
+
+When `SIGNALFX_METRICS_URL` is pointing to a Smart Gateway in production, the
+access token is not needed.
+
+The metrics URL will default to `https://ingest.signalfx.com` when not configured.
+
+The default `SIGNALFX_METRICS_URL` points to the `us0` realm. If you are not in
+this realm, you will need to set the environment variable to the correct realm
+ingest endpoint (https://ingest.{REALM}.signalfx.com). To determine what realm
+you are in, check your profile page in the SignalFx web application (click the
+avatar in the upper right and click My Profile).
+
 ## Trace and tags
 
-The wrapper will generate a single span per function invocation. This span will
+The wrapper will generate a trace per function invocation. The parent span will
 be named with the pattern  `lambda_ruby_<function_name>`. The span prefix can be
 optionally configured with the `SIGNALFX_SPAN_PREFIX` environment variable:
 
@@ -82,11 +130,39 @@ Each span will also have the following tags:
 
 If a `qualifier` is present in the ARN, depending on the resource type, either `aws_function_qualifier` or `event_source_mappings` will be tagged.
 
-## Manual Tracing
+## Metrics
+
+When metrics are enabled, the following datapoints are sent to SignalFx:
+
+| Metric Name            | Type    | Description                                                     |
+| ---                    | ---     | ---                                                             |
+| `function.invocations` | Counter | Count number of Lambda invocations                              |
+| `function.cold_starts` | Counter | Count number of cold starts                                     |
+| `function.errors`      | Counter | Count number of errors captured from underlying Lambda handler  |
+| `function.duration`    | Gauge   | Execution time of the underlying Lambda handler in milliseconds |
+
+Each datapoint has the following dimensions:
+- `metric_source`: `ruby-lambda-wrapper`
+- `lambda_arn`: the full ARN of the invocation
+- `aws_region`: the region that the function executed in
+- `aws_account_id`: id of the account this function ran for
+- `aws_function_name`: the function name set for this Lambda
+- `aws_function_version`: the function version
+- `aws_function_qualifier`: function version qualifier, which will be a version
+  or version alias if it is not an event source mapping invocation
+- `event_source_mappings`: function name if it is an event source mapping invocation
+- `aws_execution_env`: the name of the runtime environment running this function
+- `function_wrapper_version`: the version of this wrapper gem being used
+- `log_group_name`: log group for the function
+- `log_stream_name`: log stream for the instance
+
+## Manual Instrumentation
+
+### Tracing
 
 Manual tracing may be useful to get a better view into the function. The
 OpenTracing global tracer makes the tracer used by the wrapper available
-to when more specific instrumentation is desired.
+when more specific instrumentation is desired.
 
 ```ruby
 require 'opentracing'
@@ -103,6 +179,15 @@ Lambda handler as the parent.
 
 For more examples of usage, please see [opentracing-ruby](https://github.com/opentracing/opentracing-ruby).
 
+### Metrics
+
+Your function can be manually instrumented to send additional metrics using the
+already configured SignalFx client.
+
+```ruby
+SignalFx::Lambda::Metrics.client.send(counters: ..., gauges: ..., cumulative_counters: ...)
+```
+
 ## Development
 
 After checking out the repo, run `bin/setup` to install dependencies. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
@@ -115,4 +200,4 @@ Bug reports and pull requests are welcome on GitHub at https://github.com/signal
 
 ## License
 
-The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).
+The gem is available as open source under the terms of the [Apache 2.0 License](https://opensource.org/licenses/Apache-2.0).

data/lib/signalfx/lambda/metrics.rb

@@ -0,0 +1,88 @@
+require 'signalfx'
+
+module SignalFx
+  module Lambda
+    module Metrics
+      class Error < StandardError; end
+
+      class << self
+        attr_accessor :client
+
+        def wrap_function(event:, context:)
+          cold_start = @client.nil?
+          init_client unless @client
+          counters = []
+          gauges = []
+
+          dimensions = populate_dimensions(context)
+
+          # time execution of next block
+          start_time = Time.now
+          response = yield event: event, context: context
+          end_time = Time.now
+
+          duration = ((end_time - start_time) * 1000) # duration in ms
+          end_time = end_time.strftime('%s%L')
+
+          counters.push(
+            {
+              :metric => 'function.invocations',
+              :value => 1,
+              :timestamp => end_time,
+              :dimensions => dimensions
+            }
+          )
+
+          counters.push(
+            {
+              :metric => 'function.cold_starts',
+              :value => 1,
+              :timestamp => end_time,
+              :dimensions => dimensions
+            }
+          ) if cold_start
+
+          gauges = [
+            {
+              :metric => 'function.duration',
+              :value => duration,
+              :timestamp => end_time,
+              :dimensions => dimensions
+            }
+          ]
+
+          response
+        rescue => error
+          error_counter = {
+            :metric => 'function.errors',
+            :value => 1,
+            :timestamp => end_time,
+            :dimensions => dimensions
+          }
+
+          counters.push(error_counter)
+
+          raise
+        ensure
+          # send metrics before leaving this block
+          @client.send(gauges: gauges, counters: counters) if @client
+        end
+
+        def populate_dimensions(context)
+          dimensions = SignalFx::Lambda.fields.map do |key, val|
+            { :key => key, :value => val }
+          end
+          dimensions.merge!({ :key => 'metric_source', :value => SignalFx::Lambda::COMPONENT })
+        end
+
+        def init_client
+          access_token = ENV['SIGNALFX_ACCESS_TOKEN']
+          ingest_endpoint = ENV['SIGNALFX_METRICS_URL'] || ENV['SIGNALFX_ENDPOINT_URL'] || 'https://ingest.signalfx.com'
+
+          @client = SignalFx.new access_token, ingest_endpoint: ingest_endpoint
+        end
+      end
+    end
+  end
+end
+

data/lib/signalfx/lambda/tracing.rb

@@ -8,103 +8,75 @@ module SignalFx
     module Tracing
       class Error < StandardError; end
 
-      def self.wrap_function(event, context, &block)
-        init_tracer(event) if !@tracer # avoid initializing except on a cold start
+      class << self
+        attr_accessor :tracer, :reporter
 
-        scope = OpenTracing.start_active_span("#{@span_prefix}#{context.function_name}", tags: build_tags(context))
+        def wrap_function(event:, context:, &block)
+          init_tracer(event) if !@tracer # avoid initializing except on a cold start
 
-        response = yield event: event, context: context
-        scope.span.set_tag("http.status_code", response[:statusCode]) if response[:statusCode]
+          tags = SignalFx::Lambda.fields
+          tags['component'] = SignalFx::Lambda::COMPONENT
 
-        response
-      rescue => error
-        if scope
-          scope.span.set_tag("error", true)
-          scope.span.log_kv(key: "message", value: error.message)
-        end
-
-        # pass this error up
-        raise
-      ensure
-        scope.close if scope
-
-        # flush the spans before leaving the execution context
-        @reporter.flush
-      end
+          scope = OpenTracing.start_active_span("#{@span_prefix}#{context.function_name}",
+                                                tags: tags)
 
-      def self.wrapped_handler(event:, context:)
-        wrap_function(event, context, &@handler)
-      end
-
-      def self.build_tags(context)
-        tags = {
-          'component' => 'ruby-lambda-wrapper',
-          'lambda_arn' => context.invoked_function_arn,
-          'aws_request_id' => context.aws_request_id,
-          'aws_function_name' => context.function_name,
-          'aws_function_version' => context.function_version,
-          'aws_execution_env' => ENV['AWS_EXECUTION_ENV'],
-          'log_group_name' => context.log_group_name,
-          'log_stream_name' => context.log_stream_name,
-          'function_wrapper_version' => "signalfx-lambda-#{SignalFx::Lambda::VERSION}",
-        }
-
-        tags = tags.merge(tags_from_arn(context.invoked_function_arn))
-      end
+          response = yield event: event, context: context
+          scope.span.set_tag("http.status_code", response[:statusCode]) if response[:statusCode]
 
-      def self.tags_from_arn(arn)
-        _, _, _, region, account_id, resource_type, _, qualifier = arn.split(':')
+          response
+        rescue => error
+          if scope
+            scope.span.set_tag("error", true)
+            scope.span.log_kv(key: "message", value: error.message)
+          end
 
-        tags = {
-          'aws_region' => region,
-          'aws_account_id' => account_id,
-        }
+          # pass this error up
+          raise
+        ensure
+          scope.close if scope
 
-        if qualifier
-          case resource_type
-          when 'function'
-            tags['aws_function_qualifier'] = qualifier
-          when 'event-source-mappings'
-            tags['event_source_mappings'] = qualifier
-          end
+          # flush the spans before leaving the execution context
+          @reporter.flush
         end
 
-        tags
-      end
+        def wrapped_handler(event:, context:)
+          wrap_function(event, context, &@handler)
+        end
 
-      def self.register_handler(&handler)
-        @handler = handler
-      end
+        def register_handler(&handler)
+          @handler = handler
+        end
 
-      def self.init_tracer(event)
-        access_token = ENV['SIGNALFX_ACCESS_TOKEN']
-        ingest_url = ENV['SIGNALFX_INGEST_URL'] || 'https://ingest.signalfx.com/v1/trace'
-        service_name = ENV['SIGNALFX_SERVICE_NAME'] || event.function_name
-        @span_prefix = ENV['SIGNALFX_SPAN_PREFIX'] || 'lambda_ruby_'
-
-        # configure the trace reporter
-        headers = { }
-        headers['X-SF-Token'] = access_token if !access_token.empty?
-        encoder = Jaeger::Client::Encoders::ThriftEncoder.new(service_name: service_name)
-        sender = Jaeger::Client::HttpSender.new(url: ingest_url, headers: headers, encoder: encoder, logger: Logger.new(STDOUT))
-        @reporter = Jaeger::Client::Reporters::RemoteReporter.new(sender: sender, flush_interval: 1)
-
-        # propagation format configuration
-        injectors = {
-          OpenTracing::FORMAT_TEXT_MAP => [Jaeger::Client::Injectors::B3RackCodec]
-        }
-        extractors = {
-          OpenTracing::FORMAT_TEXT_MAP => [SignalFx::Lambda::Tracing::B3TextMapCodec]
-        }
-
-        OpenTracing.global_tracer = Jaeger::Client.build(
-          service_name: service_name,
-          reporter: @reporter,
-          injectors: injectors,
-          extractors: extractors
-        )
-
-        @tracer = OpenTracing.global_tracer
+        def init_tracer(event)
+          access_token = ENV['SIGNALFX_ACCESS_TOKEN']
+          ingest_url = ENV['SIGNALFX_TRACING_URL'] || ENV['SIGNALFX_ENDPOINT_URL'] || 'https://ingest.signalfx.com/v1/trace'
+          service_name = ENV['SIGNALFX_SERVICE_NAME'] || event.function_name
+          @span_prefix = ENV['SIGNALFX_SPAN_PREFIX'] || 'lambda_ruby_'
+
+          # configure the trace reporter
+          headers = { }
+          headers['X-SF-Token'] = access_token if !access_token.empty?
+          encoder = Jaeger::Client::Encoders::ThriftEncoder.new(service_name: service_name)
+          sender = Jaeger::Client::HttpSender.new(url: ingest_url, headers: headers, encoder: encoder, logger: Logger.new(STDOUT))
+          @reporter = Jaeger::Client::Reporters::RemoteReporter.new(sender: sender, flush_interval: 100)
+
+          # propagation format configuration
+          injectors = {
+            OpenTracing::FORMAT_TEXT_MAP => [Jaeger::Client::Injectors::B3RackCodec]
+          }
+          extractors = {
+            OpenTracing::FORMAT_TEXT_MAP => [SignalFx::Lambda::Tracing::B3TextMapCodec]
+          }
+
+          OpenTracing.global_tracer = Jaeger::Client.build(
+            service_name: service_name,
+            reporter: @reporter,
+            injectors: injectors,
+            extractors: extractors
+          )
+
+          @tracer = OpenTracing.global_tracer
+        end
       end
     end
   end

data/lib/signalfx/lambda/version.rb

@@ -1,5 +1,5 @@
 module SignalFx
   module Lambda
-    VERSION = "0.1.0"
+    VERSION = "0.2.0"
   end
 end

data/lib/signalfx/lambda.rb

@@ -1,2 +1,81 @@
 require 'signalfx/lambda/version'
 require 'signalfx/lambda/tracing'
+require 'signalfx/lambda/metrics'
+
+module SignalFx
+  module Lambda
+    class Error < StandardError; end
+
+    COMPONENT = 'ruby-lambda-wrapper'.freeze
+
+    class << self
+      attr_accessor :fields
+
+      def wrapped_handler(event:, context:)
+        # gather some useful information from the execution context and ARN and
+        # make it available to the handlers
+        @fields = gather_fields(context)
+        @wrapped_handler.call(event: event, context: context)
+      end
+
+      def register_handler(metrics: true, tracing: true, &handler)
+        @handler = handler # the original handler
+
+        # Add the wrappers needed
+        wrappers = []
+        wrappers.push(@handler)
+        wrappers.push(Tracing.method(:wrap_function)) if tracing
+        wrappers.push(Metrics.method(:wrap_function)) if metrics
+
+        @wrapped_handler = build_wrapped_handler(wrappers) if @wrapped_handler.nil?
+      end
+
+      # build a nested block depending on the wrappers enabled
+      def build_wrapped_handler(wrappers)
+        wrappers.inject do |inner, outer|
+          proc do |event:, context:|
+            outer.call(event: event, context: context, &inner)
+          end
+        end
+      end
+
+      # build a map of useful properties from the context object
+      def gather_fields(context)
+        fields = {
+          'lambda_arn' => context.invoked_function_arn,
+          'aws_request_id' => context.aws_request_id,
+          'aws_function_name' => context.function_name,
+          'aws_function_version' => context.function_version,
+          'aws_execution_env' => ENV['AWS_EXECUTION_ENV'],
+          'log_group_name' => context.log_group_name,
+          'log_stream_name' => context.log_stream_name,
+          'function_wrapper_version' => "signalfx-lambda-#{SignalFx::Lambda::VERSION}",
+        }
+
+        fields.merge!(fields_from_arn(context.invoked_function_arn))
+      end
+
+      # the arn packs useful data, including region, account id, resource type,
+      # and qualifier
+      def fields_from_arn(arn = '')
+        _, _, _, region, account_id, resource_type, _, qualifier = arn.split(':')
+
+        fields = {
+          'aws_region' => region,
+          'aws_account_id' => account_id,
+        }
+
+        if qualifier
+          case resource_type
+          when 'function'
+            fields['aws_function_qualifier'] = qualifier
+          when 'event-source-mappings'
+            fields['event_source_mappings'] = qualifier
+          end
+        end
+
+        fields
+      end
+    end
+  end
+end

data/signalfx-lambda.gemspec

@@ -24,6 +24,7 @@ Gem::Specification.new do |spec|
 
   spec.add_dependency "jaeger-client", "~> 0.10.0"
   spec.add_dependency "opentracing", "~> 0.3"
-  spec.add_development_dependency "bundler", "~> 1.17"
+  spec.add_dependency "signalfx"
+  spec.add_development_dependency "bundler", "~> 2.0"
   spec.add_development_dependency "rake", "~> 10.0"
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: signalfx-lambda
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.2.0
 platform: ruby
 authors:
 - Ashwin Chandrasekar
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2019-01-11 00:00:00.000000000 Z
+date: 2019-02-21 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: jaeger-client
@@ -38,20 +38,34 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '0.3'
+- !ruby/object:Gem::Dependency
+  name: signalfx
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
 - !ruby/object:Gem::Dependency
   name: bundler
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '1.17'
+        version: '2.0'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '1.17'
+        version: '2.0'
 - !ruby/object:Gem::Dependency
   name: rake
   requirement: !ruby/object:Gem::Requirement
@@ -81,6 +95,7 @@ files:
 - bin/console
 - bin/setup
 - lib/signalfx/lambda.rb
+- lib/signalfx/lambda/metrics.rb
 - lib/signalfx/lambda/tracing.rb
 - lib/signalfx/lambda/tracing/extractors.rb
 - lib/signalfx/lambda/version.rb
@@ -104,8 +119,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubyforge_project: 
-rubygems_version: 2.7.3
+rubygems_version: 3.0.2
 signing_key: 
 specification_version: 4
 summary: Lambda handler wrapper