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

docs: Documentation update for OpenTelemetry and tracing #1657

Merged
merged 5 commits into from
Jul 16, 2024
Merged

docs: Documentation update for OpenTelemetry and tracing #1657

Show file tree
Hide file tree
Changes from 4 commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
8848619
docs: Documentation update for OpenTelemetry and tracing
cindy-peng Jul 12, 2024
9f5b546
update wording
cindy-peng Jul 12, 2024
0e4914f
Fix comments
cindy-peng Jul 12, 2024
ff6f185
🦉 Updates from Hermetic Build image
diegomarquezp Jul 12, 2024
59b95fc
fix comments
cindy-peng Jul 12, 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
13 changes: 13 additions & 0 deletions .readme-partials.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -227,4 +227,17 @@ custom_content: |
<artifactId>google-cloud-logging-servlet-initializer</artifactId>
</dependency>
```
#### Population of Log Entrys' Trace/Span ID
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 title this "Automatic Trace/Span ID Extraction" to be consistent with the language used in other client libraries?

Copy link
Contributor Author

Choose a reason for hiding this comment

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

Hi Kevin, Java-logging is a bit special here. We don't have auto extraction for Http headers unless it's through manual setting or using servlet-initializer.

cindy-peng marked this conversation as resolved.
Show resolved Hide resolved
Cloud Logging libraries use [trace fields within LogEntry](https://cloud.google.com/logging/docs/reference/v2/rest/v2/LogEntry#FIELDS.trace) to capture trace contexts, which enables the [correlation of logs and traces](https://cloud.google.com/logging/docs/view/correlate-logs), and distributed tracing troubleshooting.
These tracing fields, including [trace](https://cloud.google.com/logging/docs/reference/v2/rest/v2/LogEntry#FIELDS.trace), [spanId](https://cloud.google.com/logging/docs/reference/v2/rest/v2/LogEntry#FIELDS.span_id), and [traceSampled](https://cloud.google.com/logging/docs/reference/v2/rest/v2/LogEntry#FIELDS.trace_sampled), define the trace context for a `LogEntry`.

Tracing information set manually takes precedence over information set by the following methods:

* Auto-populate Trace/Span ID from OpenTelemetry Context
If you are using OpenTelemetry and there is an active span in the OpenTelemetry Context, the `trace`, `span_id`, and `trace_sampled` fields in the log entry are populated from the active span. More information about OpenTelemetry can be found [here](https://opentelemetry.io/docs/languages/java/).

* Use the [servlet initializer](https://github.com/googleapis/java-logging-servlet-initializer) to Populate Trace/Span ID from HTTP Headers
If trace/span Id are not manually set or auto-populated from OpenTelemetry context, you can use the [servlet initializer](https://github.com/googleapis/java-logging-servlet-initializer) to populate trace/span Id from HTTP headers.
This package filters all servlet requests to automatically capture the execution context of the servlet request and stores it by using ContextHandler class. Http request and trace/span Id information are populated from the stored Context class instances.
Using this method, trace/span Id can be 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.

9 changes: 5 additions & 4 deletions .repo-metadata.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,17 +2,18 @@
"api_shortname": "logging",
"name_pretty": "Cloud Logging",
"product_documentation": "https://cloud.google.com/logging/docs",
"api_description": "allows you to store, search, analyze, monitor, and alert on log data and events from Google Cloud and Amazon Web Services. Using the BindPlane service, you can also collect this data from over 150 common application components, on-premises systems, and hybrid cloud systems. BindPlane is included with your Google Cloud project at no additional cost.",
"client_documentation": "https://cloud.google.com/java/docs/reference/google-cloud-logging/latest/history",
"issue_tracker": "https://issuetracker.google.com/savedsearches/559764",
"release_level": "stable",
"transport": "grpc",
"language": "java",
"repo": "googleapis/java-logging",
"repo_short": "java-logging",
"distribution_name": "com.google.cloud:google-cloud-logging",
"api_id": "logging.googleapis.com",
"transport": "grpc",
"library_type": "GAPIC_COMBO",
"api_description": "allows you to store, search, analyze, monitor, and alert on log data and events from Google Cloud and Amazon Web Services. Using the BindPlane service, you can also collect this data from over 150 common application components, on-premises systems, and hybrid cloud systems. BindPlane is included with your Google Cloud project at no additional cost.",
"requires_billing": true,
"codeowner_team": "@googleapis/api-logging @googleapis/yoshi-java @googleapis/api-logging-partners",
"issue_tracker": "https://issuetracker.google.com/savedsearches/559764",
"recommended_package": "com.google.cloud.logging"
}
}
21 changes: 17 additions & 4 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -19,7 +19,7 @@ If you are using Maven with [BOM][libraries-bom], add this to your pom.xml file:
<dependency>
<groupId>com.google.cloud</groupId>
<artifactId>libraries-bom</artifactId>
<version>26.40.0</version>
<version>26.43.0</version>
<type>pom</type>
<scope>import</scope>
</dependency>
Expand Down Expand Up @@ -52,7 +52,7 @@ If you are using Maven without the BOM, add this to your dependencies:
If you are using Gradle 5.x or later, add this to your dependencies:

```Groovy
implementation platform('com.google.cloud:libraries-bom:26.42.0')
implementation platform('com.google.cloud:libraries-bom:26.43.0')

