docs: Documentation update for OpenTelemetry (#915)

* docs: Documentation update for OpenTelemetry * updated documentation * Update docs/auto-trace-span-extraction.rst Co-authored-by: Aaron Abbott <[email protected]> --------- Co-authored-by: Aaron Abbott <[email protected]>
googleapis · Jul 15, 2024 · 2a0539a · 2a0539a
1 parent 6266f39
commit 2a0539a
Show file tree

Hide file tree

Showing 3 changed files with 41 additions and 7 deletions.
diff --git a/docs/auto-trace-span-extraction.rst b/docs/auto-trace-span-extraction.rst
@@ -0,0 +1,27 @@
+Automatic Trace/Span ID Extraction
+==================================
+
+.. note::
+    All `LogEntry fields`_ populated :ref:`manually<Manual-Metadata>` will override those populated via methods referred to in this
+    section.
+
+The Google Cloud Logging library can automatically populate `LogEntry fields`_
+`trace`, `span_id`, and `trace_sampled` via OpenTelemetry integration, or extracting header information from an HTTP request.
+
+OpenTelemetry Integration
+-------------------------
+
+If you have the OpenTelemetry SDK package installed and are logging from within an active OpenTelemetry span, that log entry will automatically
+have the `trace`, `span_id`, and `trace_sampled` fields populated from that span. More information about OpenTelemetry can be found 
+`here <https://opentelemetry.io/docs/languages/python/>`_.
+
+HTTP headers
+------------
+
+Another possible method of automatic `trace` / `span_id` is via extraction from HTTP headers. 
+This is prioritized after OpenTelemetry and requires a :doc:`supported Python web framework </web-framework-integration>`.
+Trace information is automatically populated from either the `W3C Traceparent <https://www.w3.org/TR/trace-context>`_ 
+or `X-Cloud-Trace-Context <https://cloud.google.com/trace/docs/trace-context#legacy-http-header>`_ headers.
+Populating trace information this way also automatically populates the `http_request` field in the `LogEntry` as well.
+
+.. _LogEntry fields: https://cloud.google.com/logging/docs/reference/v2/rest/v2/LogEntry
diff --git a/docs/std-lib-integration.rst b/docs/std-lib-integration.rst
@@ -102,31 +102,35 @@ The Google Cloud Logging library attempts to detect and attach additional
 The following fields are currently supported:
 
 - labels
-- trace*
-- span_id*
-- trace_sampled*
-- http_request*
+- trace
+- span_id
+- trace_sampled
+- http_request
 - source_location
 - resource
 - :ref:`json_fields<JSON>`
 
 .. note::
-    Fields marked with "*" require a :doc:`supported Python web framework </web-framework-integration>`.
+    | More information about `trace`, `span_id`, and `trace_sampled` can be found :doc:`here </auto-trace-span-extraction>`.
+    | `http_request` requires a :doc:`supported Python web framework </web-framework-integration>`.
+
 
 Manual Metadata Using the `extra` Argument
 --------------------------------------------
 
+.. _Manual-Metadata:
+
 The Python :mod:`logging` standard library accepts `an "extra" argument <https://docs.python.org/3/library/logging.html#logging.Logger.debug>`_ when
 writing logs. You can use this argument to populate LogRecord objects with user-defined
 key-value pairs. Google Cloud Logging uses the `extra` field as a way to pass in additional
-metadata to populate `LogEntry fields <https://cloud.google.com/logging/docs/reference/v2/rest/v2/LogEntry>`_.
+metadata to populate `LogEntry fields`_.
 
 .. literalinclude:: ../samples/snippets/usage_guide.py
     :start-after: [START logging_extras]
     :end-before: [END logging_extras]
     :dedent: 4
 
-All of the `LogEntry fields <https://cloud.google.com/logging/docs/reference/v2/rest/v2/LogEntry>`_
+All of the `LogEntry fields`_
 that can be :ref:`autodetected<Autodetection>` can also be set manually through the `extra` argument. Fields sent explicitly through the `extra`
 argument override any :ref:`automatically detected<Autodetection>` fields.
 
@@ -153,3 +157,5 @@ You can use both transport options over :doc:`gRPC or HTTP</grpc-vs-http>`.
 .. note::
     :class:`~google.cloud.logging_v2.handlers.structured_log.StructuredLogHandler`
     prints logs as formatted JSON to standard output, and does not use a Transport class.
+
+.. _LogEntry fields: https://cloud.google.com/logging/docs/reference/v2/rest/v2/LogEntry
diff --git a/docs/usage.rst b/docs/usage.rst
@@ -4,6 +4,7 @@ Usage Guide
    :maxdepth: 2
 
    std-lib-integration
+   auto-trace-span-extraction
    web-framework-integration
    direct-lib-usage
    grpc-vs-http