Merge pull request #1905 from daspecster/add-logging-export-ownership-doc

daspecster · web-flow · commit ea50f555130c · 2016-06-27T12:42:31.000-04:00
Add docs, exporting logging to storage permissions.
diff --git a/docs/logging-usage.rst b/docs/logging-usage.rst
@@ -205,13 +205,74 @@ Delete a metric:
    >>> metric.exists()  # API call
    False
 
-
 Export log entries using sinks
 ------------------------------
 
 Sinks allow exporting entries which match a given filter to Cloud Storage
 buckets, BigQuery datasets, or Cloud Pub/Sub topics.
 
+Export to Cloud storage
+~~~~~~~~~~~~~~~~~~~~~~~
+
+Make sure that the storage bucket you want to export logs too has
+`cloud-logs@google.com` as the owner. See `Set permission for writing exported logs`_.
+
+Add `cloud-logs@google.com` as the owner of `my-bucket-name`:
+
+.. doctest::
+
+    >>> from gcloud import storage
+    >>> client = storage.Client()
+    >>> bucket = client.get_bucket('my-bucket-name')
+    >>> bucket.acl.reload()
+    >>> logs_group = bucket.acl.group('cloud-logs@google.com')
+    >>> logs_group.grant_owner()
+    >>> bucket.acl.add_entity(logs_group)
+    >>> bucket.acl.save()
+
+.. _Set permission for writing exported logs: https://cloud.google.com/logging/docs/export/configure_export#setting_product_name_short_permissions_for_writing_exported_logs
+
+Export to BigQuery
+~~~~~~~~~~~~~~~~~~
+
+To export logs to BigQuery you must log into the Cloud Platform Console
+and add `cloud-logs@google.com` to a dataset.
+
+See: `Setting permissions for BigQuery`_
+
+.. doctest::
+    >>> from gcloud import bigquery
+    >>> from gcloud.bigquery.dataset import AccessGrant
+    >>> bigquery_client = bigquery.Client()
+    >>> dataset = bigquery_client.dataset('my-dataset-name')
+    >>> dataset.create()
+    >>> dataset.reload()
+    >>> grants = dataset.access_grants
+    >>> grants.append(AccessGrant(
+    ...     'WRITER', 'groupByEmail', 'cloud-logs@google.com')))
+    >>> dataset.access_grants = grants
+    >>> dataset.update()
+
+.. _Setting permissions for BigQuery: https://cloud.google.com/logging/docs/export/configure_export#manual-access-bq
+
+Export to Pub/Sub
+~~~~~~~~~~~~~~~~~
+
+To export logs to BigQuery you must log into the Cloud Platform Console
+and add `cloud-logs@google.com` to a topic.
+
+See: `Setting permissions for Pub/Sub`_
+
+.. doctest::
+    >>> from gcloud import pubsub
+    >>> client = pubsub.Client()
+    >>> topic = client.topic('your-topic-name')
+    >>> policy = top.get_iam_policy()
+    >>> policy.owners.add(policy.group('cloud-logs@google.com'))
+    >>> topic.set_iam_policy(policy)
+
+.. _Setting permissions for Pub/Sub: https://cloud.google.com/logging/docs/export/configure_export#manual-access-pubsub
+
 Create a Cloud Storage sink:
 
 .. doctest::
