google-cloud-logging 1.5.3 → 1.5.4

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c8b7a06296878a5094bc4de7d45d87b988297de5cec70e212c17b55639f07485
-  data.tar.gz: '090cc3fe558e01f326240b6c7ba23cc9607e480454f39be71ec0da9844cefa0e'
+  metadata.gz: c186c4f38de2474a1a806259d215e3613ccea28d09011b3ad7b9c08421aae52f
+  data.tar.gz: d17ddc92fd9783853bb4efb7edba4be0aaa6bea9f45bb8d04147a17f6f8c191e
 SHA512:
-  metadata.gz: fda5da167d780b2ad5dd119037291730e935927b57da558266168db82f587665608fc0e1df14b983dd8f87ac0d217b790a810ab037edaba2497b7558bdd19305
-  data.tar.gz: bb7324f057ca44e027fcaf532360b66e5ec25a377ff32ae20f88accae7f0b2097117f61c626d966dac18e67998b9fe95ef8a55f8fe817a38fa248e842c17fa03
+  metadata.gz: 5e8c71b129fa26d8f3061fee8e7f66dca3942467cf844f650d47322f586d18c9a381251f7afd05767f22b87b81538182a8ae6cc82aa4003e98e0e7feee7d8ca6
+  data.tar.gz: e13b593778894c9df313fb513ef9c16496961243342ac36523a12d98192fc65a82c5bfa740e5ec597d304805cf829eb39452f386d1900d0a30ee28e813aa60a8

data/AUTHENTICATION.md

