Update logging samples to fit new style guide and match Node.js samples. [(#435)](GoogleCloudPlatform/python-docs-samples#435)

Author: Jon Wayne Parrott

samples/snippets/README.md

@@ -0,0 +1,36 @@
+# Stackdriver Logging v2 API Samples
+
+`snippets.py` is a simple command-line program to demonstrate writing to a log,
+listing its entries, and deleting it.
+
+`export.py` demonstrates how to interact with sinks which are used to export
+logs to Google Cloud Storage, Cloud Pub/Sub, or BigQuery. The sample uses
+Google Cloud Storage, but can be easily adapted for other outputs.
+
+<!-- auto-doc-link -->
+<!-- end-auto-doc-link -->
+
+## Prerequisites
+
+All samples require a [Google Cloud Project](https://console.cloud.google.com).
+
+To run `export.py`, you will also need a Google Cloud Storage Bucket. 
+
+    gsutil mb gs://[YOUR_PROJECT_ID]
+
+You must add Cloud Logging as an owner to the bucket. To do so, add
+`[email protected]` as an owner to the bucket. See the
+[exportings logs](https://cloud.google.com/logging/docs/export/configure_export#configuring_log_sinks)
+docs for complete details. 
+
+# Running locally
+
+Use the [Cloud SDK](https://cloud.google.com/sdk) to provide authentication:
+
+    gcloud beta auth application-default login
+
+Run the samples:
+
+    python snippets.py -h
+    python export.py -h
+

samples/snippets/export.py

@@ -0,0 +1,144 @@
+#!/usr/bin/env python
+
+# Copyright 2016 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.
+
+import argparse
+
+from gcloud import logging
+
+
+def list_sinks():
+    """Lists all sinks."""
+    logging_client = logging.Client()
+
+    sinks = []
+    token = None
+    while True:
+        new_sinks, token = logging_client.list_sinks(page_token=token)
+        sinks.extend(new_sinks)
+        if token is None:
+            break
+
+    if not sinks:
+        print('No sinks.')
+
+    for sink in sinks:
+        print('{}: {} -> {}'.format(sink.name, sink.filter_, sink.destination))
+
+
+def create_sink(sink_name, destination_bucket, filter_):
+    """Creates a sink to export logs to the given Cloud Storage bucket.
+
+    The filter determines which logs this sink matches and will be exported
+    to the destination. For example a filter of 'severity>=INFO' will send
+    all logs that have a severity of INFO or greater to the destination.
+    See https://cloud.google.com/logging/docs/view/advanced_filters for more
+    filter information.
+    """
+    logging_client = logging.Client()
+
+    # The destination can be a Cloud Storage bucket, a Cloud Pub/Sub topic,
+    # or a BigQuery dataset. In this case, it is a Cloud Storage Bucket.
+    # See https://cloud.google.com/logging/docs/api/tasks/exporting-logs for
+    # information on the destination format.
+    destination = 'storage.googleapis.com/{bucket}'.format(
+        bucket=destination_bucket)
+
+    sink = logging_client.sink(
+        sink_name,
+        filter_,
+        destination)
+
+    if sink.exists():
+        print('Sink {} already exists.'.format(sink.name))
+        return
+
+    sink.create()
+    print('Created sink {}'.format(sink.name))
+
+
+def update_sink(sink_name, filter_):
+    """Changes a sink's filter.
+
+    The filter determines which logs this sink matches and will be exported
+    to the destination. For example a filter of 'severity>=INFO' will send
+    all logs that have a severity of INFO or greater to the destination.
+    See https://cloud.google.com/logging/docs/view/advanced_filters for more
+    filter information.
+    """
+    logging_client = logging.Client()
+    sink = logging_client.sink(sink_name)
+
+    sink.reload()
+
+    sink.filter_ = filter_
+    print('Updated sink {}'.format(sink.name))
+    sink.update()
+    # [END update]
+
+
+def delete_sink(sink_name):
+    """Deletes a sink."""
+    logging_client = logging.Client()
+    sink = logging_client.sink(sink_name)
+
+    sink.delete()
+
+    print('Deleted sink {}'.format(sink.name))
+
+
+if __name__ == '__main__':
+    parser = argparse.ArgumentParser(
+        description=__doc__,
+        formatter_class=argparse.RawDescriptionHelpFormatter
+    )
+
+    subparsers = parser.add_subparsers(dest='command')
+    subparsers.add_parser('list', help=list_sinks.__doc__)
+
+    create_parser = subparsers.add_parser('create', help=list_sinks.__doc__)
+    create_parser.add_argument(
+        'sink_name',
+        help='Name of the log export sink.')
+    create_parser.add_argument(
+        'destination_bucket',
+        help='Cloud Storage bucket where logs will be exported.')
+    create_parser.add_argument(
+        'filter',
+        help='The filter used to match logs.')
+
+    update_parser = subparsers.add_parser('update', help=update_sink.__doc__)
+    update_parser.add_argument(
+        'sink_name',
+        help='Name of the log export sink.')
+    update_parser.add_argument(
+        'filter',
+        help='The filter used to match logs.')
+
+    delete_parser = subparsers.add_parser('delete', help=delete_sink.__doc__)
+    delete_parser.add_argument(
+        'sink_name',
+        help='Name of the log export sink.')
+
+    args = parser.parse_args()
+
+    if args.command == 'list':
+        list_sinks()
+    elif args.command == 'create':
+        create_sink(args.sink_name, args.destination_bucket, args.filter)
+    elif args.command == 'update':
+        update_sink(args.sink_name, args.filter)
+    elif args.command == 'delete':
+        delete_sink(args.sink_name)

samples/snippets/export_test.py

@@ -0,0 +1,71 @@
+# Copyright 2016 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.
+
+import export
+from gcloud import logging
+from gcp.testing import eventually_consistent
+import pytest
+
+TEST_SINK_NAME = 'example_sink'
+TEST_SINK_FILTER = 'severity>=CRITICAL'
+
+
+@pytest.fixture
+def example_sink(cloud_config):
+    client = logging.Client()
+
+    sink = client.sink(
+        TEST_SINK_NAME,
+        TEST_SINK_FILTER,
+        'storage.googleapis.com/{bucket}'.format(
+            bucket=cloud_config.storage_bucket))
+
+    if sink.exists():
+        sink.delete()
+
+    sink.create()
+
+    return sink
+
+
+def test_list(example_sink, capsys):
+    @eventually_consistent.call
+    def _():
+        export.list_sinks()
+        out, _ = capsys.readouterr()
+        assert example_sink.name in out
+
+
+def test_create(cloud_config, capsys):
+    export.create_sink(
+        TEST_SINK_NAME,
+        TEST_SINK_FILTER,
+        'storage.googleapis.com/{bucket}'.format(
+            bucket=cloud_config.storage_bucket))
+
+    out, _ = capsys.readouterr()
+    assert TEST_SINK_NAME in out
+
+
+def test_update(example_sink, capsys):
+    updated_filter = 'severity>=INFO'
+    export.update_sink(TEST_SINK_NAME, updated_filter)
+
+    example_sink.reload()
+    assert example_sink.filter_ == updated_filter
+
+
+def test_delete(example_sink, capsys):
+    export.delete_sink(TEST_SINK_NAME)
+    assert not example_sink.exists()

samples/snippets/requirements.txt

@@ -0,0 +1 @@
+gcloud==0.17.0

samples/snippets/snippets.py

@@ -0,0 +1,106 @@
+#!/usr/bin/env python
+
+# Copyright 2016 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.
+
+"""This application demonstrates how to perform basic operations on logs and
+log entries with Stackdriver Logging.
+
+For more information, see the README.md under /logging and the
+documentation at https://cloud.google.com/logging/docs.
+"""
+
+import argparse
+
+from gcloud import logging
+
+
+def write_entry(logger_name):
+    """Writes log entries to the given logger."""
+    logging_client = logging.Client()
+
+    # This log can be found in the Cloud Logging console under 'Custom Logs'.
+    logger = logging_client.logger(logger_name)
+
+    # Make a simple text log
+    logger.log_text('Hello, world!')
+
+    # Simple text log with severity.
+    logger.log_text('Goodbye, world!', severity='ERROR')
+
+    # Struct log. The struct can be any JSON-serializable dictionary.
+    logger.log_struct({
+        'name': 'King Arthur',
+        'quest': 'Find the Holy Grail',
+        'favorite_color': 'Blue'
+    })
+
+    print('Wrote logs to {}.'.format(logger.name))
+
+
+def list_entries(logger_name):
+    """Lists the most recent entries for a given logger."""
+    logging_client = logging.Client()
+    logger = logging_client.logger(logger_name)
+
+    print('Listing entries for logger {}:'.format(logger.name))
+
+    entries = []
+    page_token = None
+
+    while True:
+        new_entries, page_token = logger.list_entries(page_token=page_token)
+        entries.extend(new_entries)
+        if not page_token:
+            break
+
+    for entry in entries:
+        timestamp = entry.timestamp.isoformat()
+        print('* {}: {}'.format
+              (timestamp, entry.payload))
+
+
+def delete_logger(logger_name):
+    """Deletes a logger and all its entries.
+
+    Note that a deletion can take several minutes to take effect.
+    """
+    logging_client = logging.Client()
+    logger = logging_client.logger(logger_name)
+
+    logger.delete()
+
+    print('Deleted all logging entries for {}'.format(logger.name))
+
+
+if __name__ == '__main__':
+    parser = argparse.ArgumentParser(
+        description=__doc__,
+        formatter_class=argparse.RawDescriptionHelpFormatter
+    )
+    parser.add_argument(
+        'logger_name', help='Logger name', default='example_log')
+    subparsers = parser.add_subparsers(dest='command')
+    subparsers.add_parser('list', help=list_entries.__doc__)
+    subparsers.add_parser('write', help=write_entry.__doc__)
+    subparsers.add_parser('delete', help=delete_logger.__doc__)
+
+    args = parser.parse_args()
+
+    if args.command == 'list':
+        list_entries(args.logger_name)
+    elif args.command == 'write':
+        write_entry(args.logger_name)
+    elif args.command == 'delete':
+        delete_logger(args.logger_name)