From 2e8b2dac95857a97d8ad0181ef493e272569c202 Mon Sep 17 00:00:00 2001
From: Tres Seaver <tseaver@palladion.com>
Date: Thu, 18 Feb 2016 12:42:59 -0500
Subject: [PATCH 01/19] Initial sketch of logging API usage docs.

---
 docs/index.rst         |   7 +
 docs/logging-usage.rst | 295 +++++++++++++++++++++++++++++++++++++++++
 2 files changed, 302 insertions(+)
 create mode 100644 docs/logging-usage.rst

diff --git a/docs/index.rst b/docs/index.rst
index c08588dfa8b1..921a9b3b3cd9 100644
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -83,6 +83,13 @@
   search-index
   search-document
 
+.. toctree::
+  :maxdepth: 0
+  :hidden:
+  :caption: Cloud Logging
+
+  logging-usage
+
 .. toctree::
   :maxdepth: 0
   :hidden:
diff --git a/docs/logging-usage.rst b/docs/logging-usage.rst
new file mode 100644
index 000000000000..5bf4de24b54a
--- /dev/null
+++ b/docs/logging-usage.rst
@@ -0,0 +1,295 @@
+Using the API
+=============
+
+Authentication / Configuration
+------------------------------
+
+- Use :class:`Client <gcloud.logging.client.Client>` objects to configure
+  your applications.
+
+- :class:`Client <gcloud.logging.client.Client>` objects hold both a ``project``
+  and an authenticated connection to the Logging service.
+
+- The authentication credentials can be implicitly determined from the
+  environment or directly via
+  :meth:`from_service_account_json <gcloud.logging.client.Client.from_service_account_json>`
+  and
+  :meth:`from_service_account_p12 <gcloud.logging.client.Client.from_service_account_p12>`.
+
+- After setting ``GOOGLE_APPLICATION_CREDENTIALS`` and ``GCLOUD_PROJECT``
+  environment variables, create a :class:`Client <gcloud.logging.client.Client>`
+
+  .. doctest::
+
+     >>> from gcloud import logging
+     >>> client = logging.Client()
+
+Writing log entries
+-------------------
+
+Write a simple text entry to a log.
+
+.. doctest::
+
+   >>> from gcloud import logging
+   >>> client = logging.Client()
+   >>> log = client.log('log_name')
+   >>> log.text("A simple entry")  # API call
+
+Write a dictionary entry to a log.
+
+.. doctest::
+
+   >>> from gcloud import logging
+   >>> client = logging.Client()
+   >>> log = client.log('log_name')
+   >>> log.struct(message="My second entry",
+   ...     weather="partly cloudy")  # API call
+
+Retrieving log entries
+----------------------
+
+Fetch entries for the default project.
+
+.. doctest::
+
+   >>> from gcloud import logging
+   >>> client = logging.Client()
+   >>> entries, token = client.list_entries()  # API call
+   >>> for entry in entries:
+   ...    timestamp = entry.timestamp.ISO()
+   ...    print(timestamp, entry.text_payload, entry.struct_payload)
+   ('2016-02-17T20:35:49.031864072Z', 'A simple entry', None)
+   ('2016-02-17T20:38:15.944418531Z,' None, {'message': 'My second entry', 'weather': 'partly cloudy'})
+
+
+Fetch entries across multiple projects.
+
+.. doctest::
+
+   >>> from gcloud import logging
+   >>> client = logging.Client()
+   >>> entries, token = client.list_entries(
+   ...     project_ids=['one-project', 'another-project'])  # API call
+
+
+Filter entries retrieved using the "Advance Logs Filters" syntax (see
+https://cloud.google.com/logging/docs/view/advanced_filters).
+
+.. doctest::
+
+   >>> from gcloud import logging
+   >>> client = logging.Client()
+   >>> FILTER = "log:log_name AND textPayload:simple"
+   >>> entries, token = client.list_entries(filter=FILTER)  # API call
+
+Sort entries in descending timestamp order.
+
+.. doctest::
+
+   >>> from gcloud import logging
+   >>> client = logging.Client()
+   >>> entries, token = client.list_entries(order_by='timestamp desc')  # API call
+
+Retrieve entities in batches of 10, iterating until done.
+
+.. doctest::
+
+   >>> from gcloud import logging
+   >>> client = logging.Client()
+   >>> retrieved = []
+   >>> token = None
+   >>> while True:
+   ...     entries, token = client.list_entries(page_size=10)  # API call
+   ...     retrieved.extend(entries)
+   ...     if token is None:
+   ...         break
+
+
+Deleting all entries for a log
+------------------------------
+
+.. doctest::
+
+   >>> from gcloud import logging
+   >>> client = logging.Client()
+   >>> log = client.log('log_name')
+   >>> log.delete()  # API call
+
+
+Manage log metrics
+------------------
+
+Metrics are counters of entries which match a given filter.  They can be
+used within Cloud Monitoring to create charts and alerts.
+
+Create a metric:
+
+.. doctest::
+
+   >>> from gcloud import logging
+   >>> client = logging.Client()
+   >>> metric = client.metric("robots", "Robots all up in your server",
+   ...     filter='log:apache-access AND textPayload:robot')
+   >>> metric.exists()  # API call
+   False
+   >>> metric.create()  # API call
+   >>> metric.exists()  # API call
+   True
+
+List all metrics for a project:
+
+.. doctest::
+
+   >>> from gcloud import logging
+   >>> client = logging.Client()
+   >>> metrics, token = client.list_metrics()
+   >>> len(metrics)
+   0
+   >>> metric = metrics[0]
+   >>> metric.name
+   "robots"
+
+Refresh local information about a metric:
+
+.. doctest::
+
+   >>> from gcloud import logging
+   >>> client = logging.Client()
+   >>> metric = client.metric("robots")
+   >>> metric.get()  # API call
+   >>> metric.description
+   "Robots all up in your server"
+   >>> metric.filter
+   "log:apache-access AND textPayload:robot"
+
+Update a metric:
+
+.. doctest::
+
+   >>> from gcloud import logging
+   >>> client = logging.Client()
+   >>> metric = client.metric("robots")
+   >>> metric.exists()  # API call
+   True
+   >>> metric.get()  # API call
+   >>> metric.description = "Danger, Will Robinson!"
+   >>> metric.update()  # API call
+
+Delete a metric:
+
+.. doctest::
+
+   >>> from gcloud import logging
+   >>> client = logging.Client()
+   >>> metric = client.metric("robots")
+   >>> metric.exists()  # API call
+   True
+   >>> metric.delete()  # API call
+   >>> 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 Pubsub topics.
+
+Create a CloudStorage sink:
+
+.. doctest::
+
+   >>> from gcloud import logging
+   >>> client = logging.Client()
+   >>> sink = client.sink("robots-storage",
+   ...     filter='log:apache-access AND textPayload:robot')
+   >>> sink.storage_bucket = "my-bucket-name"
+   >>> sink.exists()  # API call
+   False
+   >>> sink.create()  # API call
+   >>> sink.exists()  # API call
+   True
+
+Create a BigQuery sink:
+
+.. doctest::
+
+   >>> from gcloud import logging
+   >>> client = logging.Client()
+   >>> sink = client.sink("robots-bq",
+   ...     filter='log:apache-access AND textPayload:robot')
+   >>> sink.bigquery_dataset = "projects/my-project/datasets/my-dataset"
+   >>> sink.exists()  # API call
+   False
+   >>> sink.create()  # API call
+   >>> sink.exists()  # API call
+   True
+
+Create a Pubsub sink:
+
+.. doctest::
+
+   >>> from gcloud import logging
+   >>> client = logging.Client()
+   >>> sink = client.sink("robots-pubsub",
+   ...     filter='log:apache-access AND textPayload:robot')
+   >>> sink.pubsub_topic = 'projects/my-project/topics/my-topic'
+   >>> sink.exists()  # API call
+   False
+   >>> sink.create()  # API call
+   >>> sink.exists()  # API call
+   True
+
+List all sinks for a project:
+
+.. doctest::
+
+   >>> from gcloud import logging
+   >>> client = logging.Client()
+   >>> sinks, token = client.list_sinks()
+   >>> for sink in sinks:
+   ...     print(sink.name, sink.destination)
+   ('robots-storage', 'storage.googleapis.com/my-bucket-name')
+   ('robots-bq', 'bigquery.googleapis.com/projects/my-project/datasets/my-dataset')
+   ('robots-pubsub', 'pubsub.googleapis.com/projects/my-project/topics/my-topic')
+
+Refresh local information about a sink:
+
+.. doctest::
+
+   >>> from gcloud import logging
+   >>> client = logging.Client()
+   >>> sink = client.sink('robots-storage')
+   >>> sink.filter is None
+   True
+   >>> sink.get()  # API call
+   >>> sink.filter
+   'log:apache-access AND textPayload:robot'
+   >>> sink.destination
+   'storage.googleapis.com/my-bucket-name')
+
+Update a sink:
+
+.. doctest::
+
+   >>> from gcloud import logging
+   >>> client = logging.Client()
+   >>> sink = client.sink("robots")
+   >>> sink.get()  # API call
+   >>> sink.filter = "log:apache-access"
+   >>> sink.update()  # API call
+
+Delete a sink:
+
+.. doctest::
+
+   >>> from gcloud import logging
+   >>> client = logging.Client()
+   >>> sink = client.sink("robots",
+   ...     filter='log:apache-access AND textPayload:robot')
+   >>> sink.exists()  # API call
+   True
+   >>> sink.delete()  # API call
+   >>> sink.exists()  # API call
+   False

