Skip to content

Commit 8bce609

Browse files
committed
added grpc vs http docs
1 parent e822bd0 commit 8bce609

File tree

4 files changed

+28
-9
lines changed

4 files changed

+28
-9
lines changed

docs/direct-lib-usage.rst

+10-8
Original file line numberDiff line numberDiff line change
@@ -15,15 +15,17 @@ Setup
1515
Creating a Client
1616
~~~~~~~~~~~~~~~~~
1717

18+
.. _Creating Client:
19+
1820
Before using the library, you must first set up a :doc:`Client</client>`:
1921

2022
.. literalinclude:: ../samples/snippets/usage_guide.py
2123
:start-after: [START usage_client_setup]
2224
:end-before: [END usage_client_setup]
2325
:dedent: 4
2426

25-
When setting up the :doc:`Client</client>`, you can also disable gRPC to put the library
26-
into HTTP mode:
27+
When setting up the :doc:`Client</client>`, you can also :doc:`disable gRPC</grpc-vs-http>`
28+
to put the library into HTTP mode:
2729

2830
.. literalinclude:: ../samples/snippets/usage_guide.py
2931
:start-after: [START usage_http_client_setup]
@@ -83,24 +85,24 @@ can be set by passing them as keyword arguments:
8385
based on input type. If you want to be more explicit about the type used, you can use the following
8486
Logger methods:
8587

86-
- :meth:`Logger.log_text <google.cloud.logging_v2.logger.Logger.log_text>` creates a :class:`TextEntry <google.cloud.logging_v2.entries.TextEntry>`
87-
- :meth:`Logger.log_struct <google.cloud.logging_v2.logger.Logger.log_struct>` creates a :class:`StructEntry <google.cloud.logging_v2.entries.StructEntry>`
88-
- :meth:`Logger.log_proto <google.cloud.logging_v2.logger.Logger.log_proto>` creates a :class:`ProtobufEntry <google.cloud.logging_v2.entries.ProtobufEntry>`
89-
- :meth:`Logger.log_empty <google.cloud.logging_v2.logger.Logger.log_empty>` creates an empty :class:`LogEntry <google.cloud.logging_v2.entries.LogEntry>`
88+
- :meth:`Logger.log_text <google.cloud.logging_v2.logger.Logger.log_text>` creates a :class:`~google.cloud.logging_v2.entries.TextEntry`
89+
- :meth:`Logger.log_struct <google.cloud.logging_v2.logger.Logger.log_struct>` creates a :class:`~google.cloud.logging_v2.entries.StructEntry`
90+
- :meth:`Logger.log_proto <google.cloud.logging_v2.logger.Logger.log_proto>` creates a :class:`~google.cloud.logging_v2.entries.ProtobufEntry`
91+
- :meth:`Logger.log_empty <google.cloud.logging_v2.logger.Logger.log_empty>` creates an empty :class:`~google.cloud.logging_v2.entries.LogEntry`
9092

9193
Batch Writing Logs
9294
------------------
9395

9496
By default, each log write will take place in an individual network request, which may be inefficient at scale.
95-
Instead, you can use a :class:`Batch <google.cloud.logging_v2.logger.Batch>`:
97+
Instead, you can use a :class:`~google.cloud.logging_v2.logger.Batch`:
9698

9799
.. literalinclude:: ../samples/snippets/usage_guide.py
98100
:start-after: [START logger_log_batch]
99101
:end-before: [END logger_log_batch]
100102
:dedent: 4
101103

102104
In this case, logs are batched together, and only sent out when :func:`batch.commit <google.cloud.logging_v2.logger.Batch.commit>` is called.
103-
To simplify things, you can also use :class:`Batch <google.cloud.logging_v2.logger.Batch>` as a context manager:
105+
To simplify things, you can also use :class:`~google.cloud.logging_v2.logger.Batch` as a context manager:
104106

105107
.. literalinclude:: ../samples/snippets/usage_guide.py
106108
:start-after: [START logger_log_batch_context]

docs/grpc-vs-http.rst

+14
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,14 @@
1+
gRPC vs HTTP
2+
====================
3+
4+
:mod:`google-cloud-logging` supports two different protocols for sending logs over the network:
5+
gRPC and HTTP. Both implementations conform to the same API, and should be
6+
invisible to the end user.
7+
8+
gRPC is enabled by default. You can switch to HTTP mode by either:
9+
10+
- setting the `DISABLE_GRPC` environment variable to `TRUE`
11+
- or, passing `_use_grpc=False` when :ref:`initializing a Client<creating client>`
12+
13+
We recommend using gRPC whenever possible, but you may want to try the HTTP
14+
implementation if you have network issues when using gRPC.

docs/std-lib-integration.rst

+3-1
Original file line numberDiff line numberDiff line change
@@ -37,7 +37,7 @@ as an argument to :meth:`~google.cloud.logging_v2.client.Client.setup_logging`:
3737
There are two supported handler classes to choose from:
3838

3939
- :class:`~google.cloud.logging_v2.handlers.handlers.CloudLoggingHandler`:
40-
- Sends logs directly to Cloud Logging over the network (gRPC or HTTP)
40+
- Sends logs directly to Cloud Logging over the network (:doc:`gRPC or HTTP</grpc-vs-http>`)
4141
- Logs are transmitted according to a :ref:`Transport <Transports>` class
4242
- This is the default handler on most environments, including local development
4343
- :class:`~google.cloud.logging_v2.handlers.structured_log.StructuredLogHandler`:
@@ -139,6 +139,8 @@ transports logs over the network to GCP. There are currently two Transport imple
139139
You can set a Transport class by passing it as an argument when
140140
:ref:`initializing CloudLoggingHandler manually.<manual handler>`
141141

142+
Both options can be used over either :doc:`gRPC or HTTP</grpc-vs-http>`.
143+
142144
.. note::
143145
:class:`~google.cloud.logging_v2.handlers.structured_log.StructuredLogHandler`
144146
prints logs as formatted JSON to standard output, and does not use a Transport class.

docs/usage.rst

+1
Original file line numberDiff line numberDiff line change
@@ -5,4 +5,5 @@ Usage Guide
55

66
std-lib-integration
77
direct-lib-usage
8+
grpc-vs-http
89

0 commit comments

Comments
 (0)