diff --git a/docs/logging-usage.rst b/docs/logging-usage.rst index 9b23e2edd8ab..ec8f157cec5c 100644 --- 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::