From f413435581ad6b4f3217e61e0165803d0627cd43 Mon Sep 17 00:00:00 2001
From: Tres Seaver <tseaver@palladion.com>
Date: Thu, 18 Feb 2016 16:26:31 -0500
Subject: [PATCH 02/19] Pull in auth/config section from #1420.

Addresses:
https://github.com/GoogleCloudPlatform/gcloud-python/pull/1488/files#r53380211
---
 docs/logging-usage.rst | 31 +++++++++++++++++--------------
 1 file changed, 17 insertions(+), 14 deletions(-)

diff --git a/docs/logging-usage.rst b/docs/logging-usage.rst
index 5bf4de24b54a..6d1848fbdf25 100644
--- a/docs/logging-usage.rst
+++ b/docs/logging-usage.rst
@@ -1,29 +1,32 @@
 Using the API
 =============
 
-Authentication / Configuration
-------------------------------
-
-- Use :class:`Client <gcloud.logging.client.Client>` objects to configure
-  your applications.
+Authentication and Configuration
+--------------------------------
 
-- :class:`Client <gcloud.logging.client.Client>` objects hold both a ``project``
-  and an authenticated connection to the Logging service.
+- For an overview of authentication in ``gcloud-python``,
+  see :doc:`gcloud-auth`.
 
