Skip to content
Permalink
Browse files
docs: fix usage guide (#140)
  • Loading branch information
daniel-sanche committed Dec 17, 2020
1 parent ba94afb commit 1ca398103fdfefb5576d6ef2ba20cfa4bd4ab252
Showing with 192 additions and 152 deletions.
  1. +29 −43 docs/usage.rst
  2. +4 −1 samples/snippets/requirements.txt
  3. +69 −108 docs/snippets.py → samples/snippets/usage_guide.py
  4. +90 −0 samples/snippets/usage_guide_test.py
@@ -8,21 +8,21 @@ To write log entries, first create a
:class:`~google.cloud.logging.logger.Logger`, passing the "log name" with
which to associate the entries:

.. literalinclude:: snippets.py
.. literalinclude:: ../samples/snippets/usage_guide.py
:start-after: [START logger_create]
:end-before: [END logger_create]
:dedent: 4

Write a simple text entry to the logger.

.. literalinclude:: snippets.py
.. literalinclude:: ../samples/snippets/usage_guide.py
:start-after: [START logger_log_text]
:end-before: [END logger_log_text]
:dedent: 4

Write a dictionary entry to the logger.

.. literalinclude:: snippets.py
.. literalinclude:: ../samples/snippets/usage_guide.py
:start-after: [START logger_log_struct]
:end-before: [END logger_log_struct]
:dedent: 4
@@ -34,7 +34,7 @@ Supported Resource values are listed at `Monitored Resource Types`_
.. _Monitored Resource Types: https://cloud.google.com/logging/docs/api/v2/resource-list


.. literalinclude:: snippets.py
.. literalinclude:: ../samples/snippets/usage_guide.py
:start-after: [START logger_log_resource_text]
:end-before: [END logger_log_resource_text]
:dedent: 4
@@ -44,7 +44,7 @@ Retrieving log entries

Fetch entries for the default project.

.. literalinclude:: snippets.py
.. literalinclude:: ../samples/snippets/usage_guide.py
:start-after: [START client_list_entries_default]
:end-before: [END client_list_entries_default]
:dedent: 4
@@ -59,41 +59,27 @@ will be instances of one of the following classes:
- :class:`~google.cloud.logging.entries.StructEntry`
- :class:`~google.cloud.logging.entries.ProtobufEntry`

Fetch entries across multiple projects.

.. literalinclude:: snippets.py
:start-after: [START client_list_entries_multi_project]
:end-before: [END client_list_entries_multi_project]
:dedent: 4

Filter entries retrieved using the `Advanced Logs Filters`_ syntax

.. _Advanced Logs Filters: https://cloud.google.com/logging/docs/view/advanced_filters

Fetch entries for the default project.

.. literalinclude:: snippets.py
.. literalinclude:: ../samples/snippets/usage_guide.py
:start-after: [START client_list_entries_filter]
:end-before: [END client_list_entries_filter]
:dedent: 4

Sort entries in descending timestamp order.

.. literalinclude:: snippets.py
.. literalinclude:: ../samples/snippets/usage_guide.py
:start-after: [START client_list_entries_order_by]
:end-before: [END client_list_entries_order_by]
:dedent: 4

Retrieve entries in batches of 10, iterating until done.

.. literalinclude:: snippets.py
:start-after: [START client_list_entries_paged]
:end-before: [END client_list_entries_paged]
:dedent: 4

Retrieve entries for a single logger, sorting in descending timestamp order:

.. literalinclude:: snippets.py
.. literalinclude:: ../samples/snippets/usage_guide.py
:start-after: [START logger_list_entries]
:end-before: [END logger_list_entries]
:dedent: 4
@@ -102,7 +88,7 @@ Retrieve entries for a single logger, sorting in descending timestamp order:
Delete all entries for a logger
-------------------------------

.. literalinclude:: snippets.py
.. literalinclude:: ../samples/snippets/usage_guide.py
:start-after: [START logger_delete]
:end-before: [END logger_delete]
:dedent: 8
@@ -116,35 +102,35 @@ used within Cloud Monitoring to create charts and alerts.

List all metrics for a project:

.. literalinclude:: snippets.py
.. literalinclude:: ../samples/snippets/usage_guide.py
:start-after: [START client_list_metrics]
:end-before: [END client_list_metrics]
:dedent: 4

Create a metric:

.. literalinclude:: snippets.py
.. literalinclude:: ../samples/snippets/usage_guide.py
:start-after: [START metric_create]
:end-before: [END metric_create]
:dedent: 4

Refresh local information about a metric:

.. literalinclude:: snippets.py
.. literalinclude:: ../samples/snippets/usage_guide.py
:start-after: [START metric_reload]
:end-before: [END metric_reload]
:dedent: 4

Update a metric:

.. literalinclude:: snippets.py
.. literalinclude:: ../samples/snippets/usage_guide.py
:start-after: [START metric_update]
:end-before: [END metric_update]
:dedent: 4

Delete a metric:

.. literalinclude:: snippets.py
.. literalinclude:: ../samples/snippets/usage_guide.py
:start-after: [START metric_delete]
:end-before: [END metric_delete]
:dedent: 4
@@ -166,14 +152,14 @@ Make sure that the storage bucket you want to export logs too has

Add ``cloud-logs@google.com`` as the owner of the bucket:

.. literalinclude:: snippets.py
.. literalinclude:: ../samples/snippets/usage_guide.py
:start-after: [START sink_bucket_permissions]
:end-before: [END sink_bucket_permissions]
:dedent: 4

Create a Cloud Storage sink:

.. literalinclude:: snippets.py
.. literalinclude:: ../samples/snippets/usage_guide.py
:start-after: [START sink_storage_create]
:end-before: [END sink_storage_create]
:dedent: 4
@@ -189,14 +175,14 @@ See: `Setting permissions for BigQuery`_

.. _Setting permissions for BigQuery: https://cloud.google.com/logging/docs/export/configure_export_v2#errors_exporting_to_bigquery

.. literalinclude:: snippets.py
.. literalinclude:: ../samples/snippets/usage_guide.py
:start-after: [START sink_dataset_permissions]
:end-before: [END sink_dataset_permissions]
:dedent: 4

Create a BigQuery sink:

.. literalinclude:: snippets.py
.. literalinclude:: ../samples/snippets/usage_guide.py
:start-after: [START sink_bigquery_create]
:end-before: [END sink_bigquery_create]
:dedent: 4
@@ -212,14 +198,14 @@ See: `Setting permissions for Pub/Sub`_

.. _Setting permissions for Pub/Sub: https://cloud.google.com/logging/docs/export/configure_export_v2#errors_exporting_logs_to_cloud_pubsub

.. literalinclude:: snippets.py
.. literalinclude:: ../samples/snippets/usage_guide.py
:start-after: [START sink_topic_permissions]
:end-before: [END sink_topic_permissions]
:dedent: 4

Create a Cloud Pub/Sub sink:

.. literalinclude:: snippets.py
.. literalinclude:: ../samples/snippets/usage_guide.py
:start-after: [START sink_pubsub_create]
:end-before: [END sink_pubsub_create]
:dedent: 4
@@ -229,28 +215,28 @@ Manage Sinks

List all sinks for a project:

.. literalinclude:: snippets.py
.. literalinclude:: ../samples/snippets/usage_guide.py
:start-after: [START client_list_sinks]
:end-before: [END client_list_sinks]
:dedent: 4

Refresh local information about a sink:

.. literalinclude:: snippets.py
.. literalinclude:: ../samples/snippets/usage_guide.py
:start-after: [START sink_reload]
:end-before: [END sink_reload]
:dedent: 4

Update a sink:

.. literalinclude:: snippets.py
.. literalinclude:: ../samples/snippets/usage_guide.py
:start-after: [START sink_update]
:end-before: [END sink_update]
:dedent: 4

Delete a sink:

.. literalinclude:: snippets.py
.. literalinclude:: ../samples/snippets/usage_guide.py
:start-after: [START sink_delete]
:end-before: [END sink_delete]
:dedent: 4
@@ -263,7 +249,7 @@ Cloud Logging. There are different handler options to accomplish this.
To automatically pick the default for your current environment, use
:meth:`~google.cloud.logging.client.Client.get_default_handler`.

.. literalinclude:: snippets.py
.. literalinclude:: ../samples/snippets/usage_guide.py
:start-after: [START create_default_handler]
:end-before: [END create_default_handler]
:dedent: 4
@@ -274,7 +260,7 @@ as well as any other loggers created. A helper method
:meth:`~google.cloud.logging.client.Client.setup_logging` is provided
to configure this automatically.

.. literalinclude:: snippets.py
.. literalinclude:: ../samples/snippets/usage_guide.py
:start-after: [START setup_logging]
:end-before: [END setup_logging]
:dedent: 4
@@ -286,7 +272,7 @@ to configure this automatically.

You can also exclude certain loggers:

.. literalinclude:: snippets.py
.. literalinclude:: ../samples/snippets/usage_guide.py
:start-after: [START setup_logging_excludes]
:end-before: [END setup_logging_excludes]
:dedent: 4
@@ -300,7 +286,7 @@ directly create a
:class:`~google.cloud.logging.handlers.handlers.CloudLoggingHandler` instance
which will write directly to the API.

.. literalinclude:: snippets.py
.. literalinclude:: ../samples/snippets/usage_guide.py
:start-after: [START create_cloud_handler]
:end-before: [END create_cloud_handler]
:dedent: 4
@@ -316,7 +302,7 @@ All logs will go to a single custom log, which defaults to "python". The name
of the Python logger will be included in the structured log entry under the
"python_logger" field. You can change it by providing a name to the handler:

.. literalinclude:: snippets.py
.. literalinclude:: ../samples/snippets/usage_guide.py
:start-after: [START create_named_handler]
:end-before: [END create_named_handler]
:dedent: 4
@@ -1 +1,4 @@
google-cloud-logging==2.0.1
google-cloud-logging==2.0.2
google-cloud-storage==1.35.0
google-cloud-pubsub==2.2.0
google-cloud-bigquery==2.6.1

0 comments on commit 1ca3981

Please sign in to comment.