gcloud 0.6.3 → 0.7.0

checksums.yaml

@@ -1,15 +1,15 @@
 ---
 !binary "U0hBMQ==":
   metadata.gz: !binary |-
-    NWQ1NzQxZjYwNGUwZjA0NzIzNmU5ZGRlZGFiODk2NWFlNzc4ZTFhZA==
+    NTQ3OWYzM2ZkNDc1ZTFlZGU1YzU2OWY1YTVhNDRjNDE2M2ZkZDQyZg==
   data.tar.gz: !binary |-
-    OGExNzlhZmU3OWMyNmJkZjg3NzRiOGRkZTg1MTdiNDUwMjc4ZGVjMw==
+    MTg1YjE2ODY0ZjEwMjc1MGQ3NzBkOTc4MTZiNTU5ZDllN2U0MWM0Mw==
 SHA512:
   metadata.gz: !binary |-
-    NjE3MzQwMDNhMmM0M2FjZDQxMWY2MTZlMWY2MzdlZDU0Y2Q4NzUwZDM3YzI4
-    YTdjOTdjOTZjZTM2NGU2MGViYTQwMjUzZTVkYTQ2YzA5MDMzMTE4Y2ZhMDEx
-    ZmRhYTdlZWRhZGQ3YTI4MDBiNzIwOWMwNjRlNzg0MjA1MGU2YzE=
+    MDhkMTc0NmMxYjJiMTUwN2I2NjMwMTEyNTE4ODkxODViNDNiN2I1YWJhZWRk
+    YzdlMWIxN2E5YzU1OWMzYmRmYjQ1MDNjNzhkN2Y2MTM2ODRkMGNmY2ZlYmE0
+    NWRhY2JhZjM0YzQ2YmNkMzAwMDFiODI1N2JhNGNjYzBmZjQ2YTk=
   data.tar.gz: !binary |-
-    N2I5MGUzOThiN2Y3OGM3MGIwM2JjY2I3ZGIxMGYzMGUxNzA0NzlhYWUxZDY3
-    OGM0OGZmNmFjNWYwMDA4MDg0NGMyMTE5MTI4NTI4YjQ4ZDVmYzQzMTc3MmM3
-    NGRiYWU1ODI1Yjc5OTJkMjRkZmUxNGE3MDY5YmExOTA0YzIzZDM=
+    MmJjMzRiMWRkN2E3ZTk3NzIwMTkyY2YwYjc3YTdlNTQzZWRkMGE3NjAwZTVm
+    YmY4N2E5MmIxNmZmNGQ3YjM0ZTlhYTYyZmY5OGMyZGFjNDNhM2U3MDRkYmEx
+    ZTE0MzlkYWQ2NTU1ZGM0N2VlODM1NTFhMDMwNGY3M2VjMjY0M2E=

data/AUTHENTICATION.md

@@ -4,15 +4,19 @@
 
 Gcloud aims to make authentication as simple as possible. Google Cloud requires a **Project ID** and **Service Account Credentials** to connect to the APIs. To create a service account:
 
