From ad26c643d6be834b886c32a55c18e4196c8f116a Mon Sep 17 00:00:00 2001 From: Kevin Zheng Date: Wed, 10 Jul 2024 18:53:53 +0000 Subject: [PATCH 1/3] docs: Documentation update for OpenTelemetry --- docs/auto-trace-span-extraction.rst | 20 ++++++++++++++++++++ docs/std-lib-integration.rst | 11 ++++++----- docs/usage.rst | 1 + 3 files changed, 27 insertions(+), 5 deletions(-) create mode 100644 docs/auto-trace-span-extraction.rst diff --git a/docs/auto-trace-span-extraction.rst b/docs/auto-trace-span-extraction.rst new file mode 100644 index 000000000..72cd5df96 --- /dev/null +++ b/docs/auto-trace-span-extraction.rst @@ -0,0 +1,20 @@ +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. + +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 with metadata 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 feature 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. diff --git a/docs/std-lib-integration.rst b/docs/std-lib-integration.rst index be43231fd..c6eb4574a 100644 --- a/docs/std-lib-integration.rst +++ b/docs/std-lib-integration.rst @@ -102,16 +102,17 @@ 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`, `trace_sampled` can be found :doc:`here `. + | `http_request` requires a :doc:`supported Python web framework `. Manual Metadata Using the `extra` Argument -------------------------------------------- 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 From 9816fbc92d9eea4b553fc247110fbf42370d7477 Mon Sep 17 00:00:00 2001 From: Kevin Zheng Date: Thu, 11 Jul 2024 15:10:28 +0000 Subject: [PATCH 2/3] updated documentation --- docs/auto-trace-span-extraction.rst | 13 ++++++++++--- docs/std-lib-integration.rst | 11 ++++++++--- 2 files changed, 18 insertions(+), 6 deletions(-) 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 From 1a4e06e005e343991dd5d0f11c98864a45fdc748 Mon Sep 17 00:00:00 2001 From: Kevin Zheng <147537668+gkevinzheng@users.noreply.github.com> Date: Thu, 11 Jul 2024 16:43:29 -0400 Subject: [PATCH 3/3] Update docs/auto-trace-span-extraction.rst Co-authored-by: Aaron Abbott --- docs/auto-trace-span-extraction.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/auto-trace-span-extraction.rst b/docs/auto-trace-span-extraction.rst index 843ebb8ec..1eb21fb78 100644 --- a/docs/auto-trace-span-extraction.rst +++ b/docs/auto-trace-span-extraction.rst @@ -12,7 +12,7 @@ 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 with metadata from that span. More information about OpenTelemetry can be found +have the `trace`, `span_id`, and `trace_sampled` fields populated from that span. More information about OpenTelemetry can be found `here `_. HTTP headers