diff --git a/docs/auto-trace-span-extraction.rst b/docs/auto-trace-span-extraction.rst index 72cd5df96..843ebb8ec 100644 --- a/docs/auto-trace-span-extraction.rst +++ b/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 `_ -`trace`, `span_id`, and`trace_sampled` via OpenTelemetry integration, or extracting header information from an HTTP request. +.. note:: + All `LogEntry fields`_ populated :ref:`manually` 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 `. +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 `. Trace information is automatically populated from either the `W3C Traceparent `_ or `X-Cloud-Trace-Context `_ 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 index c6eb4574a..8a016b8e5 100644 --- a/docs/std-lib-integration.rst +++ b/docs/std-lib-integration.rst @@ -111,23 +111,26 @@ The following fields are currently supported: - :ref:`json_fields` .. note:: - | More information about `trace`, `span_id`, `trace_sampled` can be found :doc:`here `. + | More information about `trace`, `span_id`, and `trace_sampled` can be found :doc:`here `. | `http_request` requires a :doc:`supported Python web framework `. + Manual Metadata Using the `extra` Argument -------------------------------------------- +.. _Manual-Metadata: + The Python :mod:`logging` standard library accepts `an "extra" argument `_ 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 `_. +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 `_ +All of the `LogEntry fields`_ that can be :ref:`autodetected` can also be set manually through the `extra` argument. Fields sent explicitly through the `extra` argument override any :ref:`automatically detected` fields. @@ -154,3 +157,5 @@ You can use both transport options over :doc:`gRPC or 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 \ No newline at end of file