From 4ec4ed8d6aac479ad61e11613408281b1b2a854c Mon Sep 17 00:00:00 2001 From: Heng Xiong Date: Thu, 14 Sep 2017 15:22:00 -0700 Subject: [PATCH] Update stackdriver readmes --- google-cloud-debugger/README.md | 171 ++++++++++++++++++++++-- google-cloud-error_reporting/README.md | 173 ++++++++++++++++++++----- google-cloud-logging/README.md | 119 ++++++++++++----- google-cloud-trace/README.md | 166 ++++++++++++++++++++---- 4 files changed, 524 insertions(+), 105 deletions(-) diff --git a/google-cloud-debugger/README.md b/google-cloud-debugger/README.md index bc77b414b736..52d58d61c911 100644 --- a/google-cloud-debugger/README.md +++ b/google-cloud-debugger/README.md @@ -1,6 +1,6 @@ # google-cloud-debugger -[Stackdriver Debugger](https://cloud.google.com/debugger/) ([docs](https://cloud.google.com/debugger/docs/)) lets you inspect the state of a running application at any code location in real time, without stopping or slowing down the application, and without modifying the code to add logging statements. You can use Stackdriver Debugger with any deployment of your application, including test, development, and production. The Ruby debugger adds minimal request latency, typically less than 50ms, and only when the application state is captured. In most cases, this is not noticeable by users. +[Stackdriver Debugger](https://cloud.google.com/debugger/) lets you inspect the state of a running application at any code location in real time, without stopping or slowing down the application, and without modifying the code to add logging statements. You can use Stackdriver Debugger with any deployment of your application, including test, development, and production. The Ruby debugger adds minimal request latency, typically less than 50ms, and only when the application state is captured. In most cases, this is not noticeable by users. - [google-cloud-debugger documentation](http://googlecloudplatform.github.io/google-cloud-ruby/#/docs/google-cloud-debugger/master/google/cloud/debugger) - [google-cloud-debugger on RubyGems](https://rubygems.org/gems/google-cloud-debugger) @@ -8,25 +8,170 @@ ## Quick Start -Setting up Stackdriver Debugger involves three steps: +Install the gem directly: -1. Add the `google-cloud-debugger` library to your app. -2. Register your app's source code. -3. Deploy your app and set a breakpoint. +```sh +$ gem install google-cloud-debugger +``` -See the -[google-cloud-debugger documentation](http://googlecloudplatform.github.io/google-cloud-ruby/#/docs/google-cloud-debugger/master/google/cloud/debugger) -for a quick tutorial. +Or install through Bundler: -## Authentication +1. Add the `google-cloud-debugger` gem to your Gemfile: + +```ruby +gem "google-cloud-debugger" +``` + +2. Use Bundler to install the gem: + +```sh +$ bundle install +``` + +Alternatively, check out the [`stackdriver`](../stackdriver) gem that includes +the `google-cloud-debugger` gem. + +## Enable Stackdriver Debugger API + +The Stackdriver Debugger agent would need the [Stackdriver Debugger +API](https://console.cloud.google.com/apis/library/clouddebugger.googleapis.com) +to be enabled on your Google Cloud project. Make sure it's enabled if not +already. + +## Enabling the Debugger agent + +If you're using Ruby on Rails and the `stackdriver` gem, they automatically +loads the library into your application when it starts. + +Otherwise, you can load the Railtie that comes with the library into your Ruby +on Rails application by explicitly require it in the application startup path: + +```ruby +# In config/application.rb +require "google/cloud/debugger/rails" +``` + +Other Rack-based frameworks, such as Sinatra, can use the Rack Middleware +provided by the library: + +```ruby +require "google/cloud/debugger" +use Google::Cloud::Debugger::Middleware +``` + +Non-rack-based applications can start the agent explicitly at the entry point of +your application: + +```ruby +require "google/cloud/debugger" +Google::Cloud::Debugger.new.start +``` + +### Configuring the agent -This library uses Service Account credentials to connect to Google Cloud services. When running on Compute Engine 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. +You can customize the behavior of the Stackdriver Debugger agent. See the +[agent configuration](../stackdriver/docs/configuration.md) for a list of +possible configuration options. -Instructions and configuration options are covered in the [Authentication Guide](https://googlecloudplatform.github.io/google-cloud-ruby/#/docs/google-cloud-debugger/guides/authentication). +## Running on Google Cloud Platform -## Usage +The Stackdriver Debugger agent should work without you manually providing +authentication credentials for instances running on Google Cloud Platform, as +long as the Stackdriver Debugger API access scope is enabled on that instance. + +### App Engine + +On Google App Engine, the Stackdriver Debugger API access scope is enabled by +default, and the Stackdriver Debugger agent can be used without providing +credentials or a project ID. + +### Container Engine + +On Google Container Engine, you must explicitly add the `cloud_debugger` OAuth +scope when creating the cluster: + +```sh +$ gcloud container clusters create example-cluster-name --scopes https://www.googleapis.com/auth/cloud_debugger +``` + +You can also do this through the Google Cloud Platform Console. Select +**Enabled** in the Cloud Platform section of **Create a container cluster**. + +### Compute Engine + +To use Stackdriver Debugger, Compute Engine VM instances should have one of the +following access scopes. These are only relevant when you use Compute Engine's +default service account: + +* `https://www.googleapis.com/auth/cloud-platform` +* `https://www.googleapis.com/auth/cloud_debugger` + +The `cloud-platform` access scope can be supplied when creating a new instance +through the Google Cloud Platform Console. Select **Allow full access to all +Cloud APIs** in the **Identity and API access** section of **Create an +instance**. + +The `cloud_debugger` access scope must be supplied manually using the SDK's +`gcloud compute instances create` command or the `gcloud compute instances +set-service-account` command. + +## Running locally and elsewhere + +To run the Stackdriver Debugger agent outside of Google Cloud Platform, you must +supply your GCP project ID and appropriate service account credentials directly +to the Stackdriver Debugger agent. This applies to running the agent 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 -This library provides a Stackdriver Debugger Agent that's able to work with Ruby applications. It also integrates with Ruby on Rails and other popular Rack-based frameworks. See the [Instrumentation Guide](https://googlecloudplatform.github.io/google-cloud-ruby/#/docs/google-cloud-debugger/guides/instrumentation) for more details. +This library uses Service Account credentials to connect to Google Cloud +services. When running on Compute Engine 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: + +```ruby +# 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 Debugger agent specific parameters + config.google_cloud.debugger.project_id = "your-project-id" + config.google_cloud.debugger.keyfile = "/path/to/key.json" +end +``` + +Other Rack-based applications that are loading the Rack Middleware directly can use +the configration interface: + +```ruby +require "google/cloud/debugger" +Google::Cloud.configure do |config| + # Shared parameters + config.project_id = "your-project-id" + config.keyfile = "/path/to/key.json" + # Or Stackdriver Debugger agent specific parameters + config.debugger.project_id = "your-project-id" + config.debugger.keyfile = "/path/to/key.json" +end +``` + +Or provide the parameters to the Stackdriver Debugger agent when it starts: + +```ruby +require "google/cloud/debugger" +Google::Cloud::Debugger.new(project_id: "your-project-id", + keyfile: "/path/to/key.json").start +``` + +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-debugger/guides/authentication). ## Supported Ruby Versions diff --git a/google-cloud-error_reporting/README.md b/google-cloud-error_reporting/README.md index 1b7d2a73abb6..5702ff12007a 100644 --- a/google-cloud-error_reporting/README.md +++ b/google-cloud-error_reporting/README.md @@ -13,63 +13,166 @@ new errors. - [google-cloud-error_reporting on RubyGems](https://rubygems.org/gems/google-cloud-error_reporting) - [Stackdriver ErrorReporting documentation](https://cloud.google.com/error-reporting/docs/) -google-cloud-error_reporting provides an instrumentation API that makes it easy -to report exceptions to the Stackdriver Error Reporting service. It also -contains a full API client library for the -[Stackdriver Error Reporting API](https://developers.google.com/apis-explorer/#p/clouderrorreporting/v1beta1/) -(v1beta1). - ## Quick Start + +Install the gem directly: + ```sh $ gem install google-cloud-error_reporting ``` -## 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-error_reporting` gem to your Gemfile: + +```ruby +gem "google-cloud-error_reporting" +``` + +2. Use Bundler to install the gem: + +```sh +$ bundle install +``` + +Alternatively, check out the [`stackdriver`](../stackdriver) gem that includes +the `google-cloud-error_reporting` gem. + +## Enable Stackdriver Error Reporting API -Instructions and configuration options are covered in the -[Authentication Guide](https://googlecloudplatform.github.io/google-cloud-ruby/#/docs/google-cloud-error_reporting/guides/authentication). +The Stackdriver Error Reporting library would need the [Stackdriver Error +Reporting API](https://console.cloud.google.com/apis/library/clouderrorreporting.googleapis.com) +to be enabled on your Google Cloud project. Make sure it's enabled if not +already. + +## Reporting errors in Rack-based frameworks + +The Stackdriver Error Reporting library for Ruby makes it easy to integrate +Stackdriver Error Reporting into popular Rack-based Ruby web frameworks such as +Ruby on Rails and Sinatra. When the library integration is enabled, it +automatically reports exceptions captured from the application's Rack stack. + +If you're using Ruby on Rails and the `stackdriver` gem, they automatically +loads the library into your application when it starts. + +Otherwise, you can load the Railtie that comes with the library into your Ruby +on Rails application by explicitly require it in the application startup path: + +```ruby +# In config/application.rb +require "google/cloud/error_reporting/rails" +``` + +Other Rack-based frameworks, such as Sinatra, can use the Rack Middleware +provided by the library: -## Instrumentation Example ```ruby require "google/cloud/error_reporting" - -# Configure Stackdriver ErrorReporting instrumentation -Google::Cloud::ErrorReporting.configure do |config| - config.project_id = "my-project" - config.keyfile = "/path/to/keyfile.json" -end - -# Insert a Rack Middleware to report unhanded exceptions use Google::Cloud::ErrorReporting::Middleware - -# Or explicitly submit exceptions +``` + +## Reporting errors manually + +Manually reporting an error is as easy as calling the report method: + +```ruby +require "google/cloud/error_reporting" begin - fail "Boom!" + fail "boom!" rescue => exception Google::Cloud::ErrorReporting.report exception end ``` -## Rails and Rack Integration +## Configuring the library + +You can customize the behavior of the Stackdriver Error Reporting library for +Ruby. See the [configuration guide](../stackdriver/configuration.md) for a list +of possible configuration options. + +## Running on Google Cloud Platform + +The Stackdriver Error Reporting library for Ruby should work without you +manually providing authentication credentials for instances running on Google +Cloud Platform, as long as the Stackdriver Error Reporting API access scope is +enabled on that instance. + +### App Engine + +On Google App Engine, the Stackdriver Error Reporting API access scope is +enabled by default, and the Stackdriver Error Reporting library for Ruby can +be used without providing credentials or a project ID. + +### Container Engine + +On Google Container Engine, you must explicitly add the `cloud-platform` OAuth +scope when creating the cluster: + +```sh +$ gcloud container clusters create example-cluster-name --scopes https://www.googleapis.com/auth/cloud-platform +``` + +You may also do this through the Google Cloud Platform Console. Select +**Enabled** in the **Cloud Platform** section of **Create a container cluster**. + +### Compute Engine + +For Google Compute Engine instances, you must explicitly enable the +`cloud-platform` access scope for each instance. When you create 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. + +## Running locally and elsewhere + +To run the Stackdriver Error Reporting outside of Google Cloud Platform, you +must supply your GCP project ID and appropriate service account credentials +directly to the Stackdriver Error Reporting. 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/error_reporting/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 Error Reporting specific parameters + config.google_cloud.error_reporting.project_id = "your-project-id" + config.google_cloud.error_reporting.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/error_reporting" +Google::Cloud.configure do |config| + # Shared parameters + config.project_id = "your-project-id" + config.keyfile = "/path/to/key.json" + # Or Stackdriver Error Reporting specific parameters + config.error_reporting.project_id = "your-project-id" + config.error_reporting.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-debugger/guides/authentication). ## Supported Ruby Versions diff --git a/google-cloud-logging/README.md b/google-cloud-logging/README.md index 28e81914ff3e..61016da343b8 100644 --- a/google-cloud-logging/README.md +++ b/google-cloud-logging/README.md @@ -8,17 +8,32 @@ ## Quick Start +Install the gem directly: + ```sh $ gem install google-cloud-logging ``` -## Authentication +Or install through Bundler: + +1. Add the `google-cloud-logging` gem to your Gemfile: + +```ruby +gem "google-cloud-logging" +``` + +2. Use Bundler to install the gem: -This library uses Service Account credentials to connect to Google Cloud services. When running on Compute Engine 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. +```sh +$ bundle install +``` -Instructions and configuration options are covered in the [Authentication Guide](https://googlecloudplatform.github.io/google-cloud-ruby/#/docs/google-cloud-logging/guides/authentication). +Alternatively, check out the [`stackdriver`](../stackdriver) gem that includes +the `google-cloud-logging` gem. -## Example +## Logging using client library + +You can directly read or write log entries through the client library: ```ruby require "google/cloud/logging" @@ -44,49 +59,83 @@ entry.resource.labels[:version_id] = "20150925t173233" logging.write_entries entry ``` -## Rails Integration +## Logging in Rack-based frameworks + +The `google-cloud-logging` library provides framework integration for popular +Rack-based frameworks, such as Ruby on Rails and Sinatra, which sets the default +Rack logger to an instance of Stackdriver Logging logger. -This library also provides a built in Railtie for Ruby on Rails integration. When enabled, it sets an instance of Google::Cloud::Logging::Logger as the default Rails logger. Then all consequent log entries will be submitted to the Stackdriver Logging service. +If you're using Ruby on Rails and the `stackdriver` gem, bundler automatically +loads the library into your application when it starts. + +Other Rack-based applications can use the Rack Middleware to replace the Rack +logger with the Stackdriver Logging logger: -To do this, simply add this line to config/application.rb: ```ruby -require "google/cloud/logging/rails" +require "google/cloud/logging" +use Google::Cloud::Logging::Middleware ``` -Then the library can be configured through this set of Rails parameters in config/environments/*.rb: + +Once the Rack logger is set, some Rack-based frameworks, such as Ruby on Rails +and Sinatra, automatically initialize the default application logger to use the +Rack logger: + ```ruby -# Sharing authentication parameters -config.google_cloud.project_id = "gcp-project-id" -config.google_cloud.keyfile = "/path/to/gcp/secret.json" -# Or more specificly for Logging -config.google_cloud.logging.project_id = "gcp-project-id" -config.google_cloud.logging.keyfile = "/path/to/gcp/sercret.json" - -# Explicitly enable or disable Logging -config.google_cloud.use_logging = true - -# Set Stackdriver Logging log name -config.google_cloud.logging.log_name = "my-app-log" - -# Override default monitored resource if needed. E.g. used on AWS -config.google_cloud.logging.monitored_resource.type = "aws_ec2_instance" -config.google_cloud.logging.monitored_resource.labels.instance_id = "ec2-instance-id" -config.google_cloud.logging.monitored_resource.labels.aws_account = "AWS account number" +logger.info "Hello World" +logger.warn "Hola Mundo" +logger.error "Bonjour Monde" ``` -Alternatively, check out [stackdriver](../stackdriver) gem, which includes this Railtie by default. -## Rack Integration +For other frameworks, consult the documentations on how to utilize the Rack +logger. + +### Configuring the framework integration -Other Rack base framework can also directly leverage the built-in Middleware. +You can customize the behavior of the Stackdriver Logging framework integration +for Ruby. See the [configuration guide](../stackdriver/configuration.md) for a +list of possible configuration options. + +## Authentication + +This library uses Service Account credentials to connect to Google Cloud +services. When running on Compute Engine the credentials will be discovered +automatically. When running on other environments the Service Account +credentials can be specified by providing in several ways. + +If you're using Ruby on Rails and the library's Rails integration feature, you +can provide the authentication parameters through the Rails configuration +interface: + ```ruby -require "google/cloud/logging" +# Add this to 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" + # Stackdriver Logging specific parameters + config.google_cloud.logging.project_id = "your-project-id" + config.google_cloud.logging.keyfile = "/path/to/key.json" +end +``` +Other Rack-based applications that are loading the Rack Middleware directly can +use the configration interface: -logging = Google::Cloud::Logging.new -resource = Google::Cloud::Logging::Middleware.build_monitored_resource -logger = logging.logger "my-log-name", - resource -use Google::Cloud::Logging::Middleware, logger: logger +```ruby +require "google/cloud/logging" +Google::Cloud.configure do |config| + # Shared parameters + config.project_id = "your-project-id" + config.keyfile = "/path/to/key.json" + # Or Stackdriver logging specific parameters + config.logging.project_id = "your-project-id" + config.logging.keyfile = "/path/to/key.json" +end ``` +See the [Authentication +Guide](https://googlecloudplatform.github.io/google-cloud-ruby/#/docs/google-cloud-logging/guides/authentication). +for more ways to authenticate the client library. + ## Supported Ruby Versions This library is supported on Ruby 2.0+. diff --git a/google-cloud-trace/README.md b/google-cloud-trace/README.md index 5e6f03a373ac..e782159b4b35 100644 --- a/google-cloud-trace/README.md +++ b/google-cloud-trace/README.md @@ -14,48 +14,170 @@ 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. -Instructions and configuration options are covered in the -[Authentication Guide](https://googlecloudplatform.github.io/google-cloud-ruby/#/docs/google-cloud-trace/guides/authentication). +## Enable Stackdriver Trace API -## Example +The Stackdriver Trace library would need 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. + +## 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. + +If you're using Ruby on Rails and the `stackdriver` gem, they automatically +loads the library into your application when it starts. + +Otherwise, you can load the Railtie that comes with the library into your Ruby +on Rails application by explicitly require it in the application startup path: + +```ruby +# In config/application.rb +require "google/cloud/trace/rails" +``` + +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 +``` + +### Add Custom Trace Span -trace = Google::Cloud::Trace.new +The Stackdriver Trace Rack Middleware automatically creates a trace record for +incoming requests. You can add additional custom trace spans within each +request: -result_set = trace.list_traces Time.now - 3600, Time.now -result_set.each do |trace_record| - puts "Retrieved trace ID: #{trace_record.trace_id}" +```ruby +Google::Cloud::Trace.in_span "my_task" do |span| + # Do stuff... + + 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