@@ -0,0 +1,179 @@
+# Authentication
+
+In general, the google-cloud-logging 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-logging 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 Logging checks for project ID are:
+
+1. `LOGGING_PROJECT`
+2. `GOOGLE_CLOUD_PROJECT`
+
+The environment variables that Logging checks for credentials are configured on
+{Google::Cloud::Logging::V2::Credentials}:
+
+1. `LOGGING_CREDENTIALS` - Path to JSON file, or JSON contents
+2. `LOGGING_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/logging"
+
+ENV["LOGGING_PROJECT"]     = "my-project-id"
+ENV["LOGGING_CREDENTIALS"] = "path/to/keyfile.json"
+
+logging = Google::Cloud::Logging.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/logging"
+
+Google::Cloud::Logging.configure do |config|
+  config.project_id  = "my-project-id"
+  config.credentials = "path/to/keyfile.json"
+end
+
+logging = Google::Cloud::Logging.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-logging.
+
+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,153 @@
+# Release History
+
+### 1.5.4 / 2018-09-12
+
+* Add missing documentation files to package.
+
+### 1.5.3 / 2018-09-10
+
+* Update documentation.
+
+### 1.5.2 / 2018-08-21
+
+* Update documentation.
+
+### 1.5.1 / 2018-07-05
+
+* Fix bug in List classes by propagating arguments needed for pagination calls.
+* Fix issue when disabling Stackdriver components with Rails.env.production.
+* Reduce string memory usage.
+* Add documentation for enabling gRPC logging.
+
+### 1.5.0 / 2018-02-27
+
+* Use Google Cloud Shared Configuration.
+* Deprecated Logging Sink attributes.
+
+### 1.4.0 / 2017-12-19
+
+* Update google-gax dependency to 1.0.
+
+### 1.3.2 / 2017-11-20
+
+* Refresh GAPIC layer (low-level API) based on updates to Protobuf types.
+
+### 1.3.1 / 2017-11-15
+
+* Fix credentials verification bug in Railtie.
+
+### 1.3.0 / 2017-11-14
+
+* Add `Google::Cloud::Logging::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.
+* Add `partial_success` optional argument to `Project#write_entries`.
+* Deprecate `HttpRequest#method`, use `HttpRequest#request_method` instead.
+* Update generated low level GAPIC code.
+* Updated `google-gax` (`grpc`, `google-protobuf`), `googleauth` dependencies.
+
+### 1.2.3 / 2017-09-27
+
+* Updated protobuf classes.
+* Updated README.
+
+### 1.2.2 / 2017-09-08
+
+* Add `labels` configuration option to `Google::Cloud::Logging::Middleware` for Rails and other Rack-based framework integrations.
+
+### 1.2.1 / 2017-07-11
+
+* stackdriver-core 1.2.0 release
+
+### 1.2.0 / 2017-07-11
+
+* Update `labels` parameter in `Google::Cloud::Logging::Logger#initialize` to default to empty hash.
+* Update `Google::Cloud::Logging::Logger` to support the following `ActiveSupport::Logger` methods: `:local_level`, `:local_level=`, `:silence`, `:silencer`, and `:unknown?`.
+* Update GAPIC configuration to exclude `UNAVAILABLE` errors from automatic retry.
+* Update gem spec homepage links.
+
+### 1.1.0 / 2017-05-25
+
+* Introduce new `Google::Cloud::Logging.configure` instrumentation configuration interface.
+* Google::Cloud::Logger now sends extra trace context information in log entries.
+
+### 1.0.1 / 2017-04-21
+
+* Middleware constructor can be called without an explicit logger. This should make integration in non-Rails applications simpler.
+* 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.
+
+### 1.0.0 / 2017-03-31
+
+* Release 1.0
+* Added `#trace` and `#source_location` to Entry
+* Added listing of logs for the project
+* Updated documentation
+* Automatic retry on `UNAVAILABLE` errors
+
+### 0.24.2 / 2017-03-03
+
+* No public API changes.
+* Update GRPC header value sent to the Logging API.
+
+### 0.24.1 / 2017-03-01
+
+* No public API changes.
+* Update GRPC header value sent to the Logging API.
+* Low level API adds new Protobuf types and GAPIC methods.
+
+### 0.24.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.23.2 / 2016-12-27
+
+* `Google::Cloud::Logging::Logger` depended on standard logger but didn't require it. Fixed.
+
+### 0.23.1 / 2016-12-22
+
+* Use the `stackdriver-core` gem to obtain Trace ID, for compatibility with the `google-cloud-trace` gem.
+* `Google::Cloud::Logging::Logger` now understands all remaining standard Logger methods.
+* Clean up `AsyncWriter` threads on VM exit, to prevent gRPC from crashing if it's still in the middle of a call.
+* Support setting log name by path, and direct App Engine health checks to a separate log by default.
+* Minor improvements to warning messages.
+
+### 0.23.0 / 2016-12-8
+
+* Add `resources` method argument to `Project#entries`
+* Deprecate `projects` method argument from `Project#entries`
+* Add `start_at`, `end_at`, and `writer_identity` attributes to `Sink`
+* Add `start_at`, `end_at`, and `unique_writer_identity` parameters to `Project#create_sink`
+* Add `unique_writer_identity` parameter to `Sink#save`
+* Many documentation improvements
+* Add documentation for Low Level API
+
+### 0.21.2 / 2016-11-15
+
+* Fix issue with uninitialized VERSION (remi)
+
+### 0.21.1 / 2016-11-4
+
+* Upgraded Google::Cloud::Logging::Railtie to use AsyncWriter
+* Added Rails configuration for custom monitored resource
+
+### 0.21.0 / 2016-10-20
+
+* New service constructor Google::Cloud::Logging.new
+* New constructor argument client_config
+* Logger is now asynchronous
+* AsyncWriter added
+* Rails and Rack integration added
+
+### 0.20.1 / 2016-09-02
+
+* Fix an issue with the GRPC client and forked sub-processes
+
+### 0.20.0 / 2016-08-26
+
+This gem contains the Stackdriver Logging service implementation for the `google-cloud` gem. The `google-cloud` gem replaces the old `gcloud` gem. Legacy code can continue to use the `gcloud` gem.
+
+* Namespace is now `Google::Cloud`
+* The `google-cloud` gem is now an umbrella package for individual gems

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 Logging
+
+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-logging console and run the project's tests,
+there is a small amount of setup:
+
+1. Install Ruby. google-cloud-logging 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 Logging dependencies.
+
+   ```sh
+   $ cd google-cloud-logging/
+   $ bundle exec rake bundleupdate
+   ```
+
+## Console
+
+In order to run code interactively, you can automatically load
+google-cloud-logging 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-logging/
+$ bundle exec rake console
+```
+
+## Logging Tests
+
+Tests are very important part of google-cloud-logging. 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-logging/
+$ bundle exec rake ci
+```
+
+To run the command above, plus all acceptance tests, use `rake ci:acceptance` or
+its handy alias, `rake ci:a`.
+
+### Logging 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 Logging unit tests:
+
+``` sh
+$ cd google-cloud-logging/
+$ bundle exec rake test
+```
+
+### Logging 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 Logging documentation tests:
+
+``` sh
+$ cd google-cloud-logging/
+$ 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.
+
+### Logging Acceptance Tests
+
+The Logging acceptance tests interact with the live service API. Follow the
+instructions in the {file:AUTHENTICATION.md Authentication guide} for enabling
+the Logging 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 Logging acceptance tests, you must first create indexes
+used in the tests.
+
+#### Running the Logging acceptance tests
+
+To run the Logging acceptance tests:
+
+``` sh
+$ cd google-cloud-logging/
+$ 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-logging/
+$ 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 `LOGGING_TEST_PROJECT`  and `LOGGING_TEST_KEYFILE`
+environment variables:
+
+``` sh
+$ cd google-cloud-logging/
+$ export LOGGING_TEST_PROJECT=\\{my-project-id}
+$ export LOGGING_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-logging/
+$ 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,71 @@
+# Stackdriver Logging Instrumentation
+
+Then google-cloud-logging gem provides a Rack Middleware class that can easily 
+integrate with Rack based application frameworks, such as Rails and Sinatra. 
+When enabled, it sets an instance of Google::Cloud::Logging::Logger as the 
+default Rack or Rails logger. Then all consequent log entries will be submitted 
+to the Stackdriver Logging service. 
+
+On top of that, the google-cloud-logging also implements 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/guides/instrumentation_configuration)
+for full configuration parameters.
+
+## Using instrumentation with Ruby on Rails
+
+To install application instrumentation in your Ruby on Rails app, add this
+gem, `google-cloud-logging`, to your Gemfile and update your bundle. Then
+add the following line to your `config/application.rb` file:
+```ruby
+require "google/cloud/logging/rails"
+```
+This will load a Railtie that automatically integrates with the Rails
+framework by injecting a Rack middleware.
+
+## Using instrumentation with Sinatra
+
+To install application instrumentation in your Sinatra app, add this gem,
+`google-cloud-logging`, to your Gemfile and update your bundle. Then add
+the following lines to your main application Ruby file:
+
+```ruby
+require "google/cloud/logging"
+use Google::Cloud::Logging::Middleware
+```
+
+This will install the logging middleware in your application.
+
+### 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-logging`, to your Gemfile and
+update your bundle. Then add install the logging middleware in your
+middleware stack. In most cases, this means adding these lines to your
+`config.ru` Rack configuration file:
+
+```ruby
+require "google/cloud/logging"
+use Google::Cloud::Logging::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 google-cloud-logging library is part of the Stackdriver diagnostics suite, 
+which also includes error reporting, tracing analysis, and real-time debugger. 
+If you include the `stackdriver` gem in your Gemfile, this logging library will
+be included automatically. In addition, if you include the `stackdriver`
+gem in an application using Ruby On Rails, the Railties will be installed
+automatically. See the documentation for the "stackdriver" gem
+for more details.

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,321 @@
+# Stackdriver Logging
+
+The Stackdriver Logging service collects and stores logs from applications and
+services on the Google Cloud Platform, giving you fine-grained, programmatic
+control over your projects' logs. You can use the Stackdriver Logging API to:
+
+* [Read and filter log entries](#listing-log-entries)
+* [Export your log entries](#exporting-log-entries) to Cloud Storage,
+  BigQuery, or Cloud Pub/Sub
+* [Create logs-based metrics](#creating-logs-based-metrics) for use in
+  Cloud Monitoring
+* [Write log entries](#writing-log-entries)
+
+For general information about Stackdriver Logging, read [Stackdriver Logging
+Documentation](https://cloud.google.com/logging/docs/).
+
+The goal of google-cloud is to provide an API that is comfortable to Rubyists.
+Your authentication credentials are detected automatically in Google Cloud
+Platform environments such as Google Compute Engine, Google App Engine and
+Google Kubernetes Engine. In other environments you can configure authentication
+easily, either directly in your code or via environment variables. Read more
+about the options for connecting in the {file:AUTHENTICATION.md Authentication
+Guide}.
+
+## Listing log entries
+
+Stackdriver Logging gathers log entries from many services, including Google App
+Engine and Google Compute Engine. (See the [List of Log
+Types](https://cloud.google.com/logging/docs/view/logs_index).) In addition, you
+can write your own log entries to the service.
+
+{Google::Cloud::Logging::Project#entries Project#entries} returns the
+{Google::Cloud::Logging::Entry Entry} records belonging to your project:
+
+```ruby
+require "google/cloud/logging"
+
+logging = Google::Cloud::Logging.new
+entries = logging.entries
+entries.each do |e|
+  puts "[#{e.timestamp}] #{e.log_name} #{e.payload.inspect}"
+end
+```
+
+You can narrow the results to a single log using an [advanced logs
+filter](https://cloud.google.com/logging/docs/view/advanced_filters). A log is a
+named collection of entries. Logs can be produced by Google Cloud Platform
+services, by third-party services, or by your applications. For example, the log
+`compute.googleapis.com/activity_log` is produced by Google Compute Engine. Logs
+are simply referenced by name in google-cloud. There is no `Log` type in
+google-cloud or `Log` resource in the Stackdriver Logging API.
+
+```ruby
+require "google/cloud/logging"
+
+logging = Google::Cloud::Logging.new
+entries = logging.entries filter: "logName:syslog"
+entries.each do |e|
+  puts "[#{e.timestamp}] #{e.payload.inspect}"
+end
+```
+
+You can also order the log entries by `timestamp`.
+
+```ruby
+require "google/cloud/logging"
+
+logging = Google::Cloud::Logging.new
+entries = logging.entries order: "timestamp desc"
+entries.each do |e|
+  puts "[#{e.timestamp}] #{e.log_name}"
+end
+```
+
+## Exporting log entries
+
+Stackdriver Logging lets you export log entries to destinations including Google
+Cloud Storage buckets (for long term log storage), Google BigQuery datasets (for
+log analysis), and Google Pub/Sub (for streaming to other applications).
+
+### Creating sinks
+
+A {Google::Cloud::Logging::Sink Sink} is an object that lets you to specify a
+set of log entries to export.
+
+In addition to the name of the sink and the export destination,
+{Google::Cloud::Logging::Project#create_sink Project#create_sink} accepts an
+[advanced logs
+filter](https://cloud.google.com/logging/docs/view/advanced_filters) to narrow
+the collection.
+
+Before creating the sink, ensure that you have granted `cloud-logs@google.com`
+permission to write logs to the destination. See [Exporting Logs
+(V2)](https://cloud.google.com/logging/docs/export/configure_export_v2).
+
+```ruby
+require "google/cloud/storage"
+require "google/cloud/logging"
+
+storage = Google::Cloud::Storage.new
+
+bucket = storage.create_bucket "my-logs-bucket"
+
+# Grant owner permission to Stackdriver Logging service
+email = "cloud-logs@google.com"
+bucket.acl.add_owner "group-#{email}"
+
+logging = Google::Cloud::Logging.new
+
+sink = logging.create_sink "my-sink",
+                           "storage.googleapis.com/#{bucket.id}"
+```
+
+When you create a sink, only new log entries are exported. Stackdriver Logging
+does not send previously-ingested log entries to the sink's destination.
+
+### Listing sinks
+
+You can also list the sinks belonging to your project with
+{Google::Cloud::Logging::Project#sinks Project#sinks}.
+
+```ruby
+require "google/cloud/logging"
+
+logging = Google::Cloud::Logging.new
+sinks = logging.sinks
+sinks.each do |s|
+  puts "#{s.name}: #{s.filter} -> #{s.destination}"
+end
+```
+
+## Creating logs-based metrics
+
+You can use log entries in your project as the basis for [Google Cloud
+Monitoring](https://cloud.google.com/monitoring/docs) metrics. These metrics can
+then be used to produce Cloud Monitoring reports and alerts.
+
+### Creating metrics
+
+A metric is a measured value that can be used to assess a system. Use
+{Google::Cloud::Logging::Project#create_metric Project#create_metric} to
+configure a  {Google::Cloud::Logging::Metric Metric} based on a collection of
+log entries matching an [advanced logs
+filter](https://cloud.google.com/logging/docs/view/advanced_filters).
+
+```ruby
+require "google/cloud/logging"
+
+logging = Google::Cloud::Logging.new
+metric = logging.create_metric "errors", "severity>=ERROR"
+```
+
+### Listing metrics
+
+You can also list the metrics belonging to your project with
+{Google::Cloud::Logging::Project#metrics Project#metrics}.
+
+```ruby
+require "google/cloud/logging"
+
+logging = Google::Cloud::Logging.new
+metrics = logging.metrics
+metrics.each do |m|
+  puts "#{m.name}: #{m.filter}"
+end
+```
+
+## Writing log entries
+
+An {Google::Cloud::Logging::Entry} is composed of metadata and a payload. The
+payload is traditionally a message string, but in Stackdriver Logging it can
+also be a JSON or protocol buffer object. A single log can have entries with
+different payload types. In addition to the payload, your argument(s) to
+{Google::Cloud::Logging::Project#write_entries Project#write_entries} must also
+contain a log name and a resource.
+
+```ruby
+require "google/cloud/logging"
+
+logging = Google::Cloud::Logging.new
+
+entry = logging.entry
+entry.payload = "Job started."
+entry.log_name = "my_app_log"
+entry.resource.type = "gae_app"
+entry.resource.labels[:module_id] = "1"
+entry.resource.labels[:version_id] = "20150925t173233"
+
+logging.write_entries entry
+```
+
+To write a JSON payload to the log, simply pass a hash argument:
+
+```ruby
+require "google/cloud/logging"
+
+logging = Google::Cloud::Logging.new
+
+entry = logging.entry
+entry.payload = { "stats" => { "a" => 8, "b" => 12.5} }
+entry.log_name = "my_app_log"
+entry.resource.type = "gae_app"
+entry.resource.labels[:module_id] = "1"
+entry.resource.labels[:version_id] = "20150925t173233"
+
+logging.write_entries entry
+```
+
+If you write a collection of log entries, you can provide the log name,
+resource, and/or labels hash to be used for all of the entries, and omit these
+values from the individual entries.
+
+```ruby
+require "google/cloud/logging"
+
+logging = Google::Cloud::Logging.new
+
+entry1 = logging.entry
+entry1.payload = "Job started."
+entry2 = logging.entry
+entry2.payload = "Job completed."
+labels = { job_size: "large", job_code: "red" }
+
+resource = logging.resource "gae_app",
+                            "module_id" => "1",
+                            "version_id" => "20150925t173233"
+
+logging.write_entries [entry1, entry2],
+                      log_name: "my_app_log",
+                      resource: resource,
+                      labels: labels
+```
+
+Normally, writing log entries is done synchronously; the call to
+{Google::Cloud::Logging::Project#write_entries Project#write_entries} will block
+until it has either completed transmitting the data or encountered an error. To
+"fire and forget" without blocking, use {Google::Cloud::Logging::AsyncWriter
+AsyncWriter}; it spins up a background thread that writes log entries in
+batches. Calls to {Google::Cloud::Logging::AsyncWriter#write_entries
+AsyncWriter#write_entries} simply add entries to its work queue and return
+immediately.
+
+```ruby
+require "google/cloud/logging"
+
+logging = Google::Cloud::Logging.new
+async = logging.async_writer
+
+entry1 = logging.entry
+entry1.payload = "Job started."
+entry2 = logging.entry
+entry2.payload = "Job completed."
+labels = { job_size: "large", job_code: "red" }
+
+resource = logging.resource "gae_app",
+                            "module_id" => "1",
+                            "version_id" => "20150925t173233"
+
+async.write_entries [entry1, entry2],
+                    log_name: "my_app_log",
+                    resource: resource,
+                    labels: labels,
+                    partial_success: true
+```
+
+### Creating a Ruby Logger implementation
+
+If your environment requires a logger instance that is API-compatible with
+Ruby's standard library [Logger](http://ruby-doc.org/stdlib/libdoc/logger/rdoc),
+you can use {Google::Cloud::Logging::Project#logger Project#logger} to create
+one.
+
+```ruby
+require "google/cloud/logging"
+
+logging = Google::Cloud::Logging.new
+
+resource = logging.resource "gae_app",
+                            module_id: "1",
+                            version_id: "20150925t173233"
+
+logger = logging.logger "my_app_log", resource, env: :production
+logger.info "Job started."
+```
+
+By default, the logger instance writes log entries asynchronously in a
+background thread using an {Google::Cloud::Logging::AsyncWriter AsyncWriter}. If
+you want to customize or disable asynchronous writing, you may call the Logger
+constructor directly.
+
+```ruby
+require "google/cloud/logging"
+
+logging = Google::Cloud::Logging.new
+
+resource = logging.resource "gae_app",
+                            module_id: "1",
+                            version_id: "20150925t173233"
+
+logger = Google::Cloud::Logging::Logger.new logging,
+                                            "my_app_log",
+                                            resource,
+                                            {env: :production}
+logger.info "Log entry written synchronously."
+```
+
+## Configuring timeout
+
+You can configure the request `timeout` value in seconds.
+
+```ruby
+require "google/cloud/logging"
+
+logging = Google::Cloud::Logging.new timeout: 120
+```
+
+## Additional information
+
+Stackdriver Logging 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+logging`][so-ruby]
+
+Next, try searching through the issues on GitHub:
+
+  - [`api:logging` 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+logging
+
+[gh-search-ruby]: https://github.com/googlecloudplatform/google-cloud-ruby/issues?q=label%3A%22api%3A+logging%22
+
+[gh-ruby]: https://github.com/googlecloudplatform/google-cloud-ruby/issues/new
+
+[slack-ruby]: https://gcp-slack.appspot.com/

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

@@ -16,7 +16,7 @@
 module Google
   module Cloud
     module Logging
-      VERSION = "1.5.3".freeze
+      VERSION = "1.5.4".freeze
     end
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: google-cloud-logging
 version: !ruby/object:Gem::Version
-  version: 1.5.3
+  version: 1.5.4
 platform: ruby
 authors:
 - Mike Moore
@@ -9,7 +9,7 @@ authors:
 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
@@ -244,8 +244,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-logging.rb
 - lib/google/cloud/logging.rb
 - lib/google/cloud/logging/async_writer.rb

data/README.md

@@ -1,220 +0,0 @@
-# google-cloud-logging
-
-[Stackdriver Logging](https://cloud.google.com/logging/) ([docs](https://cloud.google.com/logging/docs/)) allows you to store, search, analyze, monitor, and alert on log data and events from Google Cloud Platform and Amazon Web Services (AWS). It supports ingestion of any custom log data from any source. Stackdriver Logging is a fully-managed service that performs at scale and can ingest application and system log data from thousands of VMs. Even better, you can analyze all that log data in real-time.
-
-- [google-cloud-logging API documentation](http://googlecloudplatform.github.io/google-cloud-ruby/docs/google-cloud-logging/latest)
-- [google-cloud-logging on RubyGems](https://rubygems.org/gems/google-cloud-logging)
-- [Stackdriver Logging documentation](https://cloud.google.com/logging/docs/)
-
-## Quick Start
-
-Install the gem directly:
-
-```sh
-$ gem install google-cloud-logging
-```
-
-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:
-
-```sh
-$ bundle install
-```
-
-Alternatively, check out the [`stackdriver`](../stackdriver) gem that includes
-the `google-cloud-logging` gem.
-
-## Logging using client library
-
-You can directly read or write log entries through the client library:
-
-```ruby
-require "google/cloud/logging"
-
-logging = Google::Cloud::Logging.new
-
-# List all log entries
-logging.entries.each do |e|
-  puts "[#{e.timestamp}] #{e.log_name} #{e.payload.inspect}"
-end
-
-# List only entries from a single log
-entries = logging.entries filter: "log:syslog"
-
-# Write a log entry
-entry = logging.entry
-entry.payload = "Job started."
-entry.log_name = "my_app_log"
-entry.resource.type = "gae_app"
-entry.resource.labels[:module_id] = "1"
-entry.resource.labels[:version_id] = "20150925t173233"
-
-logging.write_entries entry
-```
-
-## Using Stackdriver Logging in 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 the Stackdriver Logging logger.
-
-### 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/logging/rails"
-```
-
-If you're using the `stackdriver` gem, it automatically loads the Railtie into
-your application when it starts.
-
-You'll be able to use Stackdriver logger through the standard Rails logger:
-
-```ruby
-Rails.logger.info "Hello World"
-# Or just...
-logger.warn "Hola Mundo"
-```
-
-### With other Rack-based frameworks
-
-Other Rack-based applications can use the Rack Middleware to replace the Rack
-logger with the Stackdriver Logging logger:
-
-```ruby
-require "google/cloud/logging"
-use Google::Cloud::Logging::Middleware
-```
-
-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
-logger.info "Hello World"
-logger.warn "Hola Mundo"
-logger.error "Bonjour Monde"
-```
-
-For other frameworks, consult the documentations on how to utilize the Rack
-logger.
-
-### Configuring the framework integration
-
-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
-# 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:
-
-```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/latest/file.AUTHENTICATION).
-for more ways to authenticate the client library.
-
-## 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/).
-
-## 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-logging/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-logging/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-logging/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).