-1. Visit the [Google Developers Console](https://console.developers.google.com/project).
-2. Create a new project or click on an existing project.
-3. Navigate to **APIs & auth** > **APIs section** and turn on the following APIs (you may need to enable billing in order to use these services):
-  * Google Cloud Datastore API
-  * Google Cloud Storage
-  * Google Cloud Storage JSON API
-4. Navigate to **APIs & auth** > **Credentials** and then:
-  * If you want to use a new service account, click on **Create new Client ID** and select **Service account**. After the account is created, you will be prompted to download the JSON key file that the library uses to authorize your requests.
-  * If you want to generate a new key for an existing service account, click on **Generate new JSON key** and download the JSON key file.
+1. Visit the [Google Developers Console Projects page](https://console.developers.google.com/project).
+1. Create a new project or click on an existing project that you wish to use.
+1. In the project's **Dashboard**, under **Explore other services**, click **Enable APIs and get credentials like keys**.
+1. Turn on one or more of the following APIs by clicking on each API name and then clicking **Enable API** (click **More** if you do not see an API; also, you may need to enable billing in order to use some services):
+  * BigQuery API
+  * Cloud Datastore API
+  * Cloud DNS API
+  * Cloud Pub/Sub API
+  * Cloud Storage Service
+  * Cloud Storage JSON API
+1. In the left nav, click **Credentials**.
+1. Under **New credentials**, select **Service account key**.
+1. If you want to create a new service account, under **Service account**, select **New service account**. Otherwise, select an existing service account. Submit the form to download a JSON type key. Save the downloaded JSON key file to authorize your requests.
 
 You will use the **Project ID** and **JSON file** to connect to services with gcloud.
 

data/CHANGELOG.md

@@ -1,11 +1,16 @@
 # Release History
 
-### 0.6.3 / 2016-05-25
+### 0.7.0 / 2016-03-31
 
 #### Changes
 
-* Pub/Sub
-  * Fix issue with base64 encoding and the REST API (arparker)
+* Add support for Logging service
+* gRPC
+  * Add dependency on gRPC gem
+  * Pub/Sub transport layer now uses gRPC
+  * New Logging transport layer uses gRPC
+  * Future releases will migrate more services to gRPC
+
 
 ### 0.6.2 / 2016-03-02
 

data/OVERVIEW.md

@@ -6,13 +6,13 @@ The `gcloud` library is installable through rubygems:
 $ gem install gcloud
 ```
 
-Gcloud aims to make authentication as simple as possible. Google Cloud requires a **Project ID** and **Service Account Credentials** to connect to the APIs. You can learn more about various options for connection on the [Authentication Guide](AUTHENTICATION.md).
+Gcloud aims to make authentication as simple as possible. Google Cloud requires a **Project ID** and **Service Account Credentials** to connect to the APIs. You can learn more about various options for connection on the [Authentication Guide](https://googlecloudplatform.github.io/gcloud-ruby/#/docs/guides/authentication).
 
 # BigQuery
 
 [Google Cloud BigQuery](https://cloud.google.com/bigquery/) ([docs](https://cloud.google.com/bigquery/docs)) enables super-fast, SQL-like queries against append-only tables, using the processing power of Google's infrastructure. Simply move your data into BigQuery and let it handle the hard work. You can control access to both the project and your data based on your business needs, such as giving others the ability to view or query your data.
 
-See the [gcloud-ruby BigQuery API documentation](rdoc-ref:Gcloud::Bigquery) to learn how to connect to Cloud BigQuery using this library.
+See the {Gcloud::Bigquery gcloud-ruby BigQuery API documentation} to learn how to connect to Cloud BigQuery using this library.
 
 ```ruby
 require "gcloud"
@@ -44,7 +44,7 @@ end
 
 Follow the [activation instructions](https://cloud.google.com/datastore/docs/activate) to use the Google Cloud Datastore API with your project.
 
-See the [gcloud-ruby Datastore API documentation](rdoc-ref:Gcloud::Datastore) to learn how to interact with the Cloud Datastore using this library.
+See the {Gcloud::Bigquery gcloud-ruby Datastore API documentation} to learn how to interact with the Cloud Datastore using this library.
 
 ```ruby
 require "gcloud"
@@ -71,7 +71,7 @@ completed_tasks = dataset.run query
 
 [Google Cloud DNS](https://cloud.google.com/dns/) ([docs](https://cloud.google.com/dns/docs)) is a high-performance, resilient, global DNS service that provides a cost-effective way to make your applications and services available to your users. This programmable, authoritative DNS service can be used to easily publish and manage DNS records using the same infrastructure relied upon by Google. To learn more, read [What is Google Cloud DNS?](https://cloud.google.com/dns/what-is-cloud-dns).
 
-See the [gcloud-ruby DNS API documentation](rdoc-ref:Gcloud::Dns) to learn how to connect to Cloud DNS using this library.
+See the {Gcloud::Dns gcloud-ruby DNS API documentation} to learn how to connect to Cloud DNS using this library.
 
 ```ruby
 require "gcloud"
@@ -95,11 +95,49 @@ end
 
 ```
 
+# Logging
+
+[Google Cloud Logging](https://cloud.google.com/logging/) collects and stores logs from applications and services on the Google Cloud Platform, giving you fine-grained, programmatic control over your projects' logs. With this API you can do the following:
+
+* Read and filter log entries
+* Export your log entries to Cloud Storage,
+  BigQuery, or Cloud Pub/Sub
+* Create logs-based metrics for use in Cloud
+  Monitoring
+* Write log entries
+
+See the {Gcloud::Logging gcloud-ruby Logging API documentation} to learn how to connect to Cloud Loging using this library.
+
+```ruby
+require "gcloud"
+
+gcloud = Gcloud.new
+logging = gcloud.logging
+
+# 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
+```
+
 # Pub/Sub
 
 [Google Cloud Pub/Sub](https://cloud.google.com/pubsub/) ([docs](https://cloud.google.com/pubsub/reference/rest/)) is designed to provide reliable, many-to-many, asynchronous messaging between applications. Publisher applications can send messages to a “topic” and other applications can subscribe to that topic to receive the messages. By decoupling senders and receivers, Google Cloud Pub/Sub allows developers to communicate between independently written applications.
 
-See the [gcloud-ruby Pub/Sub API documentation](rdoc-ref:Gcloud::Pubsub) to learn how to connect to Cloud Pub/Sub using this library.
+See the {Gcloud::Pubsub gcloud-ruby Pub/Sub API documentation} to learn how to connect to Cloud Pub/Sub using this library.
 
 ```ruby
 require "gcloud"
@@ -130,7 +168,7 @@ msgs = sub.pull
 * Delete projects
 * Undelete, or recover, projects that you don't want to delete
 
-See the [gcloud-ruby Resource Manager API documentation](rdoc-ref:Gcloud::ResourceManager) to learn how to connect to Cloud Resource Manager using this library.
+See the {Gcloud::ResourceManager gcloud-ruby Resource Manager API documentation} to learn how to connect to Cloud Resource Manager using this library.
 
 ```ruby
 require "gcloud"
@@ -157,7 +195,7 @@ projects = resource_manager.projects filter: "labels.env:production"
 
 [Google Cloud Search](https://cloud.google.com/search/) ([docs](https://cloud.google.com/search/reference/rest/index)) allows an application to quickly perform full-text and geo-spatial searches without having to spin up instances and without the hassle of managing and maintaining a search service.
 
-See the [gcloud-ruby Search API documentation](rdoc-ref:Gcloud::Search) to learn how to connect to Cloud Search using this library.
+See the {Gcloud::Search gcloud-ruby Search API documentation} to learn how to connect to Cloud Search using this library.
 
 ```ruby
 require "gcloud"
@@ -175,7 +213,7 @@ results = index.search "cotton T-shirt",
 
 [Google Cloud Storage](https://cloud.google.com/storage/) ([docs](https://cloud.google.com/storage/docs/json_api/)) allows you to store data on Google infrastructure with very high reliability, performance and availability, and can be used to distribute large data objects to users via direct download.
 
-See the [gcloud-ruby Storage API documentation](rdoc-ref:Gcloud::Storage) to learn how to connect to Cloud Storage using this library.
+See the {Gcloud::Storage gcloud-ruby Storage API documentation} to learn how to connect to Cloud Storage using this library.
 
 ```ruby
 require "gcloud"

data/lib/gcloud.rb

@@ -1,4 +1,3 @@
-#--
 # Copyright 2015 Google Inc. All rights reserved.
 #
 # Licensed under the Apache License, Version 2.0 (the "License");
@@ -13,10 +12,11 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
+
 require "gcloud/version"
 
 ##
-# = Google Cloud
+# # Google Cloud
 #
 # Gcloud is the official library for interacting with the Google Cloud Platform.
 # Google Cloud Platform is a set of modular cloud-based services that allow
@@ -27,28 +27,24 @@ require "gcloud/version"
 # information, or if you are running on Google Compute Engine this configuration
 # is taken care of for you.
 #
-# You can learn more about various options for connection on the
-# {Authentication Guide}[AUTHENTICATION.md].
+# You can learn more about various options for connection on the [Authentication
+# Guide](https://googlecloudplatform.github.io/gcloud-ruby/#/docs/guides/authentication).
 #
 module Gcloud
   ##
   # Creates a new object for connecting to Google Cloud.
   #
-  # === Parameters
-  #
-  # +project+::
-  #   Project identifier for the Pub/Sub service you are connecting to.
-  #   (+String+)
-  # +keyfile+::
-  #   Keyfile downloaded from Google Cloud. If file path the file must be
-  #   readable. (+String+ or +Hash+)
-  #
-  # === Returns
+  # For more information on connecting to Google Cloud see the [Authentication
+  # Guide](https://googlecloudplatform.github.io/gcloud-ruby/#/docs/guides/authentication).
   #
-  # Gcloud
+  # @param [String] project Project identifier for the Pub/Sub service you are
+  #   connecting to.
+  # @param [String, Hash] keyfile Keyfile downloaded from Google Cloud. If file
+  #   path the file must be readable.
   #
-  # === Example
+  # @return [Gcloud]
   #
+  # @example
   #   require "gcloud"
   #
   #   gcloud  = Gcloud.new
@@ -70,25 +66,22 @@ module Gcloud
   # Creates a new object for connecting to the Datastore service.
   # Each call creates a new connection.
   #
-  # === Parameters
+  # For more information on connecting to Google Cloud see the [Authentication
+  # Guide](https://googlecloudplatform.github.io/gcloud-ruby/#/docs/guides/authentication).
   #
-  # +scope+::
-  #   The OAuth 2.0 scopes controlling the set of resources and operations that
-  #   the connection can access. See {Using OAuth 2.0 to Access Google
-  #   APIs}[https://developers.google.com/identity/protocols/OAuth2]. (+String+
-  #   or +Array+)
+  # @param [String, Array<String>] scope The OAuth 2.0 scopes controlling the
+  #   set of resources and operations that the connection can access. See [Using
+  #   OAuth 2.0 to Access Google
+  #   APIs](https://developers.google.com/identity/protocols/OAuth2).
   #
   #   The default scopes are:
   #
-  #   * +https://www.googleapis.com/auth/datastore+
-  #   * +https://www.googleapis.com/auth/userinfo.email+
+  #   * `https://www.googleapis.com/auth/datastore`
+  #   * `https://www.googleapis.com/auth/userinfo.email`
   #
-  # === Returns
-  #
-  # Gcloud::Datastore::Dataset
-  #
-  # === Examples
+  # @return [Gcloud::Datastore::Dataset]
   #
+  # @example
   #   require "gcloud"
   #
   #   gcloud  = Gcloud.new
@@ -101,9 +94,7 @@ module Gcloud
   #
   #   dataset.save entity
   #
-  # You shouldn't need to override the default scope, but it is possible to do
-  # so with the +scope+ option:
-  #
+  # @example You shouldn't need to override the default scope, but you can:
   #   require "gcloud"
   #
   #   gcloud  = Gcloud.new
@@ -119,24 +110,24 @@ module Gcloud
   # Creates a new object for connecting to the Storage service.
   # Each call creates a new connection.
   #
-  # === Parameters
+  # For more information on connecting to Google Cloud see the [Authentication
+  # Guide](https://googlecloudplatform.github.io/gcloud-ruby/#/docs/guides/authentication).
   #
-  # +scope+::
-  #   The OAuth 2.0 scopes controlling the set of resources and operations that
-  #   the connection can access. See {Using OAuth 2.0 to Access Google
-  #   APIs}[https://developers.google.com/identity/protocols/OAuth2]. (+String+
-  #   or +Array+)
+  # @see https://cloud.google.com/storage/docs/authentication#oauth Storage
+  #   OAuth 2.0 Authentication
   #
-  #   The default scope is:
-  #
-  #   * +https://www.googleapis.com/auth/devstorage.full_control+
+  # @param [String, Array<String>] scope The OAuth 2.0 scopes controlling the
+  #   set of resources and operations that the connection can access. See [Using
+  #   OAuth 2.0 to Access Google
+  #   APIs](https://developers.google.com/identity/protocols/OAuth2).
   #
-  # === Returns
+  #   The default scope is:
   #
-  # Gcloud::Storage::Project
+  #   * `https://www.googleapis.com/auth/devstorage.full_control`
   #
-  # === Examples
+  # @return [Gcloud::Storage::Project]
   #
+  # @example
   #   require "gcloud"
   #
   #   gcloud  = Gcloud.new
@@ -144,10 +135,7 @@ module Gcloud
   #   bucket = storage.bucket "my-bucket"
   #   file = bucket.file "path/to/my-file.ext"
   #
-  # The default scope can be overridden with the +scope+ option. For more
-  # information see {Storage OAuth 2.0
-  # Authentication}[https://cloud.google.com/storage/docs/authentication#oauth].
-  #
+  # @example The default scope can be overridden with the `scope` option:
   #   require "gcloud"
   #
   #   gcloud  = Gcloud.new
@@ -163,24 +151,21 @@ module Gcloud
   # Creates a new object for connecting to the Pub/Sub service.
   # Each call creates a new connection.
   #
-  # === Parameters
+  # For more information on connecting to Google Cloud see the [Authentication
+  # Guide](https://googlecloudplatform.github.io/gcloud-ruby/#/docs/guides/authentication).
   #
-  # +scope+::
-  #   The OAuth 2.0 scopes controlling the set of resources and operations that
-  #   the connection can access. See {Using OAuth 2.0 to Access Google
-  #   APIs}[https://developers.google.com/identity/protocols/OAuth2]. (+String+
-  #   or +Array+)
+  # @param [String, Array<String>] scope The OAuth 2.0 scopes controlling the
+  #   set of resources and operations that the connection can access. See [Using
+  #   OAuth 2.0 to Access Google
+  #   APIs](https://developers.google.com/identity/protocols/OAuth2).
   #
   #   The default scope is:
   #
-  #   * +https://www.googleapis.com/auth/pubsub+
-  #
-  # === Returns
+  #   * `https://www.googleapis.com/auth/pubsub`
   #
-  # Gcloud::Pubsub::Project
-  #
-  # === Examples
+  # @return [Gcloud::Pubsub::Project]
   #
+  # @example
   #   require "gcloud"
   #
   #   gcloud = Gcloud.new
@@ -188,8 +173,7 @@ module Gcloud
   #   topic = pubsub.topic "my-topic"
   #   topic.publish "task completed"
   #
-  # The default scope can be overridden with the +scope+ option:
-  #
+  # @example The default scope can be overridden with the `scope` option:
   #   require "gcloud"
   #
   #   gcloud  = Gcloud.new
@@ -205,24 +189,21 @@ module Gcloud
   # Creates a new object for connecting to the BigQuery service.
   # Each call creates a new connection.
   #
-  # === Parameters
+  # For more information on connecting to Google Cloud see the [Authentication
+  # Guide](https://googlecloudplatform.github.io/gcloud-ruby/#/docs/guides/authentication).
   #
-  # +scope+::
-  #   The OAuth 2.0 scopes controlling the set of resources and operations that
-  #   the connection can access. See {Using OAuth 2.0 to Access Google
-  #   APIs}[https://developers.google.com/identity/protocols/OAuth2]. (+String+
-  #   or +Array+)
+  # @param [String, Array<String>] scope The OAuth 2.0 scopes controlling the
+  #   set of resources and operations that the connection can access. See [Using
+  #   OAuth 2.0 to Access Google
+  #   APIs](https://developers.google.com/identity/protocols/OAuth2).
   #
   #   The default scope is:
   #
-  #   * +https://www.googleapis.com/auth/bigquery+
-  #
-  # === Returns
+  #   * `https://www.googleapis.com/auth/bigquery`
   #
-  # Gcloud::Bigquery::Project
-  #
-  # === Examples
+  # @return [Gcloud::Bigquery::Project]
   #
+  # @example
   #   require "gcloud"
   #
   #   gcloud = Gcloud.new
@@ -233,8 +214,7 @@ module Gcloud
   #     puts row
   #   end
   #
-  # The default scope can be overridden with the +scope+ option:
-  #
+  # @example The default scope can be overridden with the `scope` option:
   #   require "gcloud"
   #
   #   gcloud  = Gcloud.new
@@ -250,24 +230,21 @@ module Gcloud
   # Creates a new object for connecting to the DNS service.
   # Each call creates a new connection.
   #
-  # === Parameters
+  # For more information on connecting to Google Cloud see the [Authentication
+  # Guide](https://googlecloudplatform.github.io/gcloud-ruby/#/docs/guides/authentication).
   #
-  # +scope+::
-  #   The OAuth 2.0 scopes controlling the set of resources and operations that
-  #   the connection can access. See {Using OAuth 2.0 to Access Google
-  #   APIs}[https://developers.google.com/identity/protocols/OAuth2]. (+String+
-  #   or +Array+)
+  # @param [String, Array<String>] scope The OAuth 2.0 scopes controlling the
+  #   set of resources and operations that the connection can access. See [Using
+  #   OAuth 2.0 to Access Google
+  #   APIs](https://developers.google.com/identity/protocols/OAuth2).
   #
   #   The default scope is:
   #
-  #   * +https://www.googleapis.com/auth/ndev.clouddns.readwrite+
-  #
-  # === Returns
+  #   * `https://www.googleapis.com/auth/ndev.clouddns.readwrite`
   #
-  # Gcloud::Dns::Project
-  #
-  # === Examples
+  # @return [Gcloud::Dns::Project]
   #
+  # @example
   #   require "gcloud"
   #
   #   gcloud = Gcloud.new
@@ -277,8 +254,7 @@ module Gcloud
   #     puts record.name
   #   end
   #
-  # The default scope can be overridden with the +scope+ option:
-  #
+  # @example The default scope can be overridden with the `scope` option:
   #   require "gcloud"
   #
   #   gcloud  = Gcloud.new
@@ -298,24 +274,21 @@ module Gcloud
   # Creates a new object for connecting to the Resource Manager service.
   # Each call creates a new connection.
   #
-  # === Parameters
+  # For more information on connecting to Google Cloud see the [Authentication
+  # Guide](https://googlecloudplatform.github.io/gcloud-ruby/#/docs/guides/authentication).
   #
-  # +scope+::
-  #   The OAuth 2.0 scopes controlling the set of resources and operations that
-  #   the connection can access. See {Using OAuth 2.0 to Access Google
-  #   APIs}[https://developers.google.com/identity/protocols/OAuth2]. (+String+
-  #   or +Array+)
+  # @param [String, Array<String>] scope The OAuth 2.0 scopes controlling the
+  #   set of resources and operations that the connection can access. See [Using
+  #   OAuth 2.0 to Access Google
+  #   APIs](https://developers.google.com/identity/protocols/OAuth2).
   #
   #   The default scope is:
   #
-  #   * +https://www.googleapis.com/auth/cloud-platform+
-  #
-  # === Returns
+  #   * `https://www.googleapis.com/auth/cloud-platform`
   #
-  # Gcloud::ResourceManager::Manager
-  #
-  # === Examples
+  # @return [Gcloud::ResourceManager::Manager]
   #
+  # @example
   #   require "gcloud"
   #
   #   gcloud = Gcloud.new
@@ -324,8 +297,7 @@ module Gcloud
   #     puts projects.project_id
   #   end
   #
-  # The default scope can be overridden with the +scope+ option:
-  #
+  # @example The default scope can be overridden with the `scope` option:
   #   require "gcloud"
   #
   #   gcloud  = Gcloud.new
@@ -343,29 +315,63 @@ module Gcloud
   # Creates a new object for connecting to the Search service.
   # Each call creates a new connection.
   #
-  # === Parameters
+  # For more information on connecting to Google Cloud see the [Authentication
+  # Guide](https://googlecloudplatform.github.io/gcloud-ruby/#/docs/guides/authentication).
   #
-  # +scope+::
-  #   The OAuth 2.0 scopes controlling the set of resources and operations that
-  #   the connection can access. See {Using OAuth 2.0 to Access Google
-  #   APIs}[https://developers.google.com/identity/protocols/OAuth2]. (+String+
-  #   or +Array+)
+  # @param [String, Array<String>] scope The OAuth 2.0 scopes controlling the
+  #   set of resources and operations that the connection can access. See [Using
+  #   OAuth 2.0 to Access Google
+  #   APIs](https://developers.google.com/identity/protocols/OAuth2).
   #
   #   The default scopes are:
   #
-  #   * +https://www.googleapis.com/auth/cloudsearch+
-  #   * +https://www.googleapis.com/auth/userinfo.email+
+  #   * `https://www.googleapis.com/auth/cloudsearch`
+  #   * `https://www.googleapis.com/auth/userinfo.email`
   #
-  # === Returns
-  #
-  # Gcloud::Search::Project
-  #
-  # === Examples
+  # @return [Gcloud::Search::Project]
   #
+  # @example
   #   require "gcloud"
   #
   def search scope: nil
     require "gcloud/search"
     Gcloud.search @project, @keyfile, scope: scope
   end
+
+  ##
+  # Creates a new object for connecting to the Logging service.
+  # Each call creates a new connection.
+  #
+  # For more information on connecting to Google Cloud see the [Authentication
+  # Guide](https://googlecloudplatform.github.io/gcloud-ruby/#/docs/guides/authentication).
+  #
+  # @param [String, Array<String>] scope The OAuth 2.0 scopes controlling the
+  #   set of resources and operations that the connection can access. See [Using
+  #   OAuth 2.0 to Access Google
+  #   APIs](https://developers.google.com/identity/protocols/OAuth2).
+  #
+  #   The default scope is:
+  #
+  #   * `https://www.googleapis.com/auth/logging.admin`
+  #
+  # @return [Gcloud::Logging::Project]
+  #
+  # @example
+  #   require "gcloud"
+  #
+  #   gcloud = Gcloud.new
+  #   logging = gcloud.logging
+  #   # ...
+  #
+  # @example The default scope can be overridden with the `scope` option:
+  #   require "gcloud"
+  #
+  #   gcloud  = Gcloud.new
+  #   platform_scope = "https://www.googleapis.com/auth/cloud-platform"
+  #   logging = gcloud.logging scope: platform_scope
+  #
+  def logging scope: nil
+    require "gcloud/logging"
+    Gcloud.logging @project, @keyfile, scope: scope
+  end
 end