introduce Logging support

README.md

@@ -17,6 +17,7 @@ This client supports the following Google Cloud Platform services:
 * [Google Cloud Storage](#google-cloud-storage)
 * [Google Compute Engine](#google-compute-engine)
 * [Google Prediction API](#google-prediction-api)
+* [Google Cloud Logging](#google-cloud-logging-beta) (Beta)
 * [Google Cloud Resource Manager](#google-cloud-resource-manager-beta) (Beta)
 * [Google Cloud Search](#google-cloud-search-alpha) (Alpha)
 
@@ -385,12 +386,62 @@ model.query('Hello', function(err, results) {
     // ]
   }
 });
+
+
+## Google Cloud Logging (Beta)
+
+> **This is a Beta release of Google Cloud Logging.** This API is not covered by any SLA or deprecation policy and may be subject to backward-incompatible changes.
+
+- [API Documentation][gcloud-logging-docs]
+- [Official Documentation][cloud-logging-docs]
+
+```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();
+
+logging.createSink('my-new-sink', {
+  destination: gcs.bucket('my-sink')
+}, function(err, sink) {});
+
+// Write a critical entry to a log.
+var syslog = logging.log('syslog');
+
+var resource = {
+  type: 'gce_instance',
+  labels: {
+    zone: 'global',
+    instance_id: 3
+  }
+};
+
+var entry = syslog.entry(resource, {
+  delegate: process.env.user
+});
+
+syslog.critical(entry, function(err) {});
+
+// Get all entries in your project.
+logging.getEntries(function(err, entries) {
+  if (!err) {
+    // `entries` contains all of the entries from the logs in your project.
+  }
+});
 ```
 
 
 ## Google Cloud Resource Manager (Beta)
 
-> This is a *Beta* release of Google Cloud Resource Manager. This feature is not covered by any SLA or deprecation policy and may be subject to backward-incompatible changes.
+> **This is a Beta release of Google Cloud Resource Manager.** This feature is not covered by any SLA or deprecation policy and may be subject to backward-incompatible changes.
 
 - [API Documentation][gcloud-resource-docs]
 - [Official Documentation][cloud-resource-docs]
@@ -426,7 +477,7 @@ project.getMetadata(function(err, metadata) {
 
 ## Google Cloud Search (Alpha)
 
-> This is an *Alpha* release of Google Cloud Search. This feature is not covered by any SLA or deprecation policy and may be subject to backward-incompatible changes.
+> **This is an Alpha release of Google Cloud Search.** This feature is not covered by any SLA or deprecation policy and may be subject to backward-incompatible changes.
 
 - [API Documentation][gcloud-search-docs]
 - [Official Documentation][cloud-search-docs]
@@ -485,6 +536,7 @@ Apache 2.0 - See [COPYING](COPYING) for more information.
 [gcloud-datastore-docs]: https://googlecloudplatform.github.io/gcloud-node/#/docs/datastore
 [gcloud-dns-docs]: https://googlecloudplatform.github.io/gcloud-node/#/docs/dns
 [gcloud-prediction-docs]: https://googlecloudplatform.github.io/gcloud-node/#/docs/prediction
+[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
@@ -514,6 +566,8 @@ Apache 2.0 - See [COPYING](COPYING) for more information.
 
 [cloud-prediction-docs]: https://cloud.google.com/prediction/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/site/components/docs/docs-values.js

@@ -135,6 +135,25 @@ angular.module('gcloud.docs')
       ]
     },
 
+    logging: {
+      title: 'Logging',
+      _url: '{baseUrl}/logging',
+      pages: [
+        {
+          title: 'Entry',
+          url: '/entry'
+        },
+        {
+          title: 'Log',
+          url: '/log'
+        },
+        {
+          title: 'Sink',
+          url: '/sink'
+        }
+      ]
+    },
+
     prediction: {
       title: 'Prediction',
       _url: '{baseUrl}/prediction',
@@ -275,7 +294,7 @@ angular.module('gcloud.docs')
       // introduce Storage#Channel.
       '>=0.26.0': ['storageWithChannels'],
 
-      // introduce prediction api.
-      '>=0.27.0': ['prediction']
+      // introduce prediction & logging api.
+      '>=0.27.0': ['prediction', 'logging']
     }
   });

docs/site/components/docs/docs.html

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

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

@@ -0,0 +1,11 @@
+<h3>Logging Overview</h3>
+<p class="notice">
+  <strong>This is a Beta release of Google Cloud Logging.</strong> This API is not covered by any SLA or deprecation policy and may be subject to backward-incompatible changes.
+</p>
+<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>
+

lib/index.js

@@ -135,6 +135,34 @@ var apis = {
    */
   prediction: require('./prediction'),
 
+  /**
+   * [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`.
+   *
+   * <p class="notice">
+   *   **This is a Beta release of Google Cloud Logging.** This API is not
+   *   covered by any SLA or deprecation policy and may be subject to backward-
+   *   incompatible changes.
+   * </p>
+   *
+   * @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
@@ -165,9 +193,9 @@ var apis = {
    *   - Recover projects.
    *
    * <p class="notice">
-   *   **This is a *Beta* release of Cloud Resource Manager.** This feature is
-   *   not covered by any SLA or deprecation policy and may be subject to
-   *   backward-incompatible changes.
+   *   **This is a Beta release of Cloud Resource Manager.** This feature is not
+   *   covered by any SLA or deprecation policy and may be subject to backward-
+   *   incompatible changes.
    * </p>
    *
    * @type {module:resource}
@@ -190,9 +218,9 @@ var apis = {
    * maintaining a search service.
    *
    * <p class="notice">
-   *   **This is an *Alpha* release of Google Cloud Search.** This feature is
-   *   not covered by any SLA or deprecation policy and may be subject to
-   *   backward-incompatible changes.
+   *   **This is an Alpha release of Google Cloud Search.** This feature is not
+   *   covered by any SLA or deprecation policy and may be subject to backward-
+   *   incompatible changes.
    * </p>
    *
    * @type {module:search}

lib/logging/entry.js

@@ -0,0 +1,140 @@
+/*!
+ * Copyright 2015 Google Inc. All Rights Reserved.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+/*!
+ * @module logging/entry
+ */
+
+'use strict';
+
+var extend = require('extend');
+var is = require('is');
+
+/**
+ * Create an entry object to define new data to insert into a log.
+ *
+ * @resource [LogEntry JSON representation]{@link https://cloud.google.com/logging/docs/api/ref_v2beta1/rest/v2beta1/LogEntry}
+ *
+ * @param {object=|string=} resource - See a
+ *     [Monitored Resource](https://cloud.google.com/logging/docs/api/ref_v2beta1/rest/v2beta1/MonitoredResource).
+ * @param {object|string} data - The data to use as the value for this log
+ *     entry.
+ * @return {module:logging/entry}
+ *
+ * @example
+ * var gcloud = require('gcloud')({
+ *   keyFilename: '/path/to/keyfile.json',
+ *   projectId: 'grape-spaceship-123'
+ * });
+ *
+ * var logging = gcloud.logging();
+ *
+ * var syslog = logging.log('syslog');
+ *
+ * var resource = {
+ *   type: 'gce_instance',
+ *   labels: {
+ *     zone: 'global',
+ *     instance_id: 3
+ *   }
+ * };
+ *
+ * var entry = syslog.entry(resource, {
+ *   delegate: process.env.user
+ * });
+ *
+ * syslog.alert(entry, function(err, apiResponse) {
+ *   if (!error) {
+ *     // Log entry inserted successfully.
+ *   }
+ * });
+ *
+ * //-
+ * // You will also receive `Entry` objects when using
+ * // {module:logging#getEntries} and {module:logging/log#getEntries}.
+ * //-
+ * logging.getEntries(function(err, entries) {
+ *   if (!err) {
+ *     // entries[0].data = The data value from the log entry.
+ *   }
+ * });
+ */
+function Entry(resource, data) {
+  if (!data) {
+    this.data = resource;
+    return;
+  }
+
+  this.resource = resource;
+  this.data = data;
+}
+
+/**
+ * Create an Entry object from an API response, such as `entries:list`.
+ *
+ * @private
+ *
+ * @param {object} entry - An API representation of an entry. See a
+ *     [LogEntry](https://cloud.google.com/logging/docs/api/ref_v2beta1/rest/v2beta1/LogEntry).
+ * @return {module:logging/entity}
+ */
+Entry.fromApiResponse_ = function(entry) {
+  // Only one of these are populated.
+  var data = entry.protoPayload || entry.jsonPayload || entry.textPayload;
+  return extend(new Entry(entry.resource, data), entry);
+};
+
+/**
+ * Serialize an entry to the format the API expects.
+ *
+ * @private
+ */
+Entry.prototype.toJSON = function() {
+  var entry = extend(true, {}, this);
+
+  var whitelist = [
+    'logName',
+    'resource',
+    'timestamp',
+    'severity',
+    'insertId',
+    'httpRequest',
+    'labels',
+    'operation'
+  ];
+
+  for (var prop in entry) {
+    if (whitelist.indexOf(prop) === -1) {
+      delete entry[prop];
+    }
+  }
+
+  if (is.string(this.resource)) {
+    entry.resource = {
+      type: this.resource
+    };
+  }
+
+  if (is.object(this.data)) {
+    entry.jsonPayload = this.data;
+  } else if (is.string(this.data)) {
+    entry.textPayload = this.data;
+  }
+
+  return entry;
+};
+
+module.exports = Entry;