google-cloud-trace 0.24.1 → 0.25.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 7d5b72d035764de99271f31c75142c60aa57d7c4
-  data.tar.gz: 3c9b634aca6752419a66985aebbf5aaa274b3b08
+  metadata.gz: 537ea43256a80488f659a7b6ed8f41f23f935e13
+  data.tar.gz: 4e0d0e17d29ffac6d6323eaebf2838332f14c072
 SHA512:
-  metadata.gz: b7e30ed03c81da3e0e9b11ad3bf429fc46893e1f931aa99c516df818296bcc4a3ed74bf5f77650b384971b8d3c0474e8ff996edc718f66202a66f99e3e08ff52
-  data.tar.gz: 226c2a1caa3a9d2748d98a9cbeca8a2a2aed6b115dd76e669b110e1c3c9cba454493da3c30fd335c665191834e403057eb1c742d0cd6b4e148464c5c93366f28
+  metadata.gz: b874bb6c50a4b10f634311b69b45055551061b21f75125823edec6f78c181d87a0efb8ae241eb4e47a3fb7c28f259e2b6dc27c47b047332784a0e758505c7e56
+  data.tar.gz: 451c43e68ad1ca3561306c9f4a30a060ce33838d0fff9a11d303065aa0dd2f985bfe57c2c53115d0ab41230900b380ed79a8026d734deac164f809eb6222eb2b

data/README.md

@@ -1,45 +1,94 @@
-Stackdriver Trace API for Ruby
-=================================================
+# google-cloud-trace
 
