appengine 0.2.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: c5603a0560a10f3f6d0c6a6cd9a35ad8dcec9965
-  data.tar.gz: 92d67d00bfb992d723ccb5628f4f3f53c75e1a48
+  metadata.gz: 4841b00bed08c35d62dfd337ccd15cf5df775de9
+  data.tar.gz: a3158e01aaccb61471b504d7a66983c24a58a560
 SHA512:
-  metadata.gz: 381abeeea878aa676f40fbd444c022f2639f05d175c6457efd02e26c0eaa54ade5b1e032ac2dd553aa067afc594cb790be2828c230122d121a9d221dcc239657
-  data.tar.gz: 880a1741725629a5588795d1d7f38bbd340cd3a814a93e597bacdfa595080d191ecc25e1313aa2fd8e931406fb74415227ca561d3794c7bca6d0a8fbfb79433f
+  metadata.gz: 27445f16fa0d99b081992a8ea08427730dc4375b05f7a083763c5e6f9ee338652a6e8798eb47bc5293e51d9a4a22fe3c79322ca934284973826c3f7f6faf5741
+  data.tar.gz: 734a601f646ee785f5af7f9cbdf77af271a6e2bc25ae80abeaad0a8c92a26562462d2be953fa981ea4a04b48b1646c316dc08022658ad4d954e755dc5fb48406

data/README.md

@@ -9,7 +9,14 @@ environment.
 
 Currently, it includes:
 
-*   A way to configure the Logger to log to the Google Cloud Console.
+* Automatic Stackdriver instrumentation for Rails apps. This means logs,
+  error reports, and latency traces are reported to the cloud console.
+* A placeholder for a class that provides app engine environment information
+  such as project ID and VM info.
+
+Planned for the near future:
+
+* Streamlined implementation of health checks and other lifecycle hooks.
 
 For more information on using Google Cloud Platform to deploy Ruby apps,
 please visit http://cloud.google.com/ruby
@@ -27,34 +34,18 @@ may need to include the line:
     require "appengine"
 
 in your `config/application.rb` file if you aren't already requiring all
