google-cloud-trace 0.21.0

data/lib/google/cloud/trace/credentials.rb

@@ -0,0 +1,41 @@
+# Copyright 2014 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 "google/cloud/credentials"
+
+module Google
+  module Cloud
+    module Trace
+      ##
+      # @private Represents the OAuth 2.0 signing logic for Trace.
+      class Credentials < Google::Cloud::Credentials
+        SCOPE = ["https://www.googleapis.com/auth/cloud-platform"]
+        PATH_ENV_VARS = %w(TRACE_KEYFILE GOOGLE_CLOUD_KEYFILE GCLOUD_KEYFILE)
+        JSON_ENV_VARS = %w(TRACE_KEYFILE_JSON GOOGLE_CLOUD_KEYFILE_JSON
+                           GCLOUD_KEYFILE_JSON)
+
+        ##
+        # @private Create credentials with given scope and/or keyfile
+        def self.credentials_with_scope keyfile, scope = nil
+          if keyfile.nil?
+            default(scope: scope)
+          else
+            new(keyfile, scope: scope)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/google/cloud/trace/label_key.rb

@@ -0,0 +1,130 @@
+# Copyright 2014 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"
+
+module Google
+  module Cloud
+    module Trace
+      ##
+      # A collection of well-known label keys for trace spans.
+      #
+      module LabelKey
+        AGENT = "/agent"
+        COMPONENT = "/component"
+        ERROR_MESSAGE = "/error/message"
+        ERROR_NAME = "/error/name"
+        HTTP_CLIENT_CITY = "/http/client_city"
+        HTTP_CLIENT_COUNTRY = "/http/client_country"
+        HTTP_CLIENT_PROTOCOL = "/http/client_protocol"
+        HTTP_CLIENT_REGION = "/http/client_region"
+        HTTP_HOST = "/http/host"
+        HTTP_METHOD = "/http/method"
+        HTTP_REDIRECTED_URL = "/http/redirected_url"
+        HTTP_REQUEST_SIZE = "/http/request/size"
+        HTTP_RESPONSE_SIZE = "/http/response/size"
+        HTTP_STATUS_CODE = "/http/status_code"
+        HTTP_URL = "/http/url"
+        HTTP_USER_AGENT = "/http/user_agent"
+        PID = "/pid"
+        STACKTRACE = "/stacktrace"
+        TID = "/tid"
+
+        GAE_APPLICATION_ERROR = "g.co/gae/application_error"
+        GAE_APP_MODULE = "g.co/gae/app/module"
+        GAE_APP_MODULE_VERSION = "g.co/gae/app/module_version"
+        GAE_APP_VERSION = "g.co/gae/app/version"
+        GAE_DATASTORE_COUNT = "g.co/gae/datastore/count"
+        GAE_DATASTORE_CURSOR = "g.co/gae/datastore/cursor"
+        GAE_DATASTORE_ENTITY_WRITES = "g.co/gae/datastore/entity_writes"
+        GAE_DATASTORE_HAS_ANCESTOR = "g.co/gae/datastore/has_ancestor"
+        GAE_DATASTORE_HAS_CURSOR = "g.co/gae/datastore/has_cursor"
+        GAE_DATASTORE_HAS_TRANSACTION = "g.co/gae/datastore/has_transaction"
+        GAE_DATASTORE_INDEX_WRITES = "g.co/gae/datastore/index_writes"
+        GAE_DATASTORE_KIND = "g.co/gae/datastore/kind"
+        GAE_DATASTORE_LIMIT = "g.co/gae/datastore/limit"
+        GAE_DATASTORE_MORE_RESULTS = "g.co/gae/datastore/more_results"
+        GAE_DATASTORE_OFFSET = "g.co/gae/datastore/offset"
+        GAE_DATASTORE_REQUESTED_ENTITY_DELETES =
+          "g.co/gae/datastore/requested_entity_deletes"
+        GAE_DATASTORE_REQUESTED_ENTITY_PUTS =
+          "g.co/gae/datastore/requested_entity_puts"
+        GAE_DATASTORE_SIZE = "g.co/gae/datastore/size"
+        GAE_DATASTORE_SKIPPED = "g.co/gae/datastore/skipped"
+        GAE_DATASTORE_TRANSACTION_HANDLE =
+          "g.co/gae/datastore/transaction_handle"
+        GAE_ERROR_MESSAGE = "g.co/gae/error_message"
+        GAE_MEMCACHE_COUNT = "g.co/gae/memcache/count"
+        GAE_MEMCACHE_SIZE = "g.co/gae/memcache/size"
+        GAE_REQUEST_LOG_ID = "g.co/gae/request_log_id"
+
+        ##
+        # Set the stack trace label in the given labels hash. The current call
+        # stack is formatted so the Stackdriver UI will display it.
+        #
+        # @param [Hash] labels The labels hash in which to set the stack trace
+        #     label value.
+        # @param [Array<Thread::Backtrace::Location>] stack_frames The current
+        #     caller stack as returned from `::Kernel.caller_locations`. If
+        #     not set, `::Kernel.caller_locations` is called internally.
+        # @param [Integer] skip_frames Passed to the internal invocation of
+        #     `::Kernel.caller_locations` if one is needed.
+        # @param [Proc] truncate_stack A procedure that allows skipping of
+        #     the "topmost" stack frames. Stack frames, represented by
+        #     instances of `Thread::Backtrace::Location`, are passed to this
+        #     proc beginning with the topmost frame. As long as the proc
+        #     returns a falsy value, those frames are dropped. Once the proc
+        #     returns true for the first time, that frame and all remaining
+        #     frames (possibly subject to `filter_stack`) are used. If not set,
+        #     no frames are skipped.
+        # @param [Proc] filter_stack A procedure that allows skipping of
+        #     stack frames in the middle of the stack trace. After possibly
+        #     skipping frames using `truncate_stack`, all remaining frames are
+        #     passed to this proc as `Thread::Backtrace::Location` objects.
+        #     Those for whom the proc returns a falsy value are skipped. If
+        #     this parameter is not set, no filtering is done and all frames
+        #     are presented in the stack trace.
+        #
+        # @example
+        #   require "google/cloud/trace"
+        #
+        #   trace = Google::Cloud::Trace.new
+        #   span = trace.create_span "root_span"
+        #   Google::Cloud::Trace::LabelKey.set_stack_trace span.labels
+        #
+        def self.set_stack_trace labels,
+                                 stack_frames: nil, skip_frames: 1,
+                                 truncate_stack: nil, filter_stack: nil
+          stack_frames ||= ::Kernel.caller_locations skip_frames
+          json_frames = []
+          collecting_frames = !truncate_stack
+          stack_frames.each do |frame|
+            collecting_frames ||= truncate_stack.call(frame)
+            next unless collecting_frames
+            next unless !filter_stack || filter_stack.call(frame)
+            json_frames <<
+              {
+                file_name: frame.absolute_path,
+                line_number: frame.lineno,
+                method_name: frame.label
+              }
+          end
+          json_object = { stack_frame: json_frames }
+          labels[STACKTRACE] = JSON.generate json_object
+        end
+      end
+    end
+  end
+end