-google-cloud-trace uses [Google API extensions][google-gax] to provide an
-easy-to-use client library for the [Stackdriver Trace API][] (v1) defined in the [googleapis][] git repository
+[Stackdriver Trace](https://cloud.google.com/trace/) is a distributed tracing 
+system that collects latency data from your applications and displays it in the 
+Google Cloud Platform Console. You can track how requests propagate through your
+application and receive detailed near real-time performance insights. 
+Stackdriver Trace automatically analyzes all of your application's traces to 
+generate in-depth latency reports to surface performance degradations, and can 
+capture traces from all of your VMs, containers, or Google App Engine projects.
 
+- [google-cloud-trace API documentation](http://googlecloudplatform.github.io/google-cloud-ruby/#/docs/google-cloud-trace/latest)
+- [google-cloud-trace instrumentation documentation](https://googlecloudplatform.github.io/google-cloud-ruby/#/docs/google-cloud-trace/guides/instrumentation)
+- [google-cloud-trace on RubyGems](https://rubygems.org/gems/google-cloud-trace)
+- [Stackdriver Trace documentation](https://cloud.google.com/trace/docs/)
 
-[googleapis]: https://github.com/googleapis/googleapis/tree/master/google/devtools/cloudtrace/v1
-[google-gax]: https://github.com/googleapis/gax-ruby
-[Stackdriver Trace API]: https://developers.google.com/apis-explorer/#p/cloudtrace/v1/
+## Quick Start
+```sh
+$ gem install google-cloud-trace
+```
 
-Getting started
----------------
+## Authentication
 
-google-cloud-trace will allow you to connect to the [Stackdriver Trace API][] and access all its methods.
+The Instrumentation client and API use Service Account credentials to connect 
+to Google Cloud services. When running on Google Cloud Platform environments, 
+the credentials will be discovered automatically. When running on other 
+environments the Service Account credentials can be specified by providing the 
+path to the JSON file, or the JSON itself, in environment variables or 
+configuration code.
 
-In order to achieve so you need to set up authentication as well as install the library locally.
+Instructions and configuration options are covered in the 
+[Authentication Guide](https://googlecloudplatform.github.io/google-cloud-ruby/#/docs/google-cloud-trace/guides/authentication).
 
+## Example
 
-Setup Authentication
---------------------
+```ruby
+require "google/cloud/trace"
 
-To authenticate all your API calls, first install and setup the [Google Cloud SDK][].
-Once done, you can then run the following command in your terminal:
+trace = Google::Cloud::Trace.new
 
-    $ gcloud beta auth application-default login
+result_set = trace.list_traces Time.now - 3600, Time.now
+result_set.each do |trace_record|
+  puts "Retrieved trace ID: #{trace_record.trace_id}"
+end
+```
 
-or
+## Rails and Rack Integration
 
-    $ gcloud auth login
+This library also provides a built-in Railtie for Ruby on Rails integration. To
+ do this, simply add this line to config/application.rb:
+```ruby
+require "google/cloud/trace/rails"
+```
 
-Please see [gcloud beta auth application-default login][] document for the difference between these commands.
+Alternatively, check out the [stackdriver](../stackdriver) gem, which includes 
+this library and enables the Railtie by default.
 
-[Google Cloud SDK]: https://cloud.google.com/sdk/
-[gcloud beta auth application-default login]: https://cloud.google.com/sdk/gcloud/reference/beta/auth/application-default/login
+For Rack integration and more examples, see the
+[Instrumentation Guide](https://googlecloudplatform.github.io/google-cloud-ruby/#/docs/google-cloud-error_reporting/guides/instrumentation).
 
+## Supported Ruby Versions
 
-Installation
--------------------
+This library is supported on Ruby 2.0+.
 
-Install this library using gem:
+## Versioning
 
-    $ [sudo] gem install google-cloud-trace
+This library follows [Semantic Versioning](http://semver.org/).
 
-At this point you are all set to continue.
+It is currently in major version zero (0.y.z), which means that anything may 
+change at any time and the public API should not be considered stable.
+
+## Contributing
+
+Contributions to this library are always welcome and highly encouraged.
+
+See the 
+[Contributing Guide](https://googlecloudplatform.github.io/google-cloud-ruby/#/docs/guides/contributing) 
+for more information on how to get started.
+
+Please note that this project is released with a Contributor Code of Conduct. By
+participating in this project you agree to abide by its terms. See 
+[Code of Conduct](../CODE_OF_CONDUCT.md) for more information.
+
+## License
+
+This library is licensed under Apache 2.0. Full license text is available in
+ [LICENSE](LICENSE).
+
+## Support
+
+Please 
+[report bugs at the project on Github](https://github.com/GoogleCloudPlatform/google-cloud-ruby/issues).
+Don't hesitate to 
+[ask questions](http://stackoverflow.com/questions/tagged/google-cloud-platform+ruby) 
+about the client or APIs on [StackOverflow](http://stackoverflow.com).

data/lib/google/cloud/trace.rb

@@ -13,7 +13,6 @@
 # limitations under the License.
 
 
-require "stackdriver/core/trace_context"
 require "google-cloud-trace"
 require "google/cloud/trace/version"
 require "google/cloud/trace/credentials"
@@ -28,11 +27,12 @@ require "google/cloud/trace/span_kind"
 require "google/cloud/trace/time_sampler"
 require "google/cloud/trace/trace_record"
 require "google/cloud/trace/utils"
+require "stackdriver/core"
 
 module Google
   module Cloud
     ##
-    # # Stackdriver Trace
+    # # Trace
     #
     # The Stackdriver Trace service collects and stores latency data from your
     # application and displays it in the Google Cloud Platform Console, giving
@@ -191,6 +191,12 @@ module Google
     module Trace
       THREAD_KEY = :__stackdriver_trace_span__
 
+      # Initialize :error_reporting as a nested Configuration under
+      # Google::Cloud if haven't already
+      unless Google::Cloud.configure.option? :trace
+        Google::Cloud.configure.add_options :trace
+      end
+
       ##
       # Creates a new object for connecting to the Stackdriver Trace service.
       # Each call creates a new connection.
@@ -335,6 +341,22 @@ module Google
           yield nil
         end
       end
+
+      ##
+      # Configure the Stackdriver Trace instrumentation Middleware.
+      #
+      # See the [Configuration
+      # Guide](https://googlecloudplatform.github.io/google-cloud-ruby/#/docs/stackdriver/guides/instrumentation_configuration)
+      # for full configuration parameters.
+      #
+      # @return [Stackdriver::Core::Configuration] The configuration object
+      #   the Google::Cloud::ErrorReporting module uses.
+      #
+      def self.configure
+        yield Google::Cloud.configure.trace if block_given?
+
+        Google::Cloud.configure.trace
+      end
     end
   end
 end

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

@@ -114,26 +114,23 @@ module Google
         # @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.
+        # @param [Hash] *kwargs Hash of configuration settings. Used for
+        #   backward API compatibility. See the [Configuration
+        #   Guide](https://googlecloudplatform.github.io/google-cloud-ruby/#/docs/stackdriver/guides/instrumentation_configuration)
+        #   for the prefered way to set configuration parameters.
         #
-        def initialize app,
-                       service: nil,
-                       capture_stack: false,
-                       sampler: nil,
-                       span_id_generator: nil
+        def initialize app, service: nil, **kwargs
           @app = app
-          @capture_stack = capture_stack
-          @sampler = sampler
-          @span_id_generator = span_id_generator
+
+          load_config kwargs
+
           if service
             @service = service
           else
-            project_id = Google::Cloud::Trace::Project.default_project
-            @service = Google::Cloud::Trace.new.service if project_id
+            project_id = configuration.project_id
+            if project_id
+              @service = Google::Cloud::Trace.new(project: project_id).service
+            end
           end
         end
 
@@ -172,13 +169,14 @@ module Google
         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
+              sampler = configuration.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
+                capture_stack: sampled && configuration.capture_stack
             end
             tc
           end
@@ -195,7 +193,7 @@ module Google
           Google::Cloud::Trace::TraceRecord.new \
             @service.project,
             trace_context,
-            span_id_generator: @span_id_generator
+            span_id_generator: configuration.span_id_generator
         end
 
         ##
@@ -352,6 +350,38 @@ module Google
           end
           result
         end
+
+        private
+
+        ##
+        # Consolidate configurations from various sources. Also set
+        # instrumentation config parameters to default values if not set
+        # already.
+        #
+        def load_config **kwargs
+          configuration.capture_stack = kwargs[:capture_stack] ||
+                                        configuration.capture_stack
+          configuration.sampler = kwargs[:sampler] ||
+                                  configuration.sampler
+          configuration.span_id_generator = kwargs[:span_id_generator] ||
+                                            configuration.span_id_generator
+
+          init_default_config
+        end
+
+        ##
+        # Fallback to default configuration values if not defined already
+        def init_default_config
+          configuration.project_id ||= Cloud.configure.project_id ||
+                                       Trace::Project.default_project
+          configuration.capture_stack ||= false
+        end
+
+        ##
+        # @private Get Google::Cloud::Trace.configure
+        def configuration
+          Google::Cloud::Trace.configure
+        end
       end
     end
   end

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

@@ -43,59 +43,9 @@ module Google
       #
       # ## 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.
+      # See the [Configuration
+      # Guide](https://googlecloudplatform.github.io/google-cloud-ruby/#/docs/stackdriver/guides/instrumentation_configuration)
+      # on how to configure the Railtie and Middleware.
       #
       # ## Measuring custom functionality
       #
@@ -135,67 +85,9 @@ module Google
           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
+          self.class.consolidate_rails_config app.config
 
-          # 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
-            STDOUT.puts "Note: Google::Cloud::Trace is disabled because " \
-              "it failed to authorize with the service. (#{e.message})"
-            return false
-          end
-
-          if project_id(config).to_s.empty?
-            STDOUT.puts "Note: Google::Cloud::Trace is disabled because " \
-              "the project ID could not be determined."
-            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.env.project_id
+          self.class.init_middleware app if Cloud.configure.use_trace
         end
 
         ##
@@ -204,11 +96,10 @@ module Google
         #
         # @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
+        def self.init_middleware app
+          trace_config = Trace.configure
+          project_id = trace_config.project_id
+          keyfile = trace_config.keyfile
 
           tracer = Google::Cloud::Trace.new project: project_id,
                                             keyfile: keyfile
@@ -216,8 +107,7 @@ module Google
           app.middleware.insert_before \
             Rack::Runtime,
             Google::Cloud::Trace::Middleware,
-            service: tracer.service,
-            capture_stack: trace_config.capture_stack
+            service: tracer.service
 
           trace_config.notifications.each do |type|
             Google::Cloud::Trace::Notifications.instrument \
@@ -226,6 +116,86 @@ module Google
               capture_stack: trace_config.capture_stack
           end
         end
+
+        ##
+        # @private Consolidate Rails configuration into Trace instrumentation
+        # configuration. Also consolidate the `use_trace` setting by verifying
+        # credentials and Rails environment. The `use_trace` setting will be
+        # true if credentials are valid, and the setting is manually set to
+        # true or Rails is in production environment.
+        #
+        # @param [Rails::Railtie::Configuration] config The
+        #   Rails.application.config
+        #
+        def self.consolidate_rails_config config
+          merge_rails_config config
+
+          init_default_config
+
+          # Done if Google::Cloud.configure.use_trace is explicitly false
+          return if Google::Cloud.configure.use_trace == false
+
+          # Verify credentials and set use_error_reporting to false if
+          # credentials are invalid
+          unless valid_credentials? Trace.configure.project_id,
+                                    Trace.configure.keyfile
+            Cloud.configure.use_trace = false
+            return
+          end
+
+          # Otherwise set use_trace to true if Rails is running in production
+          Google::Cloud.configure.use_trace ||= Rails.env.production?
+        end
+
+        ##
+        # @private Merge Rails configuration into Trace instrumentation
+        # configuration.
+        def self.merge_rails_config rails_config
+          gcp_config = rails_config.google_cloud
+          trace_config = gcp_config.trace
+
+          Cloud.configure.use_trace ||= gcp_config.use_trace
+          Trace.configure do |config|
+            config.project_id ||= trace_config.project_id ||
+                                  gcp_config.project_id
+            config.keyfile ||= trace_config.keyfile || gcp_config.keyfile
+            config.notifications ||= trace_config.notifications
+            config.max_data_length ||= trace_config.max_data_length
+            config.capture_stack ||= trace_config.capture_stack
+            config.sampler ||= trace_config.sampler
+            config.span_id_generator ||= trace_config.span_id_generator
+          end
+        end
+
+        ##
+        # Fallback to default config values if config parameters not provided.
+        def self.init_default_config
+          Trace.configure.project_id ||= Trace::Project.default_project
+        end
+
+        ##
+        # @private Verify credentials
+        def self.valid_credentials? project_id, keyfile
+          begin
+            Google::Cloud::Trace::Credentials.credentials_with_scope keyfile
+          rescue Exception => e
+            STDOUT.puts "Note: Google::Cloud::Trace is disabled because " \
+              "it failed to authorize with the service. (#{e.message})"
+            return false
+          end
+
+          if project_id.to_s.empty?
+            STDOUT.puts "Note: Google::Cloud::Trace is disabled because " \
+              "the project ID could not be determined."
+            return false
+          end
+
+          true
+        end
+
+        private_class_method :merge_rails_config,
+                             :init_default_config,
+                             :valid_credentials?
       end
     end
   end

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

@@ -32,7 +32,8 @@ module Google
       #   env = my_get_rack_environment
       #   trace_context = Stackdriver::Core::TraceContext.parse_rack_env env
       #
-      #   trace = Google::Cloud::Trace.new "my-project", trace_context
+      #   trace = Google::Cloud::Trace::TraceRecord.new "my-project",
+      #                                                 trace_context
       #   span = trace.create_span "root_span"
       #   subspan = span.create_span "subspan"
       #

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

@@ -16,7 +16,7 @@
 module Google
   module Cloud
     module Trace
-      VERSION = "0.24.1".freeze
+      VERSION = "0.25.0".freeze
     end
   end
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: google-cloud-trace
 version: !ruby/object:Gem::Version
-  version: 0.24.1
+  version: 0.25.0
 platform: ruby
 authors:
 - Daniel Azuma
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2017-04-21 00:00:00.000000000 Z
+date: 2017-05-26 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: google-cloud-core
@@ -30,14 +30,14 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '1.0'
+        version: '1.1'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '1.0'
+        version: '1.1'
 - !ruby/object:Gem::Dependency
   name: google-gax
   requirement: !ruby/object:Gem::Requirement
@@ -225,7 +225,7 @@ files:
 - lib/google/cloud/trace/version.rb
 - lib/google/devtools/cloudtrace/v1/trace_pb.rb
 - lib/google/devtools/cloudtrace/v1/trace_services_pb.rb
-homepage: http://googlecloudplatform.github.io/google-cloud-ruby/
+homepage: https://github.com/GoogleCloudPlatform/google-cloud-ruby/tree/master/google-cloud-trace
 licenses:
 - Apache-2.0
 metadata: {}
@@ -245,7 +245,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
       version: '0'
 requirements: []
 rubyforge_project: 
-rubygems_version: 2.6.11
+rubygems_version: 2.6.12
 signing_key: 
 specification_version: 4
 summary: Application Instrumentation and API Client library for Stackdriver Trace