google-cloud-trace 0.21.0

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

@@ -0,0 +1,115 @@
+# 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.
+
+
+module Google
+  module Cloud
+    module Trace
+      ##
+      # Utility methods for configuring ActiveSupport notifications to generate
+      # spans in the current trace.
+      #
+      module Notifications
+        ##
+        # The default max length for label data.
+        DEFAULT_MAX_DATA_LENGTH = 1024
+
+        ##
+        # The default prefix for label keys
+        DEFAULT_LABEL_NAMESPACE = "/ruby/"
+
+        ##
+        # Stack truncation method that removes the ActiveSupport::Notifications
+        # calls from the top.
+        REMOVE_NOTIFICATION_FRAMEWORK =
+          lambda do |frame|
+            frame.absolute_path !~ %r{/lib/active_support/notifications}
+          end
+
+        ##
+        # Subscribes to the given event type or any type matching the given
+        # pattern. When an event is raised, a span is generated in the current
+        # thread's trace. The event payload is exposed as labels on the span.
+        # If there is no active trace for the current thread, then no span is
+        # generated.
+        #
+        # @param [String, Regex] type A specific type or pattern to select
+        #     notifications to listen for.
+        # @param [Integer] max_length The maximum length for label values.
+        #     If a label value exceeds this length, it is truncated.
+        #     If the length is nil, no truncation takes place.
+        # @param [String] label_namespace A string to prepend to all label
+        #     keys.
+        # @param [Boolean] capture_stack Whether traces should include the
+        #     call stack.
+        #
+        # @example
+        #
+        #   require "google/cloud/trace"
+        #   require "activerecord"
+        #
+        #   Google::Cloud::Trace::Notifications.instrument "sql.activerecord"
+        #
+        #   trace = Google::Cloud::Trace::Trace.new
+        #   Google::Cloud::Trace.set trace
+        #   ActiveRecord::Base.query "SHOW TABLES"
+        #
+        def self.instrument type,
+                            max_length: DEFAULT_MAX_DATA_LENGTH,
+                            label_namespace: DEFAULT_LABEL_NAMESPACE,
+                            capture_stack: false
+          require "active_support/notifications"
+          ActiveSupport::Notifications.subscribe(type) do |*args|
+            event = ActiveSupport::Notifications::Event.new(*args)
+            handle_notification_event event, max_length, label_namespace,
+                                      capture_stack
+          end
+        end
+
+        ##
+        # @private
+        def self.handle_notification_event event, maxlen, label_namespace,
+                                           capture_stack
+          cur_span = Google::Cloud::Trace.get
+          if cur_span && event.time && event.end
+            labels = payload_to_labels event, maxlen, label_namespace
+            if capture_stack
+              Google::Cloud::Trace::LabelKey.set_stack_trace \
+                labels,
+                skip_frames: 2,
+                truncate_stack: REMOVE_NOTIFICATION_FRAMEWORK
+            end
+            cur_span.create_span event.name,
+                                 start_time: event.time,
+                                 end_time: event.end,
+                                 labels: labels
+          end
+        end
+
+        ##
+        # @private
+        def self.payload_to_labels event, maxlen, label_namespace
+          labels = {}
+          event.payload.each do |k, v|
+            if v.is_a? ::String
+              v = v[0, maxlen-3] + "..." if maxlen && v.size > maxlen
+              labels["#{label_namespace}#{k}"] = v
+            end
+          end
+          labels
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,219 @@
+# 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/core/environment"
+
+module Google
+  module Cloud
+    module Trace
+      ##
+      # # Project
+      #
+      # Projects are top-level containers in Google Cloud Platform. They store
+      # information about billing and authorized users, and they control access
+      # to Stackdriver Trace resources. Each project has a friendly name and a
+      # unique ID. Projects can be created only in the [Google Developers
+      # Console](https://console.developers.google.com).
+      #
+      # This class is a client to make API calls for the project's trace data.
+      # Create an instance using {Google::Cloud::Trace.new} or
+      # {Google::Cloud#trace}. You may then use the `get_trace` method to
+      # retrieve a trace by ID, `list_traces` to query for a set of traces,
+      # and `patch_traces` to update trace data. You may also use `new_trace`
+      # as a convenience constructor to build a
+      # {Google::Cloud::Trace::TraceRecord} object.
+      #
+      # @example
+      #   require "google/cloud/trace"
+      #
+      #   trace_client = Google::Cloud::Trace.new
+      #   traces = trace_client.list_traces Time.now - 3600, Time.now
+      #
+      class Project
+        ##
+        # @private The Service object.
+        attr_accessor :service
+
+        ##
+        # @private Creates a new Project instance.
+        def initialize service
+          @service = service
+        end
+
+        ##
+        # The ID of the current project.
+        #
+        # @return [String] the Google Cloud project ID
+        #
+        # @example
+        #   require "google/cloud/trace"
+        #
+        #   trace_client = Google::Cloud::Trace.new(
+        #     project: "my-project",
+        #     keyfile: "/path/to/keyfile.json"
+        #   )
+        #
+        #   trace_client.project #=> "my-project"
+        #
+        def project
+          service.project
+        end
+
+        ##
+        # Create a new empty trace record for this project. Uses the current
+        # thread's TraceContext by default; otherwise you may provide a
+        # specific TraceContext.
+        #
+        # @param [Stackdriver::Core::TraceContext, nil] trace_context The
+        #     context within which to locate this trace (i.e. sets the trace ID
+        #     and the context parent span, if present.) If the context is set
+        #     explicitly to `nil`, a new trace with a new trace ID is created.
+        #     If no context is provided, the current thread's context is used.
+        # @return [Google::Cloud::Trace::TraceRecord] The new trace.
+        #
+        # @example
+        #   require "google/cloud/trace"
+        #
+        #   trace_client = Google::Cloud::Trace.new(
+        #     project: "my-project",
+        #     keyfile: "/path/to/keyfile.json"
+        #   )
+        #
+        #   trace = trace_client.new_trace
+        #
+        def new_trace trace_context: :DEFAULT
+          if trace_context == :DEFAULT
+            trace_context = Stackdriver::Core::TraceContext.get
+          end
+          Google::Cloud::Trace::TraceRecord.new project, trace_context
+        end
+
+        ##
+        # Sends new traces to Stackdriver Trace or updates existing traces.
+        # If the ID of a trace that you send matches that of an existing trace,
+        # any fields in the existing trace and its spans are overwritten by the
+        # provided values, and any new fields provided are merged with the
+        # existing trace data. If the ID does not match, a new trace is created.
+        #
+        # @param [Google::Cloud::Trace::TraceRecord,
+        #     Array{Google::Cloud::Trace::TraceRecord}] traces Either a single
+        #     trace object or an array of trace objects.
+        # @return [Array{Google::Cloud::Trace::TraceRecord}] The traces written.
+        #
+        # @example
+        #   require "google/cloud/trace"
+        #
+        #   trace_client = Google::Cloud::Trace.new
+        #
+        #   trace = trace_client.new_trace
+        #   trace.in_span "root_span" do
+        #     # Do stuff...
+        #   end
+        #
+        #   trace_client.patch_traces trace
+        #
+        def patch_traces traces
+          ensure_service!
+          service.patch_traces traces
+        end
+
+        ##
+        # Gets a single trace by its ID.
+        #
+        # @param [String] trace_id The ID of the trace to fetch.
+        # @return [Google::Cloud::Trace::TraceRecord, nil] The trace object, or
+        #     `nil` if there is no accessible trace with the given ID.
+        #
+        # @example
+        #   require "google/cloud/trace"
+        #
+        #   trace_client = Google::Cloud::Trace.new
+        #
+        #   trace = trace_client.get_trace "1234567890abcdef1234567890abcdef"
+        #
+        def get_trace trace_id
+          ensure_service!
+          service.get_trace trace_id
+        end
+
+        ##
+        # Returns of a list of traces that match the specified conditions.
+        # You must provide a time interval. You may optionally provide a
+        # filter, an ordering, a view type.
+        # Results are paginated, and you may specify a page size. The result
+        # will come with a token you can pass back to retrieve the next page.
+        #
+        # @param [Time] start_time The start of the time interval (inclusive).
+        # @param [Time] end_time The end of the time interval (inclusive).
+        # @param [String] filter An optional filter.
+        # @param [String] order_by The optional sort order for returned traces.
+        #     May be `trace_id`, `name`, `duration`, or `start`. Any sort order
+        #     may also be reversed by appending `desc`; for example use
+        #     `start desc` to order traces from newest to oldest.
+        # @param [Symbol] view The optional type of view. Valid values are
+        #     `:MINIMAL`, `:ROOTSPAN`, and `:COMPLETE`. Default is `:MINIMAL`.
+        # @param [Integer] page_size The size of each page to return. Optional;
+        #     if omitted, the service will select a reasonable page size.
+        # @param [String] page_token A token indicating the page to return.
+        #     Each page of results includes proper token for specifying the
+        #     following page.
+        # @return [Google::Cloud::Trace::ResultSet] A page of results.
+        #
+        # @example
+        #   require "google/cloud/trace"
+        #
+        #   trace_client = Google::Cloud::Trace.new
+        #
+        #   traces = trace_client.list_traces Time.now - 3600, Time.now
+        #   traces.each do |trace|
+        #     puts "Retrieved trace ID: #{trace.trace_id}"
+        #   end
+        #
+        def list_traces start_time, end_time,
+                        filter: nil,
+                        order_by: nil,
+                        view: nil,
+                        page_size: nil,
+                        page_token: nil
+          ensure_service!
+          service.list_traces project, start_time, end_time,
+                              filter: filter,
+                              order_by: order_by,
+                              view: view,
+                              page_size: page_size,
+                              page_token: page_token
+        end
+
+        ##
+        # @private Default project.
+        def self.default_project
+          ENV["TRACE_PROJECT"] ||
+            ENV["GOOGLE_CLOUD_PROJECT"] ||
+            ENV["GCLOUD_PROJECT"] ||
+            Google::Cloud::Core::Environment.project_id
+        end
+
+        protected
+
+        ##
+        # @private Raise an error unless an active connection to the service is
+        # available.
+        def ensure_service!
+          fail "Must have active connection to service" unless service
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,231 @@
+# 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 "google/cloud/trace"
+
+
+module Google
+  module Cloud
+    module Trace
+      ##
+      # # Rails integration for Stackdriver Trace
+      #
+      # This Railtie is a drop-in Stackdriver Trace instrumentation plugin
+      # for Ruby on Rails applications. If present, it automatically
+      # instruments your Rails app to record performance traces and cause them
+      # to appear on your Stackdriver console.
+      #
+      # ## Installation
+      #
+      # To install this plugin, the gem `google-cloud-trace` must be in your
+      # Gemfile. You also must add the following line to your `application.rb`
+      # file:
+      #
+      # ```ruby
+      # require "google/cloud/trace/rails"
+      # ```
+      #
+      # If you include the `stackdriver` gem in your Gemfile, the above is done
+      # for you automatically, and you do not need to edit your
+      # `application.rb`.
+      #
+      # ## Configuration
+      #
+      # The following Rails configuration options are recognized.
+      #
+      # ```ruby
+      # config.google_cloud.use_trace = true | false
+      # ```
+      #
+      # Normally, tracing is activated when `RAILS_ENV` is set to `production`
+      # and credentials are available. You can override this and enable tracing
+      # in other environments by setting `use_trace` explicitly.
+      #
+      # ```ruby
+      # config.google_cloud.keyfile = "path/to/file"
+      # ```
+      #
+      # If your application is running on Google Cloud Platform, it will
+      # automatically use credentials available to your project. However, if
+      # you are running an application locally or on a different hosting
+      # provider, you may provide a path to your credentials file using this
+      # configuration.
+      #
+      # ```ruby
+      # config.google_cloud.project_id = "my-project-id"
+      # ```
+      #
+      # If your application is running on Google Cloud Platform, it will
+      # automatically select the project under which it is running. However, if
+      # you are running an application locally or on a different hosting
+      # provider, or if you want to log traces to a different project than you
+      # are using to host your application, you may provide the project ID.
+      #
+      # ```ruby
+      # config.google_cloud.trace.notifications = ["event1", "event2"]
+      # ```
+      #
+      # By default, this Railtie subscribes to ActiveSupport notifications
+      # emitted by ActiveRecord queries, rendering, and emailing functions.
+      # See {DEFAULT_NOTIFICATIONS}. If you want to customize the list of
+      # notification types, edit the notifications configuration.
+      #
+      # ```ruby
+      # config.google_cloud.trace.max_data_length = 1024
+      # ```
+      #
+      # The maximum length of span properties recorded with ActiveSupport
+      # notification events. Any property value larger than this length is
+      # truncated.
+      #
+      # ```ruby
+      # config.google_cloud.trace.capture_stack = true | false
+      # ```
+      #
+      # Whether to capture the call stack with each trace span. Default is
+      # false.
+      #
+      # ## Measuring custom functionality
+      #
+      # To add a custom measurement to a request trace, use the classes
+      # provided in this library. Below is an example to get you started.
+      #
+      # ```ruby
+      # class MyController < ApplicationController
+      #   def index
+      #     Google::Cloud::Trace.in_span "Sleeping on the job!" do
+      #       sleep rand
+      #     end
+      #     render plain: "Hello World!"
+      #   end
+      # end
+      # ```
+      #
+      class Railtie < ::Rails::Railtie
+        ##
+        # The default list of ActiveSupport notification types to include in
+        # traces.
+        #
+        DEFAULT_NOTIFICATIONS = [
+          "sql.active_record",
+          "render_template.action_view",
+          "send_file.action_controller",
+          "send_data.action_controller",
+          "deliver.action_mailer"
+        ].freeze
+
+        unless config.respond_to? :google_cloud
+          config.google_cloud = ActiveSupport::OrderedOptions.new
+        end
+        config.google_cloud.trace = ActiveSupport::OrderedOptions.new
+        config.google_cloud.trace.notifications = DEFAULT_NOTIFICATIONS.dup
+        config.google_cloud.trace.max_data_length =
+          Google::Cloud::Trace::Notifications::DEFAULT_MAX_DATA_LENGTH
+
+        initializer "Google.Cloud.Trace" do |app|
+          if Google::Cloud::Trace::Railtie.use_trace? app.config
+            Google::Cloud::Trace::Railtie.init_trace app
+          end
+        end
+
+        ##
+        # Determine whether to use Stackdriver Trace or not.
+        #
+        # Returns true if valid GCP project_id and keyfile are provided and
+        # either Rails is in "production" environment or
+        # config.google_cloud.use_trace is explicitly true. Otherwise false.
+        #
+        # @param [Rails::Railtie::Configuration] config The
+        #     Rails.application.config
+        #
+        # @return [Boolean] Whether to use Stackdriver Trace
+        #
+        def self.use_trace? config
+          gcp_config = config.google_cloud
+
+          # Return false if config.google_cloud.use_trace is
+          # explicitly false
+          return false if gcp_config.key?(:use_trace) &&
+                          !gcp_config.use_trace
+
+          # Try authenticate authorize client API. Return false if unable to
+          # authorize.
+          keyfile = gcp_config.trace.keyfile || gcp_config.keyfile
+          begin
+            Google::Cloud::Trace::Credentials.credentials_with_scope keyfile
+          rescue Exception => e
+            warn "Unable to initialize Google::Cloud::Trace due " \
+              "to authorization error: #{e.message}"
+            return false
+          end
+
+          if project_id(config).to_s.empty?
+            warn "Google::Cloud::Trace is not activated due to empty project_id"
+            return false
+          end
+
+          # Otherwise return true if Rails is running in production or
+          # config.google_cloud.use_trace is explicitly true
+          Rails.env.production? ||
+            (gcp_config.key?(:use_trace) && gcp_config.use_trace)
+        end
+
+        ##
+        # Return the effective project ID for this app, given a Rails config.
+        #
+        # @param [Rails::Railtie::Configuration] config The
+        #     Rails.application.config
+        # @return [String] The project ID, or nil if not found.
+        #
+        def self.project_id config
+          config.google_cloud.trace.project_id ||
+            config.google_cloud.project_id ||
+            ENV["TRACE_PROJECT"] ||
+            ENV["GOOGLE_CLOUD_PROJECT"] ||
+            Google::Cloud::Core::Environment.project_id
+        end
+
+        ##
+        # Initialize trace integration for Rails. Sets up the configuration,
+        # adds and configures middleware, and installs notifications.
+        #
+        # @private
+        #
+        def self.init_trace app
+          gcp_config = app.config.google_cloud
+          trace_config = gcp_config.trace
+          project_id = trace_config.project_id || gcp_config.project_id
+          keyfile = trace_config.keyfile || gcp_config.keyfile
+
+          tracer = Google::Cloud::Trace.new project: project_id,
+                                            keyfile: keyfile
+
+          app.middleware.insert_before \
+            Rack::Runtime,
+            Google::Cloud::Trace::Middleware,
+            service: tracer.service,
+            capture_stack: trace_config.capture_stack
+
+          trace_config.notifications.each do |type|
+            Google::Cloud::Trace::Notifications.instrument \
+              type,
+              max_length: trace_config.max_data_length,
+              capture_stack: trace_config.capture_stack
+          end
+        end
+      end
+    end
+  end
+end