Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

docs: Documentation update for OpenTelemetry #915

Merged
merged 4 commits into from
Jul 15, 2024
Merged

docs: Documentation update for OpenTelemetry #915

Show file tree
Hide file tree
Changes from 1 commit
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
ad26c64
docs: Documentation update for OpenTelemetry
gkevinzheng Jul 10, 2024
9816fbc
updated documentation
gkevinzheng Jul 11, 2024
1a4e06e
Update docs/auto-trace-span-extraction.rst
gkevinzheng Jul 11, 2024
11e42e0
Merge branch 'main' into otel-docs
gkevinzheng Jul 15, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
20 changes: 20 additions & 0 deletions docs/auto-trace-span-extraction.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,20 @@
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.
Copy link
Contributor

@cindy-peng cindy-peng Jul 10, 2024 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Somehow andtrace_sampled is not rendered correctly in the screenshot.

Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Looks like there's a space needed between "and" and "trace_sampled".


OpenTelemetry Integration
-------------------------

If you have the OpenTelemetry SDK package installed and are logging from within an active OpenTelemetry span, that log entry will automatically
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

nit the SDK is not technically necessary here. Does this suggestion make sense to you? I think it's a little more precise

Suggested change
If you have the OpenTelemetry SDK package installed and are logging from within an active OpenTelemetry span, that log entry will automatically
If you are using OpenTelemetry and there is an active span in the OpenTelemetry Context, 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
gkevinzheng marked this conversation as resolved.
Show resolved Hide resolved
`here <https://opentelemetry.io/docs/languages/python/>`_.

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>`.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Do we want to mention that this is prioritized after OpenTelemetry?

Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think that's probably a good idea.

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.
11 changes: 6 additions & 5 deletions docs/std-lib-integration.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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<JSON>`

.. note::
Fields marked with "*" require a :doc:`supported Python web framework </web-framework-integration>`.
| More information about `trace`, `span_id`, `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
--------------------------------------------
Expand Down
1 change: 1 addition & 0 deletions docs/usage.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,6 +4,7 @@ Usage Guide
:maxdepth: 2

std-lib-integration
auto-trace-span-extraction
web-framework-integration
direct-lib-usage
grpc-vs-http
Expand Down