-- The authentication credentials can be implicitly determined from the
-  environment or directly via
-  :meth:`from_service_account_json <gcloud.logging.client.Client.from_service_account_json>`
-  and
-  :meth:`from_service_account_p12 <gcloud.logging.client.Client.from_service_account_p12>`.
+- In addition to any authentication configuration, you should also set the
+  :envvar:`GCLOUD_PROJECT` environment variable for the project you'd like
+  to interact with. If you are Google App Engine or Google Compute Engine
+  this will be detected automatically.
 
-- After setting ``GOOGLE_APPLICATION_CREDENTIALS`` and ``GCLOUD_PROJECT``
-  environment variables, create a :class:`Client <gcloud.logging.client.Client>`
+- After configuring your environment, create a
+  :class:`Client <gcloud.logging.client.Client>`
 
   .. doctest::
 
      >>> from gcloud import logging
      >>> client = logging.Client()
 
+  or pass in ``credentials`` and ``project`` explicitly
+
+  .. doctest::
+
+     >>> from gcloud import logging
+     >>> client = logging.Client(project='my-project', credentials=creds)
+
 Writing log entries
 -------------------
 

From 4d61743a6061be93943f53bb8158d4a7785adb2e Mon Sep 17 00:00:00 2001
From: Tres Seaver <tseaver@palladion.com>
Date: Thu, 18 Feb 2016 16:32:43 -0500
Subject: [PATCH 03/19] Clean up Py2/Py3 print differences.

Addresses:
https://github.com/GoogleCloudPlatform/gcloud-python/pull/1488/files#r53380934
https://github.com/GoogleCloudPlatform/gcloud-python/pull/1488/files#r53380856
---
 docs/logging-usage.rst | 17 +++++++++--------
 1 file changed, 9 insertions(+), 8 deletions(-)

diff --git a/docs/logging-usage.rst b/docs/logging-usage.rst
index 6d1848fbdf25..99bb7784a200 100644
--- a/docs/logging-usage.rst
+++ b/docs/logging-usage.rst
@@ -60,10 +60,11 @@ Fetch entries for the default project.
    >>> client = logging.Client()
    >>> entries, token = client.list_entries()  # API call
    >>> for entry in entries:
-   ...    timestamp = entry.timestamp.ISO()
-   ...    print(timestamp, entry.text_payload, entry.struct_payload)
-   ('2016-02-17T20:35:49.031864072Z', 'A simple entry', None)
-   ('2016-02-17T20:38:15.944418531Z,' None, {'message': 'My second entry', 'weather': 'partly cloudy'})
+   ...    timestamp = entry.timestamp.isoformat()
+   ...    print('%sZ: %s | %s" %
+   ...          (timestamp, entry.text_payload, entry.struct_payload))
+   2016-02-17T20:35:49.031864072Z: A simple entry | None
+   2016-02-17T20:38:15.944418531Z: None | {'message': 'My second entry', 'weather': 'partly cloudy'}
 
 
 Fetch entries across multiple projects.
@@ -252,10 +253,10 @@ List all sinks for a project:
    >>> client = logging.Client()
    >>> sinks, token = client.list_sinks()
    >>> for sink in sinks:
-   ...     print(sink.name, sink.destination)
-   ('robots-storage', 'storage.googleapis.com/my-bucket-name')
-   ('robots-bq', 'bigquery.googleapis.com/projects/my-project/datasets/my-dataset')
-   ('robots-pubsub', 'pubsub.googleapis.com/projects/my-project/topics/my-topic')
+   ...     print('%s: %s' % (sink.name, sink.destination))
+   robots-storage: storage.googleapis.com/my-bucket-name
+   robots-bq: bigquery.googleapis.com/projects/my-project/datasets/my-dataset
+   robots-pubsub: pubsub.googleapis.com/projects/my-project/topics/my-topic
 
 Refresh local information about a sink:
 

From 0deb35631d751d35b238bc3fdc98f3a366586c1a Mon Sep 17 00:00:00 2001
From: Tres Seaver <tseaver@palladion.com>
Date: Thu, 18 Feb 2016 16:34:39 -0500
Subject: [PATCH 04/19] Make vertical whitespace consistent.

Addresses:
https://github.com/GoogleCloudPlatform/gcloud-python/pull/1488/files#r53381178
---
 docs/logging-usage.rst | 9 +++++----
 1 file changed, 5 insertions(+), 4 deletions(-)

diff --git a/docs/logging-usage.rst b/docs/logging-usage.rst
index 99bb7784a200..5c4622d73e3f 100644
--- a/docs/logging-usage.rst
+++ b/docs/logging-usage.rst
@@ -1,6 +1,7 @@
 Using the API
 =============
 
+
 Authentication and Configuration
 --------------------------------
 
@@ -27,6 +28,7 @@ Authentication and Configuration
      >>> from gcloud import logging
      >>> client = logging.Client(project='my-project', credentials=creds)
 
+
 Writing log entries
 -------------------
 
@@ -49,6 +51,7 @@ Write a dictionary entry to a log.
    >>> log.struct(message="My second entry",
    ...     weather="partly cloudy")  # API call
 
+
 Retrieving log entries
 ----------------------
 
@@ -66,7 +69,6 @@ Fetch entries for the default project.
    2016-02-17T20:35:49.031864072Z: A simple entry | None
    2016-02-17T20:38:15.944418531Z: None | {'message': 'My second entry', 'weather': 'partly cloudy'}
 
-
 Fetch entries across multiple projects.
 
 .. doctest::
@@ -76,7 +78,6 @@ Fetch entries across multiple projects.
    >>> entries, token = client.list_entries(
    ...     project_ids=['one-project', 'another-project'])  # API call
 