-bundled gems. You may provide additional configuration via the
-`config.appengine` object. See below for more details.
-
-If you are using a different Rack-based framework such as
-[Sinatra](http://sinatrarb.com/), you can use the provided middlewares. See
-the more detailed instructions below.
-
-## Google Cloud Console logger integration
-
-In order for your application logs to appear in the Google Cloud Console with
-the correct severities and other metadata, they should be written in a
-specific format to a specific location. The logger module in this gem provides
-tools to make that happen.
-
-If you are using Ruby on Rails, and you do not otherwise customize your
-Rails logger, then the provided Railtie will direct your logs to the Cloud
-Console "out of the box". Normally, this is configured to take effect when
-running in the `production` environment, but you may also configure it for
-other environments. See the documentation for the `AppEngine::Railtie` class
-for more details.
-
-If you are running a different Rack-based framework such as Sinatra, you
-should install the provided `AppEngine::Logger::Middleware` in your middleware
-stack. This should be installed instead of the normal `Rack::Logger`. It will
-automatically create a logger that directs entries to the Cloud Console, and
-will make it available via the standard `Rack::RACK_LOGGER` key in the Rack
-environment. You may also create your own logger directly using the
-`AppEngine::Logger.create()` method.
+bundled gems.
+
+## Logging and monitoring
+
+This library automatically installs the "stackdriver" gem, which instruments
+your application to report logs, unhandled exceptions, and latency traces to
+your project's Google Cloud Console. For more information on the application
+monitoring features of Google App Engine, see:
+
+* [google-cloud-logging instrumentation](http://googlecloudplatform.github.io/google-cloud-ruby/#/docs/google-cloud-logging/latest/guides/instrumentation)
+* [google-cloud-error_reporting instrumentation](http://googlecloudplatform.github.io/google-cloud-ruby/#/docs/google-cloud-error_reporting/latest/guides/instrumentation)
+* [google-cloud-trace instrumentation](http://googlecloudplatform.github.io/google-cloud-ruby/#/docs/google-cloud-trace/latest/guides/instrumentation)
 
 ## Development and support
 

data/lib/appengine.rb

@@ -24,5 +24,6 @@ end
 
 require 'appengine/version'
 require 'appengine/env'
-require 'appengine/logger'
 require 'appengine/railtie' if defined?(::Rails)
+
+require "stackdriver"

data/lib/appengine/env.rb

@@ -16,25 +16,15 @@
 
 module AppEngine
 
-
-  # == Environment information
+  ##
+  # A collection of functions for extracting App Engine environment information.
   #
-  # A collection of functions for extracting App Engine environment information
-  # from the Rack environment
-
   module Env
 
-
-    # Returns the Trace ID string from a Rack environment, or nil if no trace
-    # ID was found.
-
-    def self.extract_trace_id(env)
-      trace_context = env['HTTP_X_CLOUD_TRACE_CONTEXT'].to_s
-      return nil if trace_context.empty?
-      return trace_context.sub(/\/.*/, '')
+    def self.app_engine?
+      ::ENV["GAE_INSTANCE"] ? true : false
     end
 
-
   end
 
 end

data/lib/appengine/railtie.rb

@@ -31,25 +31,7 @@ module AppEngine
   #
   # === Configuration
   #
-  # The following configuration parameters are supported.
-  #
-  # [<tt>config.appengine.use_cloud_logger</tt>]
-  #   Set to true to cause the Rails logger to log to Google Cloud Console.
-  #   By default, this is true in the production environment and false in
-  #   all other environments. You may override this setting in individual
-  #   environment config files.
-  #
-  # [<tt>config.appengine.logfile</tt>]
-  #   The path to the log file when <tt>use_cloud_logger</tt> is active.
-  #   You should normally leave this as the default when deploying to Google
-  #   App Engine, but you may set it to a different path if you want to test
-  #   logging in a development environment.
-  #
-  # [<tt>config.appengine.trace_id_var</tt>]
-  #   The name of a fiber-local variable to store the current request's trace
-  #   ID. This is used to communicate request and trace information between
-  #   Rack and the cloud logger. You may change it if you need to control
-  #   fiber-local variable names.
+  # This is a placeholder for now.
 
   class Railtie < ::Rails::Railtie
 
@@ -57,25 +39,6 @@ module AppEngine
 
     config.appengine = ::ActiveSupport::OrderedOptions.new
 
-    config.appengine.use_cloud_logger = ::Rails.env.to_s == 'production'
-    config.appengine.logfile = ::AppEngine::Logger::DEFAULT_LOG_FILENAME
-    config.appengine.trace_id_var = ::AppEngine::Logger::DEFAULT_TRACE_ID_VAR
-
-
-    initializer 'google.appengine.logger', before: :initialize_logger do |app|
-      if app.config.appengine.use_cloud_logger
-        app.config.logger = ::AppEngine::Logger.create(
-            logfile: app.config.appengine.logfile,
-            trace_id_var: app.config.appengine.trace_id_var)
-        app.config.log_formatter = app.config.logger.formatter
-
-        app.middleware.insert_before(::Rails::Rack::Logger,
-            ::AppEngine::Logger::Middleware,
-            logger: app.config.logger,
-            trace_id_var: app.config.appengine.trace_id_var)
-      end
-    end
-
     # :startdoc:
 
   end

data/lib/appengine/version.rb

@@ -16,6 +16,6 @@
 module AppEngine
 
   # The current version of this gem, as a string.
-  VERSION = '0.2.0'.freeze
+  VERSION = '0.3.0'.freeze
 
 end

data/test/test_env.rb

@@ -23,31 +23,11 @@ module AppEngine
     class TestEnv < ::Minitest::Test  # :nodoc:
 
 
-      def test_extract_trace_id_absent
-        env = {}
-        trace_id = Env.extract_trace_id(env)
-        assert_nil(trace_id)
-      end
-
-
-      def test_extract_trace_id_empty
-        env = {'HTTP_X_CLOUD_TRACE_CONTEXT' => ''}
-        trace_id = Env.extract_trace_id(env)
-        assert_nil(trace_id)
-      end
-
-
-      def test_extract_trace_id_simple
-        env = {'HTTP_X_CLOUD_TRACE_CONTEXT' => 'abcdefg'}
-        trace_id = Env.extract_trace_id(env)
-        assert_equal('abcdefg', trace_id)
-      end
-
-
-      def test_extract_trace_id_with_suffix
-        env = {'HTTP_X_CLOUD_TRACE_CONTEXT' => 'abcdefg/hijk/lmnop'}
-        trace_id = Env.extract_trace_id(env)
-        assert_equal('abcdefg', trace_id)
+      def test_app_engine
+        ::ENV["GAE_INSTANCE"] = "instance-123"
+        assert Env.app_engine?
+        ::ENV.delete "GAE_INSTANCE"
+        refute Env.app_engine?
       end
 
 

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: appengine
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.3.0
 platform: ruby
 authors:
 - Adam Tanner
@@ -9,22 +9,42 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2016-05-04 00:00:00.000000000 Z
+date: 2017-02-28 00:00:00.000000000 Z
 dependencies:
+- !ruby/object:Gem::Dependency
+  name: stackdriver
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.4'
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 0.4.1
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.4'
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 0.4.1
 - !ruby/object:Gem::Dependency
   name: bundler
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '1.11'
+        version: '1.14'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '1.11'
+        version: '1.14'
 - !ruby/object:Gem::Dependency
   name: minitest
   requirement: !ruby/object:Gem::Requirement
@@ -69,7 +89,7 @@ dependencies:
         version: '4.2'
 description: The appengine gem is a set of classes, plugins, and tools for integration
   with Google App Engine. It provides access to the App Engine runtime environment,
-  including logging to the Google Cloud Console and interpretation of App Engine headers.
+  including logging to the Google Cloud Console and interrogation of hosting properties.
   However, it is not required for deploying your Ruby application to App Engine.
 email:
 - adamtanner@google.com
@@ -85,11 +105,9 @@ files:
 - Rakefile
 - lib/appengine.rb
 - lib/appengine/env.rb
-- lib/appengine/logger.rb
 - lib/appengine/railtie.rb
 - lib/appengine/version.rb
 - test/test_env.rb
-- test/test_logger.rb
 homepage: https://github.com/GoogleCloudPlatform/appengine-ruby
 licenses:
 - Apache 2.0
@@ -110,7 +128,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
       version: '0'
 requirements: []
 rubyforge_project: 
-rubygems_version: 2.4.5.1
+rubygems_version: 2.6.8
 signing_key: 
 specification_version: 4
 summary: Google App Engine integration tools

data/lib/appengine/logger.rb

@@ -1,188 +0,0 @@
-# Copyright 2016 Google Inc. All rights reserved.
-#
-# Licensed under the Apache License, Version 2.0 (the "License");
-# you may not use this file except in compliance with the License.
-# You may obtain a copy of the License at
-#
-#     http://www.apache.org/licenses/LICENSE-2.0
-#
-# Unless required by applicable law or agreed to in writing, software
-# distributed under the License is distributed on an "AS IS" BASIS,
-# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
-# See the License for the specific language governing permissions and
-# limitations under the License.
-;
-
-require 'json'
-require 'logger'
-
-
-module AppEngine
-
-
-  # == AppEngine Logger integration
-  #
-  # A collection of tools for talking to the StackDriver logs in the Google
-  # Cloud Console.
-  #
-  # For logs to appear in the Google Cloud Console, they must be written in
-  # JSON format to files matching the pattern "/var/log/app_engine/app*.json".
-  # We provide an appropriate formatter, and a LogDevice that omits the
-  # log header line.
-  #
-  # Logs should also be annotated with the request's Trace ID. We provide
-  # a Rack Middleware to extract that ID from the environment and annotate
-  # log entries. It uses a fiber-local variable to store the Trace ID for
-  # the current request being handled by that fiber.
-
-  module Logger
-
-
-    # The name of a fiber-local variable storing the trace ID for the current
-    # request.
-    DEFAULT_TRACE_ID_VAR = :_google_appengine_trace_id
-
-    # The default path to the log file.
-    DEFAULT_LOG_FILENAME = '/var/log/app_engine/app-ruby.json'
-
-    # A map from Ruby severity names to Google Cloud severity names.
-    SEV_MAP = {
-      'DEBUG' => 'DEBUG',
-      'INFO' => 'INFO',
-      'WARN' => 'WARNING',
-      'ERROR' => 'ERROR',
-      'FATAL' => 'CRITICAL'
-    }
-
-
-    # == AppEngie Formatter
-    #
-    # A formatter that generates the appropriate JSON format for log entries.
-    # Pulls the trace ID from the fiber-local variable, if present.
-    #
-    # (see ::Logger::Formatter)
-
-    class Formatter
-
-
-      # Create a new formatter. You may optionally override the fiber-local
-      # variable name used for the trace ID.
-
-      def initialize(trace_id_var: DEFAULT_TRACE_ID_VAR)
-        @trace_id_var = trace_id_var
-      end
-
-
-      def call(severity, time, progname, msg)  # :nodoc:
-        msg = msg.to_s
-        return '' if msg.empty?
-        entry = {
-          message: (progname.to_s != '') ? "#{progname}: #{msg}" : msg,
-          timestamp: {seconds: time.to_i, nanos: time.nsec},
-          severity: SEV_MAP.fetch(severity.to_s, 'CRITICAL')
-        }
-        trace_id = ::Thread.current[@trace_id_var]
-        if trace_id
-          entry[:traceId] = trace_id.to_s
-        end
-        ::JSON.generate(entry) + "\n"
-      end
-
-    end
-
-
-    # == AppEngine LogDevice
-    #
-    # A ::Logger::LogDevice subclass that omits the log header line.
-
-    class LogDevice < ::Logger::LogDevice
-
-      def add_log_header(file)  # :nodoc:
-      end
-
-    end
-
-
-    # == Rack Middleware for AppEngine logger
-    #
-    # A Rack middleware that sets the logger in the Rack environment, and
-    # stashes the trace ID for the current request in a fiber-local variable
-    # for the logger to use when formatting log entries.
-    #
-    # In a standard Rack application, you should use this middleware instead
-    # of the standard ::Rack::Logger.
-
-    class Middleware
-
-
-      # Create a new AppEngine logging Middleware.
-      # The argument is an options hash supporting the following keys:
-      #
-      # [<tt>:logger</tt>]
-      #   A global logger to use. This should generally be a logger created
-      #   by AppEngine::Logger.create(). The middleware sets env["rack.logger"]
-      #   accordingly. If omitted, a default logger is created automatically
-      #   when the middleware is constructed.
-      # [<tt>:trace_id_var</tt>]
-      #   The name of the fiber-local variable to use to stack the trace ID.
-      #   Defaults to the value of DEFAULT_TRACE_ID_VAR. You generally should
-      #   not need to modify this value unless you need to control fiber-local
-      #   variable names.
-      # [<tt>:logfile</tt>]
-      #   If you do not specify a <tt>:logger</tt>, a logger is created that
-      #   opens this file. Defaults to the value of DEFAULT_LOG_FILENAME.
-      #   Generally, you should leave this setting to the default for
-      #   deployments, because App Engine expects log files in a particular
-      #   location. However, if you want to test log generation into a
-      #   different directory in development, you may set it here.
-
-      def initialize(app,
-            logger: nil,
-            trace_id_var: DEFAULT_TRACE_ID_VAR,
-            logfile: DEFAULT_LOG_FILENAME)
-        @app = app
-        @trace_id_var = trace_id_var
-        @logger = logger || Logger.create(trace_id_var: trace_id_var, logfile: logfile)
-      end
-
-
-      def call(env)  # :nodoc:
-        env['rack.logger'] = @logger
-        ::Thread.current[@trace_id_var] = Env.extract_trace_id(env)
-        begin
-          @app.call(env)
-        ensure
-          ::Thread.current[@trace_id_var] = nil
-        end
-      end
-
-    end
-
-
-    # Creates a new logger for AppEngine that writes to the correct location
-    # using the correct formatting.
-    # The argument is an options hash supporting the following keys:
-    #
-    # [<tt>:trace_id_var</tt>]
-    #   The name of the fiber-local variable to use to stack the trace ID.
-    #   Defaults to the value of DEFAULT_TRACE_ID_VAR. You generally should
-    #   not need to modify this value unless you need to control fiber-local
-    #   variable names.
-    # [<tt>:logfile</tt>]
-    #   Log file to write to. Defaults to the value of DEFAULT_LOG_FILENAME.
-    #   Generally, you should leave this setting to the default for
-    #   deployments, because App Engine expects log files in a particular
-    #   location. However, if you want to test log generation into a
-    #   different directory in development, you may set it here.
-
-    def self.create(trace_id_var: DEFAULT_TRACE_ID_VAR, logfile: DEFAULT_LOG_FILENAME)
-      if logfile.kind_of?(::String)
-        ::FileUtils.mkdir_p(::File.dirname(logfile))
-      end
-      logger = ::Logger.new(LogDevice.new(logfile))
-      logger.formatter = Formatter.new(trace_id_var: trace_id_var)
-      logger
-    end
-
-  end
-end

data/test/test_logger.rb

@@ -1,151 +0,0 @@
-# Copyright 2016 Google Inc. All rights reserved.
-#
-# Licensed under the Apache License, Version 2.0 (the "License");
-# you may not use this file except in compliance with the License.
-# You may obtain a copy of the License at
-#
-#     http://www.apache.org/licenses/LICENSE-2.0
-#
-# Unless required by applicable law or agreed to in writing, software
-# distributed under the License is distributed on an "AS IS" BASIS,
-# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
-# See the License for the specific language governing permissions and
-# limitations under the License.
-;
-
-require 'minitest/autorun'
-require 'appengine'
-
-
-module AppEngine
-  module Tests  # :nodoc:
-
-    class TestFormatter < ::Minitest::Test  # :nodoc:
-
-
-      def setup
-        @time_sec = 1461544128
-        @time_nsec = 580791000
-        @time = ::Time.at(@time_sec, @time_nsec / 1000)
-        @trace_id = 'a1b2c3d4e5f6'
-        ::Thread.current[::AppEngine::Logger::DEFAULT_TRACE_ID_VAR] = @trace_id
-        @formatter = ::AppEngine::Logger::Formatter.new
-      end
-
-
-      def test_format_empty
-        result = @formatter.call('ERROR', @time, 'prog', '')
-        assert_equal('', result)
-      end
-
-
-      def test_format_with_progname
-        result = @formatter.call('ERROR', @time, 'prog', 'this message')
-        assert_equal(
-            "{\"message\":\"prog: this message\"," +
-              "\"timestamp\":{\"seconds\":#{@time_sec},\"nanos\":#{@time_nsec}}," +
-              "\"severity\":\"ERROR\"," +
-              "\"traceId\":\"#{@trace_id}\"}\n",
-            result)
-      end
-
-
-      def test_format_with_no_trace_id
-        ::Thread.current[::AppEngine::Logger::DEFAULT_TRACE_ID_VAR] = nil
-        result = @formatter.call('ERROR', @time, '', 'this message')
-        assert_equal(
-            "{\"message\":\"this message\"," +
-              "\"timestamp\":{\"seconds\":#{@time_sec},\"nanos\":#{@time_nsec}}," +
-              "\"severity\":\"ERROR\"}\n",
-            result)
-      end
-
-
-      def test_format_with_warning_severity
-        result = @formatter.call('WARN', @time, '', 'this message')
-        assert_equal(
-            "{\"message\":\"this message\"," +
-              "\"timestamp\":{\"seconds\":#{@time_sec},\"nanos\":#{@time_nsec}}," +
-              "\"severity\":\"WARNING\"," +
-              "\"traceId\":\"#{@trace_id}\"}\n",
-            result)
-      end
-
-
-      def test_format_with_critical_severity
-        result = @formatter.call('FATAL', @time, '', 'this message')
-        assert_equal(
-            "{\"message\":\"this message\"," +
-              "\"timestamp\":{\"seconds\":#{@time_sec},\"nanos\":#{@time_nsec}}," +
-              "\"severity\":\"CRITICAL\"," +
-              "\"traceId\":\"#{@trace_id}\"}\n",
-            result)
-      end
-
-
-      def test_format_with_unknown_severity
-        result = @formatter.call('UNKNOWN', @time, '', 'this message')
-        assert_equal(
-            "{\"message\":\"this message\"," +
-              "\"timestamp\":{\"seconds\":#{@time_sec},\"nanos\":#{@time_nsec}}," +
-              "\"severity\":\"CRITICAL\"," +
-              "\"traceId\":\"#{@trace_id}\"}\n",
-            result)
-      end
-
-
-    end
-
-
-    class TestLogger < ::Minitest::Test  # :nodoc:
-
-
-      def test_no_logging
-        lines = run_test do |logger|
-        end
-        assert_equal([], lines)
-      end
-
-
-      def test_basic_log
-        trace_id = "tracetrace"
-        lines = run_test(trace_id) do |logger|
-          logger.progname = "rails"
-          logger.info("Hello")
-          logger.warn("This is a warning")
-        end
-        assert_equal(2, lines.size)
-        assert_log_entry("rails: Hello", "INFO", trace_id, lines[0])
-        assert_log_entry("rails: This is a warning", "WARNING", trace_id, lines[1])
-      end
-
-
-      def assert_log_entry(expected_message, expected_severity, expected_trace_id, line)
-        if line =~ /^\{"message":"(.*)","timestamp":\{"seconds":\d+,"nanos":\d+\},"severity":"(\w+)"(,"traceId":"(\w+)")?\}\n$/
-          message = $1
-          severity = $2
-          trace_id = $4
-          assert_equal(expected_message, message)
-          assert_equal(expected_severity, severity)
-          assert_equal(expected_trace_id, trace_id)
-        else
-          flunk("Bad format: #{line.inspect}")
-        end
-      end
-
-
-      def run_test(trace_id=nil)
-        stringio = ::StringIO.new('', 'w')
-        app = ::Proc.new { |env|
-          yield(env['rack.logger'])
-        }
-        middleware = ::AppEngine::Logger::Middleware.new(app, logfile: stringio)
-        middleware.call({'HTTP_X_CLOUD_TRACE_CONTEXT' => trace_id})
-        ::StringIO.new(stringio.string).each_line.to_a
-      end
-
-
-    end
-
-  end
-end