Initial sketch of logging API usage docs.

docs/index.rst

@@ -83,6 +83,13 @@
   search-index
   search-document
 
+.. toctree::
+  :maxdepth: 0
+  :hidden:
+  :caption: Cloud Logging
+
+  logging-usage
+
 .. toctree::
   :maxdepth: 0
   :hidden:

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