introduce Logging support

Author: stephenplusplus

README.md

@@ -13,6 +13,7 @@ This client supports the following Google Cloud Platform services:
 * [Google BigQuery](#google-bigquery)
 * [Google Cloud Datastore](#google-cloud-datastore)
 * [Google Cloud DNS](#google-cloud-dns)
+* [Google Cloud Logging](#google-cloud-logging)
 * [Google Cloud Pub/Sub](#google-cloud-pubsub)
 * [Google Cloud Storage](#google-cloud-storage)
 * [Google Compute Engine](#google-compute-engine)
@@ -209,6 +210,49 @@ zone.export('/zonefile.zone', function(err) {});
 ```
 
 
+## Google Cloud Logging
+
+- [API Documentation][gcloud-logging-docs]
+- [Official Documentation][cloud-logging-docs]
+
+#### Preview
+
+```js
+// Authenticating on a global-basis. You can also authenticate on a per-API-
+// basis (see Authentication section above).
+var gcloud = require('gcloud')({
+  projectId: 'my-project',
+  keyFilename: '/path/to/keyfile.json'
+});
+
+var logging = gcloud.logging();
+
+// Create a sink using a Bucket as a destination.
+var gcs = gcloud.storage();
+
+dns.createSink('my-new-sink', {
+  destination: gcs.bucket('my-sink')
+}, function(err, sink) {});
+
+// Write a critical entry to a log.
+var log = logging.log('compute.googleapis.com');
+
+log.critical({
+  metadata: {
+    serviceName: 'compute.googleapis.com'
+  },
+  data: {
+    delegate: process.env.USER
+  }
+}, function(err) {});
+
+// Get indexes from a service like Compute Engine.
+var service = logging.service('compute.googleapis.com');
+
+service.getIndexes(function(err, indexes) {});
+```
+
+
 ## Google Cloud Pub/Sub
 
 - [API Documentation][gcloud-pubsub-docs]
@@ -433,6 +477,7 @@ Apache 2.0 - See [COPYING](COPYING) for more information.
 [gcloud-compute-docs]: https://googlecloudplatform.github.io/gcloud-node/#/docs/compute
 [gcloud-datastore-docs]: https://googlecloudplatform.github.io/gcloud-node/#/docs/datastore
 [gcloud-dns-docs]: https://googlecloudplatform.github.io/gcloud-node/#/docs/dns
+[gcloud-logging-docs]: https://googlecloudplatform.github.io/gcloud-node/#/docs/logging
 [gcloud-pubsub-docs]: https://googlecloudplatform.github.io/gcloud-node/#/docs/pubsub
 [gcloud-resource-docs]: https://googlecloudplatform.github.io/gcloud-node/#/docs/resource
 [gcloud-search-docs]: https://googlecloudplatform.github.io/gcloud-node/#/docs/search
@@ -460,6 +505,8 @@ Apache 2.0 - See [COPYING](COPYING) for more information.
 
 [cloud-dns-docs]: https://cloud.google.com/dns/docs
 
+[cloud-logging-docs]: https://cloud.google.com/logging/docs
+
 [cloud-pubsub-docs]: https://cloud.google.com/pubsub/docs
 
 [cloud-resource-docs]: https://cloud.google.com/resource-manager

docs/json/master/logging/.gitkeep

@@ -135,6 +135,25 @@ angular.module('gcloud.docs')
       ]
     },
 
+    logging: {
+      title: 'Logging',
+      _url: '{baseUrl}/logging',
+      pages: [
+        {
+          title: 'Log',
+          url: '/log'
+        },
+        {
+          title: 'Service',
+          url: '/service'
+        },
+        {
+          title: 'Sink',
+          url: '/sink'
+        }
+      ]
+    },
+
     pubsub: {
       title: 'PubSub',
       _url: '{baseUrl}/pubsub',
@@ -240,6 +259,9 @@ angular.module('gcloud.docs')
       '>=0.20.0': ['compute'],
 
       // introduce resource api.
-      '>=0.22.0': ['resource']
+      '>=0.22.0': ['resource'],
+
+      // introduce logging api.
+      '>=0.25.0': ['logging']
     }
   });

docs/site/components/docs/docs-values.js

@@ -44,7 +44,7 @@ <h3 class="sub-heading">
     </article>
     <hr>
 
-    <article ng-repeat="service in ['bigquery', 'compute', 'datastore', 'dns', 'pubsub', 'resource', 'search', 'storage']"
+    <article ng-repeat="service in ['bigquery', 'compute', 'datastore', 'dns', 'pubsub', 'logging', 'resource', 'search', 'storage']"
              ng-if="isActiveDoc(service)"
              ng-include="'site/components/docs/' + service + '-overview.html'">
     </article>

docs/site/components/docs/docs.html

@@ -0,0 +1,8 @@
+<h3>Logging Overview</h3>
+<p>
+  The <code>gcloud.logging</code> method will return a <code>logging</code> object, allowing you to create sinks, write log entries, and more.
+</p>
+<p>
+  To learn more about Logging, see the <a href="https://cloud.google.com/logging/docs">What is Google Cloud Logging?</a>
+</p>
+

docs/site/components/docs/logging-overview.html

@@ -312,7 +312,7 @@ ServiceObject.prototype.request = function(reqOpts, callback) {
     })
     .join('/');
 
-  this.parent.request(reqOpts, callback);
+  return this.parent.request(reqOpts, callback);
 };
 
 module.exports = ServiceObject;

lib/common/service-object.js

@@ -84,7 +84,7 @@ Service.prototype.request = function(reqOpts, callback) {
     // Good: https://.../projects:list
     .replace(/\/:/g, ':');
 
-  this.makeAuthenticatedRequest(reqOpts, callback);
+  return this.makeAuthenticatedRequest(reqOpts, callback);
 };
 
 module.exports = Service;

lib/common/service.js

@@ -108,6 +108,34 @@ var apis = {
    */
   dns: require('./dns'),
 
+  /**
+   * <p class="notice">
+   *   **This is a *Beta* release of Google Cloud Logging for Google Compute
+   *   Engine.** This feature is not covered by any SLA or deprecation policy
+   *   and may be subject to backward-incompatible changes.
+   * </p>
+   *
+   * [Google Cloud Logging](https://cloud.google.com/logging/docs) collects and
+   * stores logs from applications and services on the Google Cloud Platform:
+   *
+   *   - Export your logs to Google Cloud Storage, Google BigQuery, or Google
+   *     Cloud Pub/Sub.
+   *   - Integrate third-party logs from your virtual machine instances by
+   *     installing the logging agent, `google-fluentd`.
+   *
+   * @type {module:logging}
+   *
+   * @return {module:logging}
+   *
+   * @example
+   * var gcloud = require('gcloud');
+   * var logging = gcloud.logging({
+   *   projectId: 'grape-spaceship-123',
+   *   keyFilename: '/path/to/keyfile.json'
+   * });
+   */
+  logging: require('./logging'),
+
   /**
    * [Google Cloud Pub/Sub](https://developers.google.com/pubsub/overview) is a
    * reliable, many-to-many, asynchronous messaging service from Google Cloud