google-cloud-trace 0.27.1 → 0.27.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 975ed7f4bb02a5e59ce4fca105d238f3ca7dbe1a
-  data.tar.gz: b4f90c3860ffc78f4629b33e09389acfeb97902e
+  metadata.gz: 738619f7020791ff599a950fc987c8e725712e4c
+  data.tar.gz: 22a78c9abed2cfc846a41ce294e9227f36c27af7
 SHA512:
-  metadata.gz: 03b6604e0d41b91a6c407b21669132d01402e4efef40387b5dcb6d689439f60f99b2fd278ce0aa6e08bf42e1cce58832552edbb2810177ca0c92eb2263d6d5c1
-  data.tar.gz: '09aa20c57a10bbfffcf47023a7e764556ab6620bb0c68c2ab6fc03943be7bb25ef5028c8ee60222e3018e1a7b5b4037ba06eee346bdd38b096620cf1bf024920'
+  metadata.gz: 85b5c5f7960a4af52650d0376480d6e6f7e82bf901e986e19c743e13f25cab8095a5e5d57c06b50fbf8a9c5334aa7cffbe445b09e1e0dde99a134d79f2d63770
+  data.tar.gz: 0eed3070b782306da41e78bf9b336023671ff151f77aee648a27c00916f711f760642428a578df61c9d8f6ebb949e4d3fdccb56b610c2e07721ecd9f96aa2ca5

data/README.md

