google-cloud-trace 0.33.3 → 0.33.4

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 4abf38adb01ec9b9997a1d6a0f6e9d3918147157e8e35f178edad7f75c1ea831
-  data.tar.gz: ac52a148244c3ff89da4915d84865df83872b9f0880e4928503669339f4a9a3b
+  metadata.gz: f65232342ef80608b2f8550bd38b0265d9594f9a0fee1537e7b5e9a47b992374
+  data.tar.gz: b002288b95f33f62d702cd714bbf512b188ddb1aaab672a7a9736fa1f300f2df
 SHA512:
-  metadata.gz: e7b1342855a44dd3282c2e6614d0188759cafa2bcfbe8b16a1a3333b8ca336d077111755f6b8b9af4766f5221cb131fb9f6e583a0f4552b3c76e56bd6ddbf13e
-  data.tar.gz: 79a50a191e5a7e9c21fa850ab538374bdca1e6acf444f5fdaea48410b92449b104820b945ec0f9692e746877c91431b35bc573a29ab1fe030463a729e28583f6
+  metadata.gz: 517a2c8b4f5acc438cd17d863754bad9e0550ee34195a373116f199df735d720ebf771cb5c6b1a6c11f03e44c7236c0f616c8dcf10b44421a42ceeeb9d59cea2
+  data.tar.gz: 826ae7991412c32dd82570c31c081e1dc4c34cbb9d4dedff5f71107cd4f027392d921ea5f58dc5193d7d0f22f9a0ac835c2903937fe4c0b859a1b3c2991a17dd

data/AUTHENTICATION.md

