diff --git a/docs/auto-trace-span-extraction.rst b/docs/auto-trace-span-extraction.rst new file mode 100644 index 000000000..1eb21fb78 --- /dev/null +++ b/docs/auto-trace-span-extraction.rst @@ -0,0 +1,27 @@ +Automatic Trace/Span ID Extraction +================================== + +.. 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 +------------------------- + +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 `_. + +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 `. +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 be43231fd..8a016b8e5 100644 --- 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` .. note:: - Fields marked with "*" require a :doc:`supported Python web framework `. + | 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. @@ -153,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 diff --git a/docs/usage.rst b/docs/usage.rst index 7541f355b..c28be0c6f 100644 --- 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