Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We鈥檒l occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

docs: fix usage guide #140

Merged
merged 5 commits into from Dec 17, 2020
Merged

docs: fix usage guide #140

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
3312b65
moved usage guide snippets with other samples
daniel-sanche Dec 16, 2020
3fe2bae
got tests to pass
daniel-sanche Dec 17, 2020
0121813
updated usage guide
daniel-sanche Dec 17, 2020
a1c86db
removed caps
daniel-sanche Dec 17, 2020
23f1e84
fixed lint issues
daniel-sanche Dec 17, 2020
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Jump to
Jump to file
Failed to load files.
Diff view
Diff view
72 changes: 29 additions & 43 deletions docs/usage.rst
View file
Open in desktop
Expand Up @@ -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
Expand All @@ -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
Expand All @@ -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
Expand All @@ -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
Expand All @@ -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
Expand All @@ -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
Expand All @@ -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
Expand All @@ -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
Expand All @@ -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
Expand All @@ -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
Expand All @@ -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
Expand All @@ -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
Expand All @@ -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
Expand All @@ -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
Expand All @@ -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
Expand Down
5 changes: 4 additions & 1 deletion samples/snippets/requirements.txt
View file
Open in desktop
@@ -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