@@ -0,0 +1,178 @@
+# Authentication
+
+In general, the google-cloud-trace library uses [Service
+Account](https://cloud.google.com/iam/docs/creating-managing-service-accounts)
+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
+keyfile](https://cloud.google.com/iam/docs/managing-service-account-keys) for
+the account (or the JSON itself) in environment variables. Additionally, Cloud
+SDK credentials can also be discovered automatically, but this is only
+recommended during development.
+
+## Project and Credential Lookup
+
+The google-cloud-trace library aims to make authentication as simple as
+possible, and provides several mechanisms to configure your system without
+providing **Project ID** and **Service Account Credentials** directly in code.
+
+**Project ID** is discovered in the following order:
+
+1. Specify project ID in method arguments
+2. Specify project ID in configuration
+3. Discover project ID in environment variables
+4. Discover GCE project ID
+
+**Credentials** are discovered in the following order:
+
+1. Specify credentials in method arguments
+2. Specify credentials in configuration
+3. Discover credentials path in environment variables
+4. Discover credentials JSON in environment variables
+5. Discover credentials file in the Cloud SDK's path
+6. Discover GCE credentials
+
+### Google Cloud Platform environments
+
+While running on Google Cloud Platform environments such as Google Compute
+Engine, Google App Engine and Google Kubernetes Engine, no extra work is needed.
+The **Project ID** and **Credentials** and are discovered automatically. Code
+should be written as if already authenticated. Just be sure when you [set up the
+GCE instance][gce-how-to], you add the correct scopes for the APIs you want to
+access. For example:
+
+  * **All APIs**
+    * `https://www.googleapis.com/auth/cloud-platform`
+    * `https://www.googleapis.com/auth/cloud-platform.read-only`
+  * **BigQuery**
+    * `https://www.googleapis.com/auth/bigquery`
+    * `https://www.googleapis.com/auth/bigquery.insertdata`
+  * **Compute Engine**
+    * `https://www.googleapis.com/auth/compute`
+  * **Datastore**
+    * `https://www.googleapis.com/auth/datastore`
+    * `https://www.googleapis.com/auth/userinfo.email`
+  * **DNS**
+    * `https://www.googleapis.com/auth/ndev.clouddns.readwrite`
+  * **Pub/Sub**
+    * `https://www.googleapis.com/auth/pubsub`
+  * **Storage**
+    * `https://www.googleapis.com/auth/devstorage.full_control`
+    * `https://www.googleapis.com/auth/devstorage.read_only`
+    * `https://www.googleapis.com/auth/devstorage.read_write`
+
+### Environment Variables
+
+The **Project ID** and **Credentials JSON** can be placed in environment
+variables instead of declaring them directly in code. Each service has its own
+environment variable, allowing for different service accounts to be used for
+different services. (See the READMEs for the individual service gems for
+details.) The path to the **Credentials JSON** file can be stored in the
+environment variable, or the **Credentials JSON** itself can be stored for
+environments such as Docker containers where writing files is difficult or not
+encouraged.
+
+The environment variables that Trace checks for project ID are:
+
+1. `TRACE_PROJECT`
+2. `GOOGLE_CLOUD_PROJECT`
+
+The environment variables that Trace checks for credentials are configured on {Google::Cloud::Trace::V1::Credentials}:
+
+1. `TRACE_CREDENTIALS` - Path to JSON file, or JSON contents
+2. `TRACE_KEYFILE` - Path to JSON file, or JSON contents
+3. `GOOGLE_CLOUD_CREDENTIALS` - Path to JSON file, or JSON contents
+4. `GOOGLE_CLOUD_KEYFILE` - Path to JSON file, or JSON contents
+5. `GOOGLE_APPLICATION_CREDENTIALS` - Path to JSON file
+
+```ruby
+require "google/cloud/trace"
+
+ENV["TRACE_PROJECT"]     = "my-project-id"
+ENV["TRACE_CREDENTIALS"] = "path/to/keyfile.json"
+
+trace = Google::Cloud::Trace.new
+```
+
+### Configuration
+
+The **Project ID** and **Credentials JSON** can be configured instead of placing them in environment variables or providing them as arguments.
+
+```ruby
+require "google/cloud/trace"
+
+Google::Cloud::Trace.configure do |config|
+  config.project_id  = "my-project-id"
+  config.credentials = "path/to/keyfile.json"
+end
+
+trace = Google::Cloud::Trace.new
+```
+
+### Cloud SDK
+
+This option allows for an easy way to authenticate during development. If
+credentials are not provided in code or in environment variables, then Cloud SDK
+credentials are discovered.
+
+To configure your system for this, simply:
+
+1. [Download and install the Cloud SDK](https://cloud.google.com/sdk)
+2. Authenticate using OAuth 2.0 `$ gcloud auth login`
+3. Write code as if already authenticated.
+
+**NOTE:** This is _not_ recommended for running in production. The Cloud SDK
+*should* only be used during development.
+
+[gce-how-to]: https://cloud.google.com/compute/docs/authentication#using
+[dev-console]: https://console.cloud.google.com/project
+
+[enable-apis]: https://raw.githubusercontent.com/GoogleCloudPlatform/gcloud-common/master/authentication/enable-apis.png
+
+[create-new-service-account]: https://raw.githubusercontent.com/GoogleCloudPlatform/gcloud-common/master/authentication/create-new-service-account.png
+[create-new-service-account-existing-keys]: https://raw.githubusercontent.com/GoogleCloudPlatform/gcloud-common/master/authentication/create-new-service-account-existing-keys.png
+[reuse-service-account]: https://raw.githubusercontent.com/GoogleCloudPlatform/gcloud-common/master/authentication/reuse-service-account.png
+
+## Creating a Service Account
+
+Google Cloud requires a **Project ID** and **Service Account Credentials** to
+connect to the APIs. You will use the **Project ID** and **JSON key file** to
+connect to most services with google-cloud-trace.
+
+If you are not running this client on Google Compute Engine, you need a Google
+Developers service account.
+
+1. Visit the [Google Developers Console][dev-console].
+1. Create a new project or click on an existing project.
+1. Activate the slide-out navigation tray and select **API Manager**. From
+   here, you will enable the APIs that your application requires.
+
+   ![Enable the APIs that your application requires][enable-apis]
+
+   *Note: You may need to enable billing in order to use these services.*
+
+1. Select **Credentials** from the side navigation.
+
+   You should see a screen like one of the following.
+
+   ![Create a new service account][create-new-service-account]
+
+   ![Create a new service account With Existing Keys][create-new-service-account-existing-keys]
+
+   Find the "Add credentials" drop down and select "Service account" to be
+   guided through downloading a new JSON key file.
+
+   If you want to re-use an existing service account, you can easily generate a
+   new key file. Just select the account you wish to re-use, and click "Generate
+   new JSON key":
+
+   ![Re-use an existing service account][reuse-service-account]
+
+   The key file you download will be used by this library to authenticate API
+   requests and should be stored in a secure location.
+
+## Troubleshooting
+
+If you're having trouble authenticating you can ask for help by following the
+{file:TROUBLESHOOTING.md Troubleshooting Guide}.

data/CHANGELOG.md

@@ -0,0 +1,106 @@
+# Release History
+
+### 0.33.4 / 2018-09-12
+
+* Add missing documentation files to package.
+
+### 0.33.3 / 2018-09-10
+
+* Update documentation.
+
+### 0.33.2 / 2018-08-21
+
+* Update documentation.
+
+### 0.33.1 / 2018-07-05
+
+* Fix issue when disabling Stackdriver components with Rails.env.production.
+* Add /healthz to the ignored requests. (diegodurs)
+* Add documentation for enabling gRPC logging.
+
+### 0.33.0 / 2018-05-01
+
+* Fix labels in Trace. (tareksamni)
+
+### 0.31.0 / 2018-02-27
+
+* Use Google Cloud Shared Configuration.
+* Update authentication documentation.
+
+### 0.30.0 / 2017-12-26
+
+* Add `Google::Cloud::Trace::V2::TraceServiceClient` class.
+
+### 0.29.0 / 2017-12-19
+
+* Update google-gax dependency to 1.0.
+
+### 0.28.1 / 2017-11-15
+
+* Fix credentials verification bug in Railtie.
+
+### 0.28.0 / 2017-11-14
+
+* Add `Google::Cloud::Trace::Credentials` class.
+* Rename constructor arguments to `project_id` and `credentials`.
+  (The previous arguments `project` and `keyfile` are still supported.)
+* Document `Google::Auth::Credentials` as `credentials` value.
+* Update generated low level GAPIC code.
+* Updated `google-gax` (`grpc`, `google-protobuf`), `googleauth` dependencies.
+
+### 0.27.2 / 2017-09-20
+
+* Fix the bug where `Google::Cloud::Trace::Middleware` wasn't using the shared `project_id` parameter.
+
+### 0.27.1 / 2017-09-08
+
+* Print captured exception from asynchronous worker thread.
+
+### 0.27.0 / 2017-08-07
+
+* Add instrumentation to collect outbound GRPC requests information.
+
+### 0.26.1 / 2017-07-11
+
+* stackdriver-core 1.2.0 release
+
+### 0.26.0 / 2017-07-11
+
+* Add Faraday Middleware to help collect outbound RPC information.
+* Update `Google::Cloud::Trace::Middleware` and `Google::Cloud::Trace::Railtie` to submit trace spans asynchronously by default.
+* Update GAPIC configuration to exclude `UNAVAILABLE` errors from automatic retry.
+
+### 0.25.0 / 2017-05-25
+
+* Introduce new `Google::Cloud::Trace.configure` instrumentation configuration interface.
+
+### 0.24.1 / 2017-04-21
+
+* If Rails integration fails due to an auth error, the notice is now printed to STDOUT rather than STDERR, which should make it a bit less scary when displayed in Docker output.
+
+### 0.24.0 / 2017-03-31
+
+* Updated documentation
+* Automatic retry on `UNAVAILABLE` errors
+
+### 0.23.2 / 2017-03-03
+
+* Update GRPC header value sent to the Trace API.
+
+### 0.23.1 / 2017-03-01
+
+* Update GRPC header value sent to the Trace API.
+
+### 0.23.0 / 2017-02-21
+
+* Fix GRPC retry bug
+* The client_config data structure has replaced retry_codes/retry_codes_def with retry_codes
+* Update GRPC/Protobuf/GAX dependencies
+
+### 0.22.0 / 2017-01-27
+
+* Change class names in low-level API (GAPIC)
+
+### 0.21.0 / 2016-12-22
+
+* Initial release of google-cloud-trace, providing an API client and application instrumentation.

data/CODE_OF_CONDUCT.md

@@ -0,0 +1,40 @@
+# Contributor Code of Conduct
+
+As contributors and maintainers of this project, and in the interest of
+fostering an open and welcoming community, we pledge to respect all people who
+contribute through reporting issues, posting feature requests, updating
+documentation, submitting pull requests or patches, and other activities.
+
+We are committed to making participation in this project a harassment-free
+experience for everyone, regardless of level of experience, gender, gender
+identity and expression, sexual orientation, disability, personal appearance,
+body size, race, ethnicity, age, religion, or nationality.
+
+Examples of unacceptable behavior by participants include:
+
+* The use of sexualized language or imagery
+* Personal attacks
+* Trolling or insulting/derogatory comments
+* Public or private harassment
+* Publishing other's private information, such as physical or electronic
+  addresses, without explicit permission
+* Other unethical or unprofessional conduct.
+
+Project maintainers have the right and responsibility to remove, edit, or reject
+comments, commits, code, wiki edits, issues, and other contributions that are
+not aligned to this Code of Conduct. By adopting this Code of Conduct, project
+maintainers commit themselves to fairly and consistently applying these
+principles to every aspect of managing this project. Project maintainers who do
+not follow or enforce the Code of Conduct may be permanently removed from the
+project team.
+
+This code of conduct applies both within project spaces and in public spaces
+when an individual is representing the project or its community.
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be
+reported by opening an issue or contacting one or more of the project
+maintainers.
+
+This Code of Conduct is adapted from the [Contributor
+Covenant](http://contributor-covenant.org), version 1.2.0, available at
+[http://contributor-covenant.org/version/1/2/0/](http://contributor-covenant.org/version/1/2/0/)

data/CONTRIBUTING.md

@@ -0,0 +1,188 @@
+# Contributing to Google Cloud Trace
+
+1. **Sign one of the contributor license agreements below.**
+2. Fork the repo, develop and test your code changes.
+3. Send a pull request.
+
+## Contributor License Agreements
+
+Before we can accept your pull requests you'll need to sign a Contributor
+License Agreement (CLA):
+
+- **If you are an individual writing original source code** and **you own the
+  intellectual property**, then you'll need to sign an [individual
+  CLA](https://developers.google.com/open-source/cla/individual).
+- **If you work for a company that wants to allow you to contribute your work**,
+  then you'll need to sign a [corporate
+  CLA](https://developers.google.com/open-source/cla/corporate).
+
+You can sign these electronically (just scroll to the bottom). After that, we'll
+be able to accept your pull requests.
+
+## Setup
+
+In order to use the google-cloud-trace console and run the project's tests,
+there is a small amount of setup:
+
+1. Install Ruby. google-cloud-trace requires Ruby 2.3+. You may choose to
+   manage your Ruby and gem installations with [RVM](https://rvm.io/),
+   [rbenv](https://github.com/rbenv/rbenv), or
+   [chruby](https://github.com/postmodern/chruby).
+
+2. Install [Bundler](http://bundler.io/).
+
+   ```sh
+   $ gem install bundler
+   ```
+
+3. Install the top-level project dependencies.
+
+   ```sh
+   $ bundle install
+   ```
+
+4. Install the Trace dependencies.
+
+   ```sh
+   $ cd google-cloud-trace/
+   $ bundle exec rake bundleupdate
+   ```
+
+## Console
+
+In order to run code interactively, you can automatically load
+google-cloud-trace and its dependencies in IRB. This requires that your
+developer environment has already been configured by following the steps
+described in the {file:AUTHENTICATION.md Authentication Guide}. An IRB console
+can be created with:
+
+```sh
+$ cd google-cloud-trace/
+$ bundle exec rake console
+```
+
+## Trace Tests
+
+Tests are very important part of google-cloud-trace. All contributions
+should include tests that ensure the contributed code behaves as expected.
+
+To run the unit tests, documentation tests, and code style checks together for a
+package:
+
+``` sh
+$ cd google-cloud-trace/
+$ bundle exec rake ci
+```
+
+To run the command above, plus all acceptance tests, use `rake ci:acceptance` or
+its handy alias, `rake ci:a`.
+
+### Trace Unit Tests
+
+
+The project uses the [minitest](https://github.com/seattlerb/minitest) library,
+including [specs](https://github.com/seattlerb/minitest#specs),
+[mocks](https://github.com/seattlerb/minitest#mocks) and
+[minitest-autotest](https://github.com/seattlerb/minitest-autotest).
+
+To run the Trace unit tests:
+
+``` sh
+$ cd google-cloud-trace/
+$ bundle exec rake test
+```
+
+### Trace Documentation Tests
+
+The project tests the code examples in the gem's
+[YARD](https://github.com/lsegal/yard)-based documentation.
+
+The example testing functions in a way that is very similar to unit testing, and
+in fact the library providing it,
+[yard-doctest](https://github.com/p0deje/yard-doctest), is based on the
+project's unit test library, [minitest](https://github.com/seattlerb/minitest).
+
+To run the Trace documentation tests:
+
+``` sh
+$ cd google-cloud-trace/
+$ bundle exec rake doctest
+```
+
+If you add, remove or modify documentation examples when working on a pull
+request, you may need to update the setup for the tests. The stubs and mocks
+required to run the tests are located in `support/doctest_helper.rb`. Please
+note that much of the setup is matched by the title of the
+[`@example`](http://www.rubydoc.info/gems/yard/file/docs/Tags.md#example) tag.
+If you alter an example's title, you may encounter breaking tests.
+
+### Trace Acceptance Tests
+
+The Trace acceptance tests interact with the live service API. Follow the
+instructions in the {file:AUTHENTICATION.md Authentication guide} for enabling
+the Trace API. Occasionally, some API features may not yet be generally
+available, making it difficult for some contributors to successfully run the
+entire acceptance test suite. However, please ensure that you do successfully
+run acceptance tests for any code areas covered by your pull request.
+
+To run the acceptance tests, first create and configure a project in the Google
+Developers Console, as described in the {file:AUTHENTICATION.md Authentication
+guide}. Be sure to download the JSON KEY file. Make note of the PROJECT_ID and
+the KEYFILE location on your system.
+
+Before you can run the Trace acceptance tests, you must first create indexes
+used in the tests.
+
+#### Running the Trace acceptance tests
+
+To run the Trace acceptance tests:
+
+``` sh
+$ cd google-cloud-trace/
+$ bundle exec rake acceptance[\\{my-project-id},\\{/path/to/keyfile.json}]
+```
+
+Or, if you prefer you can store the values in the `GCLOUD_TEST_PROJECT` and
+`GCLOUD_TEST_KEYFILE` environment variables:
+
+``` sh
+$ cd google-cloud-trace/
+$ export GCLOUD_TEST_PROJECT=\\{my-project-id}
+$ export GCLOUD_TEST_KEYFILE=\\{/path/to/keyfile.json}
+$ bundle exec rake acceptance
+```
+
+If you want to use a different project and credentials for acceptance tests, you
+can use the more specific `TRACE_TEST_PROJECT`  and `TRACE_TEST_KEYFILE`
+environment variables:
+
+``` sh
+$ cd google-cloud-trace/
+$ export TRACE_TEST_PROJECT=\\{my-project-id}
+$ export TRACE_TEST_KEYFILE=\\{/path/to/keyfile.json}
+$ bundle exec rake acceptance
+```
+
+## Coding Style
+
+Please follow the established coding style in the library. The style is is
+largely based on [The Ruby Style
+Guide](https://github.com/bbatsov/ruby-style-guide) with a few exceptions based
+on seattle-style:
+
+* Avoid parenthesis when possible, including in method definitions.
+* Always use double quotes strings. ([Option
+  B](https://github.com/bbatsov/ruby-style-guide#strings))
+
+You can check your code against these rules by running Rubocop like so:
+
+```sh
+$ cd google-cloud-trace/
+$ bundle exec rake rubocop
+```
+
+## Code of Conduct
+
+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
+{file:CODE_OF_CONDUCT.md Code of Conduct} for more information.

data/INSTRUMENTATION.md

@@ -0,0 +1,60 @@
+# Stackdriver Trace Instrumentation
+
+Then google-cloud-trace gem provides a Rack Middleware class that integrates
+with Rack-based application frameworks, such as Rails and Sinatra. When
+installed, the middleware collects performance traces of requests and, subject
+to sampling constraints, submits them to the Stackdriver Trace service.
+
+Additionally, the google-cloud-trace gem provides a Railtie class that
+automatically enables the Rack Middleware in Rails applications when used.
+
+## Configuration
+
+The default configuration enables Stackdriver instrumentation features to run on
+Google Cloud Platform. You can easily configure the instrumentation library  if
+you want to run on a non Google Cloud environment or you want to customize  the
+default behavior.
+
+See the [Configuration
+Guide](https://googlecloudplatform.github.io/google-cloud-ruby/docs/stackdriver/latest/file.INSTRUMENTATION_CONFIGURATION)
+for full configuration parameters.
+
+## Rails Integration
+
+To use the Stackdriver Logging Railtie for Ruby on Rails applications, simply
+add this line to `config/application.rb`:
+
+```ruby
+require "google/cloud/trace/rails"
+```
+
+Alternatively, check out the
+[stackdriver](https://googlecloudplatform.github.io/google-cloud-ruby/#/docs/stackdriver)
+gem, which enables this Railtie by default.
+
+## Rack Integration
+
+Other Rack base frameworks can also directly leverage the built-in Middleware.
+
+```ruby
+require "google/cloud/trace"
+use Google::Cloud::Trace::Middleware
+```
+
+## Faraday Middleware
+
+On top of the Rack Middleware, you can also trace outbound Faraday requests by
+using the Faraday Middleware provided with this gem:
+
+```ruby
+require "google/cloud/trace/faraday_middleware"
+
+conn = Faraday.new "https://www.google.com"
+conn.use Google::Cloud::Trace::FaradayMiddleware
+
+result = conn.get
+```
+
+A child span will be create for each outbound Faraday request, and will be
+submitted together with the overall application request trace by the Rack
+Middleware.

data/LOGGING.md

@@ -0,0 +1,32 @@
+# Enabling gRPC Logging
+
+To enable logging for this library, set the logger for the underlying
+[gRPC](https://github.com/grpc/grpc/tree/master/src/ruby) library. The logger
+that you set may be a Ruby stdlib
+[`Logger`](https://ruby-doc.org/stdlib-2.5.0/libdoc/logger/rdoc/Logger.html) as
+shown below, or a
+[`Google::Cloud::Logging::Logger`](https://googlecloudplatform.github.io/google-cloud-ruby/docs/google-cloud-logging/latest/Google/Cloud/Logging/Logger)
+that will write logs to [Stackdriver
+Logging](https://cloud.google.com/logging/). See
+[grpc/logconfig.rb](https://github.com/grpc/grpc/blob/master/src/ruby/lib/grpc/logconfig.rb)
+and the gRPC
+[spec_helper.rb](https://github.com/grpc/grpc/blob/master/src/ruby/spec/spec_helper.rb)
+for additional information.
+
+Configuring a Ruby stdlib logger:
+
+```ruby
+require "logger"
+
+module MyLogger
+  LOGGER = Logger.new $stderr, level: Logger::WARN
+  def logger
+    LOGGER
+  end
+end
+
+# Define a gRPC module-level logger method before grpc/logconfig.rb loads.
+module GRPC
+  extend MyLogger
+end
+```

data/OVERVIEW.md

@@ -0,0 +1,161 @@
+# Stackdriver Trace
+
+The Stackdriver Trace service collects and stores latency data from your
+application and displays it in the Google Cloud Platform Console, giving
+you detailed near-real-time insight into application performance.
+
+The Stackdriver Trace Ruby library, `google-cloud-trace`, provides:
+
+*   Easy-to-use trace instrumentation that collects and collates latency
+    data for your Ruby application. If you just want latency trace data
+    for your application to appear on the Google Cloud Platform Console,
+    see the section on [instrumenting your app](#instrumenting-your-app).
+*   An idiomatic Ruby API for querying, analyzing, and manipulating trace
+    data in your Ruby application. For an introduction to the Trace API,
+    see the section on the [Trace API](#stackdriver-trace-api).
+
+## Instrumenting Your App
+
+This library integrates with Rack-based web frameworks such as Ruby On
+Rails to provide latency trace reports for your application.
+Specifcally, it:
+
+*   Provides a Rack middleware that automatically reports latency traces
+    for http requests handled by your application, and measures the
+    latency of each request as a whole.
+*   Integrates with `ActiveSupport::Notifications` to add important
+    latency-affecting events such as ActiveRecord queries to the trace.
+*   Provides a simple API for your application code to define and
+    measure latency-affecting processes specific to your application.
+
+When this library is installed and configured in your running
+application, you can view your application's latency traces in real time
+by opening the Google Cloud Console in your web browser and navigating
+to the "Trace" section. It also integrates with Google App Engine
+Flexible and Google Container Engine to provide additional information
+for applications hosted in those environments.
+
+Note that not all requests will have traces. By default, the library will
+sample about one trace every ten seconds per Ruby process, to prevent
+heavily used applications from reporting too much data. It will also
+omit certain requests used by Google App Engine for health checking. See
+{Google::Cloud::Trace::TimeSampler} for more details.
+
+### Using instrumentation with Ruby on Rails
+
+To install application instrumentation in your Ruby on Rails app, add
+this gem, `google-cloud-trace`, to your Gemfile and update your bundle.
+Then add the following line to your `config/application.rb` file:
+
+```ruby
+require "google/cloud/trace/rails"
+```
+
+This will install a Railtie that automatically integrates with the
+Rails framework, installing the middleware and the ActiveSupport
+integration for you. Your application traces, including basic request
+tracing, ActiveRecord query measurements, and view render measurements,
+should then start appearing in the Cloud Console.
+
+See the {Google::Cloud::Trace::Railtie} class for more information,
+including how to customize your application traces.
+
+### Using instrumentation with Sinatra
+
+To install application instrumentation in your Sinatra app, add this gem,
+`google-cloud-trace`, to your Gemfile and update your bundle. Then add
+the following lines to your main application Ruby file:
+
+```ruby
+require "google/cloud/trace"
+use Google::Cloud::Trace::Middleware
+```
+
+This will install the trace middleware in your application, providing
+basic request tracing for your application. You may measure additional
+processes such as database queries or calls to external services using
+other classes in this library. See the {Google::Cloud::Trace::Middleware}
+documentation for more information.
+
+### Using instrumentation with other Rack-based frameworks
+
+To install application instrumentation in an app using another Rack-based
+web framework, add this gem, `google-cloud-trace`, to your Gemfile and
+update your bundle. Then add install the trace middleware in your
+middleware stack. In most cases, this means adding these lines to your
+`config.ru` Rack configuration file:
+
+```ruby
+require "google/cloud/trace"
+use Google::Cloud::Trace::Middleware
+```
+
+Some web frameworks have an alternate mechanism for modifying the
+middleware stack. Consult your web framework's documentation for more
+information.
+
+### The Stackdriver diagnostics suite
+
+The trace library is part of the Stackdriver diagnostics suite, which
+also includes error reporting and log analysis. If you include the
+`stackdriver` gem in your Gemfile, this trace library will be included
+automatically. In addition, if you include the `stackdriver` gem in an
+application using Ruby On Rails, the Railtie will be installed
+automatically; you will not need to write any code to view latency
+traces for your appl. See the documentation for the "stackdriver" gem
+for more details.
+
+## Stackdriver Trace API
+
+This library also includes an easy to use Ruby client for the
+Stackdriver Trace API. This API provides calls to report and modify
+application traces, as well as to query and analyze existing traces.
+
+For further information on the trace API, see
+{Google::Cloud::Trace::Project}.
+
+### Querying traces using the API
+
+Using the Stackdriver Trace API, your application can query and analyze
+its own traces and traces of other projects. Here is an example query
+for all traces in the past hour.
+
+```ruby
+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
+```
+
+Each trace is an object of type {Google::Cloud::Trace::TraceRecord},
+which provides methods for analyzing tasks that took place during the
+request trace. See https://cloud.google.com/trace for more information
+on the kind of data you can capture in a trace.
+
+### Reporting traces using the API
+
+Usually it is easiest to use this library's trace instrumentation
+features to collect and record application trace information. However,
+you may also use the trace API to update this data. Here is an example:
+
+```ruby
+require "google/cloud/trace"
+
+trace_client = Google::Cloud::Trace.new
+
+trace = Google::Cloud::Trace.new
+trace.in_span "root_span" do
+  # Do stuff...
+end
+
+trace_client.patch_traces trace
+```
+
+## Additional information
+
+Stackdriver Trace can be configured to be used in Rack applications or to use
+gRPC's logging. To learn more, see the {file:INSTRUMENTATION.md Instrumentation
+Guide} and {file:LOGGING.md Logging guide}.

data/TROUBLESHOOTING.md

@@ -0,0 +1,37 @@
+# Troubleshooting
+
+## Where can I get more help?
+
+### Ask the Community
+
+If you have a question about how to use a Google Cloud client library in your
+project or are stuck in the Developer's console and don't know where to turn,
+it's possible your questions have already been addressed by the community.
+
+First, check out the appropriate tags on StackOverflow:
+  - [`google-cloud-platform+ruby+trace`][so-ruby]
+
+Next, try searching through the issues on GitHub:
+
+  - [`api:trace` issues][gh-search-ruby]
+
+Still nothing?
+
+### Ask the Developers
+
+If you're experiencing a bug with the code, or have an idea for how it can be
+improved, *please* create a new issue on GitHub so we can talk about it.
+
+  - [New issue][gh-ruby]
+
+Or, you can ask questions on the [Google Cloud Platform Slack][slack-ruby]. You
+can use the "ruby" channel for general Ruby questions, or use the
+"google-cloud-ruby" channel if you have questions about this gem in particular.
+
+[so-ruby]: http://stackoverflow.com/questions/tagged/google-cloud-platform+ruby+trace
+
+[gh-search-ruby]: https://github.com/googlecloudplatform/google-cloud-ruby/issues?q=label%3A%22api%3A+trace%22
+
+[gh-ruby]: https://github.com/googlecloudplatform/google-cloud-ruby/issues/new
+
+[slack-ruby]: https://gcp-slack.appspot.com/

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

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

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: google-cloud-trace
 version: !ruby/object:Gem::Version
-  version: 0.33.3
+  version: 0.33.4
 platform: ruby
 authors:
 - Daniel Azuma
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2018-09-10 00:00:00.000000000 Z
+date: 2018-09-12 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: google-cloud-core
@@ -242,8 +242,15 @@ extensions: []
 extra_rdoc_files: []
 files:
 - ".yardopts"
+- AUTHENTICATION.md
+- CHANGELOG.md
+- CODE_OF_CONDUCT.md
+- CONTRIBUTING.md
+- INSTRUMENTATION.md
 - LICENSE
-- README.md
+- LOGGING.md
+- OVERVIEW.md
+- TROUBLESHOOTING.md
 - lib/google-cloud-trace.rb
 - lib/google/cloud/trace.rb
 - lib/google/cloud/trace/async_reporter.rb

data/README.md

@@ -1,250 +0,0 @@
-# google-cloud-trace
-
-[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/latest/file.INSTRUMENTATION)
-- [google-cloud-trace on RubyGems](https://rubygems.org/gems/google-cloud-trace)
-- [Stackdriver Trace documentation](https://cloud.google.com/trace/docs/)
-
-## Quick Start
-
-Install the gem directly:
-
-```sh
-$ gem install google-cloud-trace
-```
-
-Or install through Bundler:
-
-1. Add the `google-cloud-trace` gem to your Gemfile:
-
-```ruby
-gem "google-cloud-trace"
-```
-
-2. Use Bundler to install the gem:
-
-```sh
-$ bundle install
-```
-
-Alternatively, check out the [`stackdriver`](../stackdriver) gem that includes
-the `google-cloud-trace` gem.
-
-## Enable Stackdriver Trace API
-
-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.
-
-## 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
-```
-
-### 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...
-
-  Google::Cloud::Trace.in_span "my_subtask" do |subspan|
-    # Do other stuff
-  end
-end
-```
-
-### 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:
-
-```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 Trace specific parameters
-  config.google_cloud.trace.project_id = "your-project-id"
-  config.google_cloud.trace.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/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
-```
-
-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/latest/file.AUTHENTICATION).
-
-## Enabling Logging
-
-To enable logging for this library, set the logger for the underlying [gRPC](https://github.com/grpc/grpc/tree/master/src/ruby) library. The logger that you set may be a Ruby stdlib [`Logger`](https://ruby-doc.org/stdlib-2.5.0/libdoc/logger/rdoc/Logger.html) as shown below, or a [`Google::Cloud::Logging::Logger`](https://googlecloudplatform.github.io/google-cloud-ruby/docs/google-cloud-logging/latest/Google/Cloud/Logging/Logger) that will write logs to [Stackdriver Logging](https://cloud.google.com/logging/). See [grpc/logconfig.rb](https://github.com/grpc/grpc/blob/master/src/ruby/lib/grpc/logconfig.rb) and the gRPC [spec_helper.rb](https://github.com/grpc/grpc/blob/master/src/ruby/spec/spec_helper.rb) for additional information.
-
-Configuring a Ruby stdlib logger:
-
-```ruby
-require "logger"
-
-module MyLogger
-  LOGGER = Logger.new $stderr, level: Logger::WARN
-  def logger
-    LOGGER
-  end
-end
-
-# Define a gRPC module-level logger method before grpc/logconfig.rb loads.
-module GRPC
-  extend MyLogger
-end
-```
-
-## Supported Ruby Versions
-
-This library is supported on Ruby 2.3+.
-
-Google provides official support for Ruby versions that are actively supported
-by Ruby Core—that is, Ruby versions that are either in normal maintenance or in
-security maintenance, and not end of life. Currently, this means Ruby 2.3 and
-later. Older versions of Ruby _may_ still work, but are unsupported and not
-recommended. See https://www.ruby-lang.org/en/downloads/branches/ for details
-about the Ruby support schedule.
-
-## Versioning
-
-This library follows [Semantic Versioning](http://semver.org/).
-
-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/google-cloud-trace/latest/file.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](https://googlecloudplatform.github.io/google-cloud-ruby/docs/google-cloud-trace/latest/file.CODE_OF_CONDUCT)
-for more information.
-
-## License
-
-This library is licensed under Apache 2.0. Full license text is available in
-[LICENSE](https://googlecloudplatform.github.io/google-cloud-ruby/docs/google-cloud-trace/latest/file.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).