@@ -14,48 +14,174 @@ capture traces from all of your VMs, containers, or Google App Engine projects.
 - [Stackdriver Trace documentation](https://cloud.google.com/trace/docs/)
 
 ## Quick Start
+
+Install the gem directly:
+
 ```sh
 $ gem install google-cloud-trace
 ```
 
-## Authentication
+Or install through Bundler:
 
-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.
+1. Add the `google-cloud-cloud` gem to your Gemfile:
+
+```ruby
+gem "google-cloud-cloud"
+```
+
+2. Use Bundler to install the gem:
+
+```sh
+$ bundle install
+```
+
+Alternatively, check out the [`stackdriver`](../stackdriver) gem that includes 
+the `google-cloud-cloud` gem.
+
+## Enable Stackdriver Trace API
 
-Instructions and configuration options are covered in the 
-[Authentication Guide](https://googlecloudplatform.github.io/google-cloud-ruby/#/docs/google-cloud-trace/guides/authentication).
+The Stackdriver Trace library needs the [Stackdriver Trace 
+API](https://console.cloud.google.com/apis/library/cloudtrace.googleapis.com) 
+to be enabled on your Google Cloud project. Make sure it's enabled if not 
+already.
 
-## Example
+## Tracing on Rack-based frameworks
+
+The Stackdriver Trace library for Ruby makes it easy to integrate Stackdriver 
+Trace into popular Rack-based Ruby web frameworks such as Ruby on Rails and 
+Sinatra. When the library integration is enabled, it automatically traces 
+incoming requests in the application.
+
+### With Ruby on Rails
+
+You can load the Railtie that comes with the library into your Ruby 
+on Rails application by explicitly requiring it during the application startup:
+
+```ruby
+# In config/application.rb
+require "google/cloud/trace/rails"
+```
+
+If you're using the `stackdriver` gem, it automatically loads the Railtie into 
+your application when it starts.
+
+### With other Rack-based frameworks
+
+Other Rack-based frameworks, such as Sinatra, can use the Rack Middleware 
+provided by the library:
 
 ```ruby
 require "google/cloud/trace"
+use Google::Cloud::Trace::Middleware
+```
 
-trace = Google::Cloud::Trace.new
+### Adding Custom Trace Spans
+
+The Stackdriver Trace Rack Middleware automatically creates a trace record for
+incoming requests. You can add additional custom trace spans within each 
+request:
+
+```ruby
+Google::Cloud::Trace.in_span "my_task" do |span|
+  # Do stuff...
 
-result_set = trace.list_traces Time.now - 3600, Time.now
-result_set.each do |trace_record|
-  puts "Retrieved trace ID: #{trace_record.trace_id}"
+  Google::Cloud::Trace.in_span "my_subtask" do |subspan|
+    # Do other stuff
+  end
 end
 ```
 
-## Rails and Rack Integration
+### Configuring the library
+
+You can customize the behavior of the Stackdriver Trace library for Ruby. See 
+the [configuration guide](../stackdriver/configuration.md) for a list of 
+possible configuration options.
+
+## Running on Google Cloud Platform
+
+The Stackdriver Trace library for Ruby should work without you manually 
+providing authentication credentials for instances running on Google Cloud 
+Platform, as long as the Stackdriver Trace API access scope is enabled on that 
+instance.
+
+### App Engine
+
+On Google App Engine, the Stackdriver Trace API access scope is enabled by 
+default, and the Stackdriver Trace library for Ruby can be used without 
+providing credentials or a project ID
+
+### Container Engine
+
+On Google Container Engine, you must explicitly add the `trace.append` OAuth 
+scope when creating the cluster:
+
+```sh
+$ gcloud container clusters create example-cluster-name --scopes https://www.googleapis.com/auth/trace.append
+```
+
+### Compute Engine
+
+For Google Compute Engine instances, you need to explicitly enable the 
+`trace.append` Stackdriver Trace API access scope for each instance. When 
+creating a new instance through the Google Cloud Platform Console, you can do 
+this under Identity and API access: Use the Compute Engine default service 
+account and select "Allow full access to all Cloud APIs" under Access scopes.
+
+To use something other than the Compute Engine default service account see the 
+docs for Creating and Enabling Service Accounts for Instances and the Running 
+elsewhere section below. The important thing is that the service account you use
+has the Cloud Trace Agent role.
+
+## Running locally and elsewhere
+
+To run the Stackdriver Trace outside of Google Cloud Platform, you must supply 
+your GCP project ID and appropriate service account credentials directly to the
+Stackdriver Trace. This applies to running the library on your own workstation, 
+on your datacenter's computers, or on the VM instances of another cloud 
+provider. See the [Authentication section](#authentication) for instructions on 
+how to do so.
+
+## Authentication
+
+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 in 
+several ways.
+
+The best way to provide authentication information if you're using Ruby on Rails
+is through the Rails configuration interface:
 
-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"
+# in config/environments/*.rb
+Rails.application.configure do |config|
+  # Shared parameters
+  config.google_cloud.project_id = "your-project-id"
+  config.google_cloud.keyfile = "/path/to/key.json"
+  # Or Stackdriver Trace specific parameters
+  config.google_cloud.trace.project_id = "your-project-id"
+  config.google_cloud.trace.keyfile = "/path/to/key.json"
+end
 ```
 
-Alternatively, check out the [stackdriver](../stackdriver) gem, which includes 
-this library and enables the Railtie by default.
+Other Rack-based applications that are loading the Rack Middleware directly can use
+the configration interface:
+ 
+```ruby
+require "google/cloud/trace"
+Google::Cloud.configure do |config|
+  # Shared parameters
+  config.project_id = "your-project-id"
+  config.keyfile = "/path/to/key.json"
+  # Or Stackdriver Trace specific parameters
+  config.trace.project_id = "your-project-id"
+  config.trace.keyfile = "/path/to/key.json"
+end
+```
 
-For Rack integration and more examples, see the
-[Instrumentation Guide](https://googlecloudplatform.github.io/google-cloud-ruby/#/docs/google-cloud-error_reporting/guides/instrumentation).
+This library also supports the other authentication methods provided by the 
+`google-cloud-ruby` suite. Instructions and configuration options are covered 
+in the [Authentication Guide](https://googlecloudplatform.github.io/google-cloud-ruby/#/docs/google-cloud-trace/guides/authentication).
 
 ## Supported Ruby Versions
 

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

@@ -379,6 +379,7 @@ module Google
         def init_default_config
           configuration.project_id ||= Cloud.configure.project_id ||
                                        Trace::Project.default_project
+          configuration.keyfile ||= Cloud.configure.keyfile
           configuration.capture_stack ||= false
         end
 

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

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

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: google-cloud-trace
 version: !ruby/object:Gem::Version
-  version: 0.27.1
+  version: 0.27.2
 platform: ruby
 authors:
 - Daniel Azuma
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2017-09-08 00:00:00.000000000 Z
+date: 2017-09-20 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: google-cloud-core