implementation 'com.google.cloud:google-cloud-logging'
```
Expand Down Expand Up @@ -82,7 +82,7 @@ The client application making API calls must be granted [authorization scopes][a
### Prerequisites

You will need a [Google Cloud Platform Console][developer-console] project with the Cloud Logging [API enabled][enable-api].

You will need to [enable billing][enable-billing] to use Google Cloud Logging.
[Follow these instructions][create-project] to get your project set up. You will also need to set up the local development environment by
[installing the Google Cloud Command Line Interface][cloud-cli] and running the following commands in command line:
`gcloud auth login` and `gcloud config set project [YOUR PROJECT ID]`.
Expand Down Expand Up @@ -329,6 +329,19 @@ If you use Maven, to use the servlet initializer add the following dependency to
<artifactId>google-cloud-logging-servlet-initializer</artifactId>
</dependency>
```
#### Population of Log Entrys' Trace/Span ID
Cloud Logging libraries use [trace fields within LogEntry](https://cloud.google.com/logging/docs/reference/v2/rest/v2/LogEntry#FIELDS.trace) to capture trace contexts, which enables the [correlation of logs and traces](https://cloud.google.com/logging/docs/view/correlate-logs), and distributed tracing troubleshooting.
These tracing fields, including [trace](https://cloud.google.com/logging/docs/reference/v2/rest/v2/LogEntry#FIELDS.trace), [spanId](https://cloud.google.com/logging/docs/reference/v2/rest/v2/LogEntry#FIELDS.span_id), and [traceSampled](https://cloud.google.com/logging/docs/reference/v2/rest/v2/LogEntry#FIELDS.trace_sampled), define the trace context for a `LogEntry`.

Tracing information set manually takes precedence over information set by the following methods:

* Auto-populate Trace/Span ID from OpenTelemetry Context
If you are using OpenTelemetry and there is an active span in the OpenTelemetry Context, the `trace`, `span_id`, and `trace_sampled` fields in the log entry are populated from the active span. More information about OpenTelemetry can be found [here](https://opentelemetry.io/docs/languages/java/).

* Use the [servlet initializer](https://github.com/googleapis/java-logging-servlet-initializer) to Populate Trace/Span ID from HTTP Headers
If trace/span Id are not manually set or auto-populated from OpenTelemetry context, you can use the [servlet initializer](https://github.com/googleapis/java-logging-servlet-initializer) to populate trace/span Id from HTTP headers.
This package filters all servlet requests to automatically capture the execution context of the servlet request and stores it by using ContextHandler class. Http request and trace/span Id information are populated from the stored Context class instances.
Using this method, trace/span Id can be 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.



Expand Down Expand Up @@ -464,7 +477,7 @@ Java is a registered trademark of Oracle and/or its affiliates.
[contributing]: https://github.com/googleapis/java-logging/blob/main/CONTRIBUTING.md
[code-of-conduct]: https://github.com/googleapis/java-logging/blob/main/CODE_OF_CONDUCT.md#contributor-code-of-conduct
[license]: https://github.com/googleapis/java-logging/blob/main/LICENSE

[enable-billing]: https://cloud.google.com/apis/docs/getting-started#enabling_billing
[enable-api]: https://console.cloud.google.com/flows/enableapi?apiid=logging.googleapis.com
[libraries-bom]: https://github.com/GoogleCloudPlatform/cloud-opensource-java/wiki/The-Google-Cloud-Platform-Libraries-BOM
[shell_img]: https://gstatic.com/cloudssh/images/open-btn.png
Expand Down
Loading