-
 Filter entries retrieved using the "Advance Logs Filters" syntax (see
 https://cloud.google.com/logging/docs/view/advanced_filters).
 
@@ -110,8 +111,8 @@ Retrieve entities in batches of 10, iterating until done.
    ...         break
 
 
-Deleting all entries for a log
-------------------------------
+Delete all entries for a log
+----------------------------
 
 .. doctest::
 

From 3bf1e7adb26eb9ae9ead7e7ab1e13bc57f7f4054 Mon Sep 17 00:00:00 2001
From: Tres Seaver <tseaver@palladion.com>
Date: Thu, 18 Feb 2016 16:36:16 -0500
Subject: [PATCH 05/19] Use ReST link syntax, rather than a bare URL.

Addresses:
https://github.com/GoogleCloudPlatform/gcloud-python/pull/1488/files#r53381211
---
 docs/logging-usage.rst | 5 +++--
 1 file changed, 3 insertions(+), 2 deletions(-)

diff --git a/docs/logging-usage.rst b/docs/logging-usage.rst
index 5c4622d73e3f..5e79e6969bf0 100644
--- a/docs/logging-usage.rst
+++ b/docs/logging-usage.rst
@@ -78,8 +78,9 @@ Fetch entries across multiple projects.
    >>> entries, token = client.list_entries(
    ...     project_ids=['one-project', 'another-project'])  # API call
 
-Filter entries retrieved using the "Advance Logs Filters" syntax (see
-https://cloud.google.com/logging/docs/view/advanced_filters).
+Filter entries retrieved using the `Advanced Logs Filters`_ syntax
+
+.. Advanced Logs Filters: https://cloud.google.com/logging/docs/view/advanced_filters
 
 .. doctest::
 

From 97c2874c4f088dbebb09db815102c2ffd4e4d745 Mon Sep 17 00:00:00 2001
From: Tres Seaver <tseaver@palladion.com>
Date: Thu, 18 Feb 2016 16:37:10 -0500
Subject: [PATCH 06/19] Fix typo.

Addresses:
https://github.com/GoogleCloudPlatform/gcloud-python/pull/1488/files#r53381782
---
 docs/logging-usage.rst | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/docs/logging-usage.rst b/docs/logging-usage.rst
index 5e79e6969bf0..fe438d38a3cb 100644
--- a/docs/logging-usage.rst
+++ b/docs/logging-usage.rst
@@ -151,7 +151,7 @@ List all metrics for a project:
    >>> client = logging.Client()
    >>> metrics, token = client.list_metrics()
    >>> len(metrics)
-   0
+   1
    >>> metric = metrics[0]
    >>> metric.name
    "robots"

From 15bdcb6a95174312d8f02066d38292bdd8545a53 Mon Sep 17 00:00:00 2001
From: Tres Seaver <tseaver@palladion.com>
Date: Thu, 18 Feb 2016 16:38:10 -0500
Subject: [PATCH 07/19] Rename '.get()' to '.reload()' for consistency.

Addresses:
https://github.com/GoogleCloudPlatform/gcloud-python/pull/1488/files#r53381896
---
 docs/logging-usage.rst | 8 ++++----
 1 file changed, 4 insertions(+), 4 deletions(-)

diff --git a/docs/logging-usage.rst b/docs/logging-usage.rst
index fe438d38a3cb..b990eb51809f 100644
--- a/docs/logging-usage.rst
+++ b/docs/logging-usage.rst
@@ -163,7 +163,7 @@ Refresh local information about a metric:
    >>> from gcloud import logging
    >>> client = logging.Client()
    >>> metric = client.metric("robots")
-   >>> metric.get()  # API call
+   >>> metric.reload()  # API call
    >>> metric.description
    "Robots all up in your server"
    >>> metric.filter
@@ -178,7 +178,7 @@ Update a metric:
    >>> metric = client.metric("robots")
    >>> metric.exists()  # API call
    True
-   >>> metric.get()  # API call
+   >>> metric.reload()  # API call
    >>> metric.description = "Danger, Will Robinson!"
    >>> metric.update()  # API call
 
@@ -269,7 +269,7 @@ Refresh local information about a sink:
    >>> sink = client.sink('robots-storage')
    >>> sink.filter is None
    True
-   >>> sink.get()  # API call
+   >>> sink.reload()  # API call
    >>> sink.filter
    'log:apache-access AND textPayload:robot'
    >>> sink.destination
@@ -282,7 +282,7 @@ Update a sink:
    >>> from gcloud import logging
    >>> client = logging.Client()
    >>> sink = client.sink("robots")
-   >>> sink.get()  # API call
+   >>> sink.reload()  # API call
    >>> sink.filter = "log:apache-access"
    >>> sink.update()  # API call
 

From 4bbdd17e12488de3fa97bd99881e054088a5e2fb Mon Sep 17 00:00:00 2001
From: Tres Seaver <tseaver@palladion.com>
Date: Thu, 18 Feb 2016 16:39:25 -0500
Subject: [PATCH 08/19] Use 'Pub/Sub' instead of 'Pubsub'.

Addresses:
https://github.com/GoogleCloudPlatform/gcloud-python/pull/1488/files#r53382015
---
 docs/logging-usage.rst | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/docs/logging-usage.rst b/docs/logging-usage.rst
index b990eb51809f..7ff2ce23cb64 100644
--- a/docs/logging-usage.rst
+++ b/docs/logging-usage.rst
@@ -200,7 +200,7 @@ Export log entries using sinks
 ------------------------------
 
 Sinks allow exporting entries which match a given filter to Cloud Storage
-buckets, BigQuery datasets, or Pubsub topics.
+buckets, BigQuery datasets, or Pub/Sub topics.
 
 Create a CloudStorage sink:
 
@@ -232,7 +232,7 @@ Create a BigQuery sink:
    >>> sink.exists()  # API call
    True
 
-Create a Pubsub sink:
+Create a Pub/Sub sink:
 
 .. doctest::
 

From 885c1344de395cb495b17e2059e016102dba1ec2 Mon Sep 17 00:00:00 2001
From: Tres Seaver <tseaver@palladion.com>
Date: Thu, 18 Feb 2016 16:42:18 -0500
Subject: [PATCH 09/19] Follow logging API export docs for branding destination
 services.

Addresses:
https://github.com/GoogleCloudPlatform/gcloud-python/pull/1488/files#r53382062
---
 docs/logging-usage.rst | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

diff --git a/docs/logging-usage.rst b/docs/logging-usage.rst
index 7ff2ce23cb64..5770507cc1d0 100644
--- a/docs/logging-usage.rst
+++ b/docs/logging-usage.rst
@@ -200,9 +200,9 @@ Export log entries using sinks
 ------------------------------
 
 Sinks allow exporting entries which match a given filter to Cloud Storage
-buckets, BigQuery datasets, or Pub/Sub topics.
+buckets, BigQuery datasets, or Cloud Pub/Sub topics.
 
-Create a CloudStorage sink:
+Create a Cloud Storage sink:
 
 .. doctest::
 
@@ -232,7 +232,7 @@ Create a BigQuery sink:
    >>> sink.exists()  # API call
    True
 
-Create a Pub/Sub sink:
+Create a Cloud Pub/Sub sink:
 
 .. doctest::
 

From 22cbb492a21291cd8c0d9520cffe94897a0bc659 Mon Sep 17 00:00:00 2001
From: Tres Seaver <tseaver@palladion.com>
Date: Thu, 18 Feb 2016 16:52:36 -0500
Subject: [PATCH 10/19] Fix typo.

Addresses:
https://github.com/GoogleCloudPlatform/gcloud-python/pull/1488#discussion_r53382547
---
 docs/logging-usage.rst | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/docs/logging-usage.rst b/docs/logging-usage.rst
index 5770507cc1d0..f87ca6b160fb 100644
--- a/docs/logging-usage.rst
+++ b/docs/logging-usage.rst
@@ -273,7 +273,7 @@ Refresh local information about a sink:
    >>> sink.filter
    'log:apache-access AND textPayload:robot'
    >>> sink.destination
-   'storage.googleapis.com/my-bucket-name')
+   'storage.googleapis.com/my-bucket-name'
 
 Update a sink:
 

From bf5b5cc4b1c460f5e7f67bf1496a0fbc554e6793 Mon Sep 17 00:00:00 2001
From: Tres Seaver <tseaver@palladion.com>
Date: Thu, 18 Feb 2016 19:45:26 -0500
Subject: [PATCH 11/19] Typo fix.

Addresses:
https://github.com/GoogleCloudPlatform/gcloud-python/pull/1488#discussion_r53404295
---
 docs/logging-usage.rst | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/docs/logging-usage.rst b/docs/logging-usage.rst
index f87ca6b160fb..cc3d868764cc 100644
--- a/docs/logging-usage.rst
+++ b/docs/logging-usage.rst
@@ -64,7 +64,7 @@ Fetch entries for the default project.
    >>> entries, token = client.list_entries()  # API call
    >>> for entry in entries:
    ...    timestamp = entry.timestamp.isoformat()
-   ...    print('%sZ: %s | %s" %
+   ...    print('%sZ: %s | %s' %
    ...          (timestamp, entry.text_payload, entry.struct_payload))
    2016-02-17T20:35:49.031864072Z: A simple entry | None
    2016-02-17T20:38:15.944418531Z: None | {'message': 'My second entry', 'weather': 'partly cloudy'}

From 449e4f0277614450fd7a54e37f82543268b61fb4 Mon Sep 17 00:00:00 2001
From: Tres Seaver <tseaver@palladion.com>
Date: Thu, 18 Feb 2016 19:46:48 -0500
Subject: [PATCH 12/19] Rewrap doctest continuations.

Addresses:
https://github.com/GoogleCloudPlatform/gcloud-python/pull/1488#discussion_r53382607 et aliae.
---
 docs/logging-usage.rst | 18 ++++++++++++------
 1 file changed, 12 insertions(+), 6 deletions(-)

diff --git a/docs/logging-usage.rst b/docs/logging-usage.rst
index cc3d868764cc..e24057fed738 100644
--- a/docs/logging-usage.rst
+++ b/docs/logging-usage.rst
@@ -48,7 +48,8 @@ Write a dictionary entry to a log.
    >>> from gcloud import logging
    >>> client = logging.Client()
    >>> log = client.log('log_name')
-   >>> log.struct(message="My second entry",
+   >>> log.struct(
+   ...     message="My second entry",
    ...     weather="partly cloudy")  # API call
 
 
@@ -135,7 +136,8 @@ Create a metric:
 
    >>> from gcloud import logging
    >>> client = logging.Client()
-   >>> metric = client.metric("robots", "Robots all up in your server",
+   >>> metric = client.metric(
+   ...     "robots", "Robots all up in your server",
    ...     filter='log:apache-access AND textPayload:robot')
    >>> metric.exists()  # API call
    False
@@ -208,7 +210,8 @@ Create a Cloud Storage sink:
 
    >>> from gcloud import logging
    >>> client = logging.Client()
-   >>> sink = client.sink("robots-storage",
+   >>> sink = client.sink(
+   ...     "robots-storage",
    ...     filter='log:apache-access AND textPayload:robot')
    >>> sink.storage_bucket = "my-bucket-name"
    >>> sink.exists()  # API call
@@ -223,7 +226,8 @@ Create a BigQuery sink:
 
    >>> from gcloud import logging
    >>> client = logging.Client()
-   >>> sink = client.sink("robots-bq",
+   >>> sink = client.sink(
+   ...     "robots-bq",
    ...     filter='log:apache-access AND textPayload:robot')
    >>> sink.bigquery_dataset = "projects/my-project/datasets/my-dataset"
    >>> sink.exists()  # API call
@@ -238,7 +242,8 @@ Create a Cloud Pub/Sub sink:
 
    >>> from gcloud import logging
    >>> client = logging.Client()
-   >>> sink = client.sink("robots-pubsub",
+   >>> sink = client.sink(
+   ...     "robots-pubsub",
    ...     filter='log:apache-access AND textPayload:robot')
    >>> sink.pubsub_topic = 'projects/my-project/topics/my-topic'
    >>> sink.exists()  # API call
@@ -292,7 +297,8 @@ Delete a sink:
 
    >>> from gcloud import logging
    >>> client = logging.Client()
-   >>> sink = client.sink("robots",
+   >>> sink = client.sink(
+   ...     "robots",
    ...     filter='log:apache-access AND textPayload:robot')
    >>> sink.exists()  # API call
    True

From e18acc7318539ec3e03a131fe9701b5ffc4a4efe Mon Sep 17 00:00:00 2001
From: Tres Seaver <tseaver@palladion.com>
Date: Thu, 18 Feb 2016 19:47:56 -0500
Subject: [PATCH 13/19] Fix ReST link syntax.

Addresses:
https://github.com/GoogleCloudPlatform/gcloud-python/pull/1488#discussion_r53404827
---
 docs/logging-usage.rst | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/docs/logging-usage.rst b/docs/logging-usage.rst
index e24057fed738..33ad8eefd8f2 100644
--- a/docs/logging-usage.rst
+++ b/docs/logging-usage.rst
@@ -81,7 +81,7 @@ Fetch entries across multiple projects.
 
 Filter entries retrieved using the `Advanced Logs Filters`_ syntax
 
-.. Advanced Logs Filters: https://cloud.google.com/logging/docs/view/advanced_filters
+.. _Advanced Logs Filters: https://cloud.google.com/logging/docs/view/advanced_filters
 
 .. doctest::
 

From 276b27b7d1665a4761c0777e2082331a5f7f0fd2 Mon Sep 17 00:00:00 2001
From: Tres Seaver <tseaver@palladion.com>
Date: Thu, 18 Feb 2016 19:51:00 -0500
Subject: [PATCH 14/19] Rename the 'log' factory -> 'logger'.

More Pythonic name, even though the backend calls it 'log'.

Addresses:
https://github.com/GoogleCloudPlatform/gcloud-python/pull/1488#discussion_r53403689
---
 docs/logging-usage.rst | 20 ++++++++++----------
 1 file changed, 10 insertions(+), 10 deletions(-)

diff --git a/docs/logging-usage.rst b/docs/logging-usage.rst
index 33ad8eefd8f2..134f67363c3b 100644
--- a/docs/logging-usage.rst
+++ b/docs/logging-usage.rst
@@ -32,23 +32,23 @@ Authentication and Configuration
 Writing log entries
 -------------------
 
-Write a simple text entry to a log.
+Write a simple text entry to a logger.
 
 .. doctest::
 
    >>> from gcloud import logging
    >>> client = logging.Client()
-   >>> log = client.log('log_name')
-   >>> log.text("A simple entry")  # API call
+   >>> logger = client.logger('log_name')
+   >>> logger.text("A simple entry")  # API call
 
-Write a dictionary entry to a log.
+Write a dictionary entry to a logger.
 
 .. doctest::
 
    >>> from gcloud import logging
    >>> client = logging.Client()
-   >>> log = client.log('log_name')
-   >>> log.struct(
+   >>> logger = client.logger('log_name')
+   >>> logger.struct(
    ...     message="My second entry",
    ...     weather="partly cloudy")  # API call
 
@@ -113,15 +113,15 @@ Retrieve entities in batches of 10, iterating until done.
    ...         break
 
 
-Delete all entries for a log
-----------------------------
+Delete all entries for a logger
+-------------------------------
 
 .. doctest::
 
    >>> from gcloud import logging
    >>> client = logging.Client()
-   >>> log = client.log('log_name')
-   >>> log.delete()  # API call
+   >>> logger = client.logger('log_name')
+   >>> logger.delete()  # API call
 
 
 Manage log metrics

From 93a7e3127f017b89aa2003995ed9167603cb2ae3 Mon Sep 17 00:00:00 2001
From: Tres Seaver <tseaver@palladion.com>
Date: Thu, 18 Feb 2016 19:52:54 -0500
Subject: [PATCH 15/19] Rename 'Logger.text' -> 'log_text', 'Logger.struct' ->
 'log_struct'.

Addresses:
https://github.com/GoogleCloudPlatform/gcloud-python/pull/1488#discussion_r53380427
https://github.com/GoogleCloudPlatform/gcloud-python/pull/1488#discussion_r53380514
---
 docs/logging-usage.rst | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/docs/logging-usage.rst b/docs/logging-usage.rst
index 134f67363c3b..ae87ea391a67 100644
--- a/docs/logging-usage.rst
+++ b/docs/logging-usage.rst
@@ -39,7 +39,7 @@ Write a simple text entry to a logger.
    >>> from gcloud import logging
    >>> client = logging.Client()
    >>> logger = client.logger('log_name')
-   >>> logger.text("A simple entry")  # API call
+   >>> logger.log_text("A simple entry")  # API call
 
 Write a dictionary entry to a logger.
 
@@ -48,7 +48,7 @@ Write a dictionary entry to a logger.
    >>> from gcloud import logging
    >>> client = logging.Client()
    >>> logger = client.logger('log_name')
-   >>> logger.struct(
+   >>> logger.log_struct(
    ...     message="My second entry",
    ...     weather="partly cloudy")  # API call
 

From 4a3bdae1aeb69137280abc58a90b53b3dfa68d9a Mon Sep 17 00:00:00 2001
From: Tres Seaver <tseaver@palladion.com>
Date: Thu, 18 Feb 2016 19:56:25 -0500
Subject: [PATCH 16/19] Use constant to hide string literal for 'timestamp
 descending'.

Addresses:

https://github.com/GoogleCloudPlatform/gcloud-python/pull/1488#discussion_r53403884
---
 docs/logging-usage.rst | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/docs/logging-usage.rst b/docs/logging-usage.rst
index ae87ea391a67..b0cf83c91a20 100644
--- a/docs/logging-usage.rst
+++ b/docs/logging-usage.rst
@@ -96,7 +96,7 @@ Sort entries in descending timestamp order.
 
    >>> from gcloud import logging
    >>> client = logging.Client()
-   >>> entries, token = client.list_entries(order_by='timestamp desc')  # API call
+   >>> entries, token = client.list_entries(order_by=Client.DESCENDING)  # API call
 
 Retrieve entities in batches of 10, iterating until done.
 

From 2e0169a682ce6b5ee0f8a0756323c12cf945c552 Mon Sep 17 00:00:00 2001
From: Tres Seaver <tseaver@palladion.com>
Date: Tue, 1 Mar 2016 15:54:11 -0500
Subject: [PATCH 17/19] Locate constant at 'gcloud.logging' scope.

Addresses:
https://github.com/GoogleCloudPlatform/gcloud-python/pull/1488#discussion_r53570777
---
 docs/logging-usage.rst | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/docs/logging-usage.rst b/docs/logging-usage.rst
index b0cf83c91a20..471b39f36b5c 100644
--- a/docs/logging-usage.rst
+++ b/docs/logging-usage.rst
@@ -96,7 +96,7 @@ Sort entries in descending timestamp order.
 
    >>> from gcloud import logging
    >>> client = logging.Client()
-   >>> entries, token = client.list_entries(order_by=Client.DESCENDING)  # API call
+   >>> entries, token = client.list_entries(order_by=logging.DESCENDING)  # API call
 
 Retrieve entities in batches of 10, iterating until done.
 

From d973ca7ab50393eaf5de2c6751748050fef7bc3a Mon Sep 17 00:00:00 2001
From: Tres Seaver <tseaver@palladion.com>
Date: Tue, 1 Mar 2016 15:56:30 -0500
Subject: [PATCH 18/19] Pass overlooked 'token' back for subsequent pages.

Addresses:
https://github.com/GoogleCloudPlatform/gcloud-python/pull/1488#discussion_r53570788
---
 docs/logging-usage.rst | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/docs/logging-usage.rst b/docs/logging-usage.rst
index 471b39f36b5c..ef40a860a1c6 100644
--- a/docs/logging-usage.rst
+++ b/docs/logging-usage.rst
@@ -107,7 +107,7 @@ Retrieve entities in batches of 10, iterating until done.
    >>> retrieved = []
    >>> token = None
    >>> while True:
-   ...     entries, token = client.list_entries(page_size=10)  # API call
+   ...     entries, token = client.list_entries(page_size=10, page_token=token)  # API call
    ...     retrieved.extend(entries)
    ...     if token is None:
    ...         break

From 559e7cd476471b0d12b9261dead984dcf825eb62 Mon Sep 17 00:00:00 2001
From: Tres Seaver <tseaver@palladion.com>
Date: Tue, 1 Mar 2016 15:59:09 -0500
Subject: [PATCH 19/19] Rename 'Logger.delete' -> 'delete_entries' to indicate
 semantics.

Addresses:
https://github.com/GoogleCloudPlatform/gcloud-python/pull/1488#discussion_r53570798
---
 docs/logging-usage.rst | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/docs/logging-usage.rst b/docs/logging-usage.rst
index ef40a860a1c6..3f027c00d38d 100644
--- a/docs/logging-usage.rst
+++ b/docs/logging-usage.rst
@@ -121,7 +121,7 @@ Delete all entries for a logger
    >>> from gcloud import logging
    >>> client = logging.Client()
    >>> logger = client.logger('log_name')
-   >>> logger.delete()  # API call
+   >>> logger.delete_entries()  # API call
 
 
 Manage log metrics