updated documentation

docs/auto-trace-span-extraction.rst

@@ -1,8 +1,12 @@
 Automatic Trace/Span ID Extraction
 ==================================
 
-The Google Cloud Logging library can automatically populate `LogEntry fields <https://cloud.google.com/logging/docs/reference/v2/rest/v2/LogEntry>`_
-`trace`, `span_id`, and`trace_sampled` via OpenTelemetry integration, or extracting header information from an HTTP request.
+.. 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
 -------------------------
@@ -14,7 +18,10 @@ have the `trace`, `span_id`, and `trace_sampled` fields populated with metadata
 HTTP headers
 ------------
 
-Another possible method of automatic `trace`/ `span_id` is via extraction from HTTP headers. This feature requires a :doc:`supported Python web framework </web-framework-integration>`.
+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

docs/std-lib-integration.rst

@@ -111,23 +111,26 @@ The following fields are currently supported:
 - :ref:`json_fields<JSON>`
 
 .. note::
-    | More information about `trace`, `span_id`, `trace_sampled` can be found :doc:`here </auto-trace-span-extraction>`.
+    | 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.
 
@@ -154,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