data/lib/google/cloud/trace/middleware.rb

@@ -0,0 +1,358 @@
+# 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 "google/cloud/core/environment"
+require "stackdriver/core/trace_context"
+
+module Google
+  module Cloud
+    module Trace
+      ##
+      # # Trace Middleware
+      #
+      # A Rack middleware that manages trace context and captures a trace of
+      # the request. Specifically, it:
+      #
+      # *   Reads the trace context from the request headers, if present.
+      #     Otherwise, generates a new trace context.
+      # *   Makes a sampling decision if one is not already specified.
+      # *   Records a span measuring the entire handling of the request,
+      #     annotated with a set of standard request data.
+      # *   Makes the trace context available so downstream middlewares and the
+      #     app can add further spans to the trace.
+      # *   Sends the completed trace to the Stackdriver service.
+      #
+      # ## Installing
+      #
+      # To use this middleware, simply install it in your middleware stack.
+      # Here is an example Sinatra application that includes the Trace
+      # middleware:
+      #
+      # ```ruby
+      # # Simple sinatra application
+      #
+      # require "sinatra"
+      # require "google/cloud/trace"
+      #
+      # use Google::Cloud::Trace::Middleware
+      #
+      # get "/" do
+      #   "Hello World!"
+      # end
+      # ```
+      #
+      # Here is an example `config.ru` file for a web application that uses
+      # the standard Rack configuration mechanism.
+      #
+      # ```ruby
+      # # config.ru for simple Rack application
+      #
+      # require "google/cloud/trace"
+      # use Google::Cloud::Trace::Middleware
+      #
+      # run MyApp
+      # ```
+      #
+      # If your application uses Ruby On Rails, you may also use the provided
+      # {Google::Cloud::Trace::Railtie} for close integration with Rails and
+      # ActiveRecord.
+      #
+      # ## Custom measurements
+      #
+      # By default, this middleware creates traces that measure just the http
+      # request handling as a whole. If you want to provide more detailed
+      # measurements of smaller processes, use the classes provided in this
+      # library. Below is a Sinatra example to get you started.
+      #
+      # ```ruby
+      # # Simple sinatra application
+      #
+      # require "sinatra"
+      # require "google/cloud/trace"
+      #
+      # use Google::Cloud::Trace::Middleware
+      #
+      # get "/" do
+      #   Google::Cloud::Trace.in_span "Sleeping on the job!" do
+      #     sleep rand
+      #   end
+      #   "Hello World!"
+      # end
+      # ```
+      #
+      # ## Sampling and blacklisting
+      #
+      # A sampler makes the decision whether to record a trace for each
+      # request (if the decision was not made by the context, e.g. by providing
+      # a request header). By default, this sampler is the default
+      # {Google::Cloud::Trace::TimeSampler}, which enforces a maximum QPS per
+      # process, and blacklists a small number of request paths such as
+      # health checks sent by Google App Engine. You may adjust this behavior
+      # by providing an alternate sampler. See
+      # {Google::Cloud::Trace::TimeSampler}.
+      #
+      class Middleware
+        ##
+        # The name of this trace agent as reported to the Stackdriver backend.
+        AGENT_NAME = "ruby #{Google::Cloud::Trace::VERSION}".freeze
+
+        ##
+        # Create a new Middleware for traces
+        #
+        # @param [Rack Application] app Rack application
+        # @param [Google::Cloud::Trace::Service] service The service object.
+        #     Optional if running on GCE.
+        # @param [Boolean] capture_stack Whether to capture stack traces for
+        #     each span. Default is false.
+        # @param [Proc] sampler A sampler to use, or `nil` to use the default.
+        #     See {Google::Cloud::Trace::TimeSampler}. Note that the sampler
+        #     may be any Proc that implements the sampling contract.
+        #
+        def initialize app,
+                       service: nil,
+                       capture_stack: false,
+                       sampler: nil,
+                       span_id_generator: nil
+          @app = app
+          @capture_stack = capture_stack
+          @sampler = sampler
+          @span_id_generator = span_id_generator
+          if service
+            @service = service
+          else
+            project_id = Google::Cloud::Trace::Project.default_project
+            @service = Google::Cloud::Trace.new.service if project_id
+          end
+        end
+
+        ##
+        # Implementation of the trace middleware. Creates a trace for this
+        # request, populates it with a root span for the entire request, and
+        # ensures it is reported back to Stackdriver.
+        #
+        # @param [Hash] env Rack environment hash
+        # @return [Rack::Response] The response from downstream Rack app
+        #
+        def call env
+          trace = create_trace env
+          begin
+            Google::Cloud::Trace.set trace
+            Google::Cloud::Trace.in_span "rack-request" do |span|
+              configure_span span, env
+              result = @app.call env
+              configure_result span, result
+              result
+            end
+          ensure
+            Google::Cloud::Trace.set nil
+            send_trace trace, env
+          end
+        end
+
+        ##
+        # Gets the current trace context from the given Rack environment.
+        # Makes a sampling decision if one has not been made already.
+        #
+        # @private
+        # @param [Hash] env Rack environment hash
+        # @return [Stackdriver::Core::TraceContext] The trace context.
+        #
+        def get_trace_context env
+          Stackdriver::Core::TraceContext.parse_rack_env(env) do |tc|
+            if tc.sampled?.nil?
+              sampler = @sampler || Google::Cloud::Trace::TimeSampler.default
+              sampled = sampler.call env
+              tc = Stackdriver::Core::TraceContext.new \
+                trace_id: tc.trace_id,
+                span_id: tc.span_id,
+                sampled: sampled,
+                capture_stack: sampled && @capture_stack
+            end
+            tc
+          end
+        end
+
+        ##
+        # Create a new trace for this request.
+        #
+        # @private
+        # @param [Hash] env The Rack environment.
+        #
+        def create_trace env
+          trace_context = get_trace_context env
+          Google::Cloud::Trace::TraceRecord.new \
+            @service.project,
+            trace_context,
+            span_id_generator: @span_id_generator
+        end
+
+        ##
+        # Send the given trace to the trace service, if requested.
+        #
+        # @private
+        # @param [Google::Cloud::Trace::TraceRecord] trace The trace to send.
+        # @param [Hash] env The Rack environment.
+        #
+        def send_trace trace, env
+          if @service && trace.trace_context.sampled?
+            begin
+              @service.patch_traces trace
+            rescue => ex
+              msg = "Transmit to Stackdriver Trace failed: #{ex.inspect}"
+              logger = env["rack.logger"]
+              if logger
+                logger.error msg
+              else
+                warn msg
+              end
+            end
+          end
+        end
+
+        ##
+        # Gets the URI path from the given Rack environment.
+        #
+        # @private
+        # @param [Hash] env Rack environment hash
+        # @return [String] The URI path.
+        #
+        def get_path env
+          path = "#{env['SCRIPT_NAME']}#{env['PATH_INFO']}"
+          path = "/#{path}" unless path.start_with? "/"
+          path
+        end
+
+        ##
+        # Gets the URI hostname from the given Rack environment.
+        #
+        # @private
+        # @param [Hash] env Rack environment hash
+        # @return [String] The hostname.
+        #
+        def get_host env
+          env["HTTP_HOST"] || env["SERVER_NAME"]
+        end
+
+        ##
+        # Gets the full URL from the given Rack environment.
+        #
+        # @private
+        # @param [Hash] env Rack environment hash
+        # @return [String] The URL.
+        #
+        def get_url env
+          path = get_path env
+          host = get_host env
+          scheme = env["rack.url_scheme"]
+          query_string = env["QUERY_STRING"].to_s
+          url = "#{scheme}://#{host}#{path}"
+          url = "#{url}?#{query_string}" unless query_string.empty?
+          url
+        end
+
+        ##
+        # Configures the root span for this request. This may be called
+        # before the request is actually handled because it doesn't depend
+        # on the result.
+        #
+        # @private
+        # @param [Google::Cloud::Trace::TraceSpan] span The root span to
+        #     configure.
+        # @param [Hash] env Rack environment hash
+        #
+        def configure_span span, env
+          span.name = get_path env
+          set_basic_labels span.labels, env
+          set_extended_labels span.labels,
+                              span.trace.trace_context.capture_stack?
+          span
+        end
+
+        ##
+        # Configures standard labels.
+        # @private
+        #
+        def set_basic_labels labels, env
+          set_label labels, Google::Cloud::Trace::LabelKey::AGENT, AGENT_NAME
+          set_label labels, Google::Cloud::Trace::LabelKey::HTTP_HOST,
+                    get_host(env)
+          set_label labels, Google::Cloud::Trace::LabelKey::HTTP_METHOD,
+                    env["REQUEST_METHOD"]
+          set_label labels,
+                    Google::Cloud::Trace::LabelKey::HTTP_CLIENT_PROTOCOL,
+                    env["SERVER_PROTOCOL"]
+          set_label labels, Google::Cloud::Trace::LabelKey::HTTP_USER_AGENT,
+                    env["HTTP_USER_AGENT"]
+          set_label labels, Google::Cloud::Trace::LabelKey::HTTP_URL,
+                    get_url(env)
+          set_label labels, Google::Cloud::Trace::LabelKey::PID,
+                    ::Process.pid.to_s
+          set_label labels, Google::Cloud::Trace::LabelKey::TID,
+                    ::Thread.current.object_id.to_s
+        end
+
+        ##
+        # Configures stack and gae labels.
+        # @private
+        #
+        def set_extended_labels labels, capture_stack
+          if capture_stack
+            Google::Cloud::Trace::LabelKey.set_stack_trace labels,
+                                                           skip_frames: 3
+          end
+          if Google::Cloud::Core::Environment.gae?
+            set_label labels, Google::Cloud::Trace::LabelKey::GAE_APP_MODULE,
+                      Google::Cloud::Core::Environment.gae_module_id
+            set_label labels,
+                      Google::Cloud::Trace::LabelKey::GAE_APP_MODULE_VERSION,
+                      Google::Cloud::Core::Environment.gae_module_version
+          end
+        end
+
+        ##
+        # Sets the given label if the given value is a proper string.
+        #
+        # @private
+        # @param [Hash] labels The labels hash.
+        # @param [String] key The key of the label to set.
+        # @param [Object] value The value to set.
+        #
+        def set_label labels, key, value
+          labels[key] = value if value.is_a? ::String
+        end
+
+        ##
+        # Performs post-request tasks, including adding result-dependent
+        # labels to the root span, and adding trace context headers to the
+        # HTTP response.
+        #
+        # @private
+        # @param [Google::Cloud::Trace::TraceSpan] span The root span to
+        #     configure.
+        # @param [Array] result The Rack response.
+        #
+        def configure_result span, result
+          if result.is_a?(::Array) && result.size == 3
+            span.labels[Google::Cloud::Trace::LabelKey::HTTP_STATUS_CODE] =
+                result[0].to_s
+            result[1]["X-Cloud-Trace-Context"] =
+                span.trace.trace_context.to_string
+          end
+          result
+        end
+      end
+    end
+  end
+end