From 8848619b474e54b1c0afb7bdb4ccb7f2e5506036 Mon Sep 17 00:00:00 2001 From: Cindy Peng <148148319+cindy-peng@users.noreply.github.com> Date: Thu, 11 Jul 2024 17:00:57 -0700 Subject: [PATCH 1/5] docs: Documentation update for OpenTelemetry and tracing --- .readme-partials.yaml | 16 ++++++++++++++++ 1 file changed, 16 insertions(+) diff --git a/.readme-partials.yaml b/.readme-partials.yaml index 588c70420..7ba50520d 100644 --- a/.readme-partials.yaml +++ b/.readme-partials.yaml @@ -227,4 +227,20 @@ custom_content: | google-cloud-logging-servlet-initializer ``` + #### 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`. + + The library provides three methods to update the context: + * Manually set trace/span Id + The trace and span Ids can be set directly using `setTraceId()` and `setSpanId()` methods provided by `Context.Builder`. Alternatively it can also be parsed from the [W3C tracing context header](https://www.w3.org/TR/trace-context) using `loadW3CTraceParentContext()` or from the [Google Cloud tracing context header](https://cloud.google.com/trace/docs/trace-context#legacy-http-header) using `loadCloudTraceContext()`. + Tracing information set using this method will take precedence over other methods below. + + * Auto-population trace/span Id from OpenTelemetry context + 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 from that span. More information about OpenTelemetry can be found [here](https://opentelemetry.io/docs/languages/java/). + + * Using [servlet initializer](https://github.com/googleapis/java-logging-servlet-initializer) to populate trace/span Id from HTTP headers + If trace/span Id is not manually set or auto-populated from OpenTelemetry context, you can use [servlet initializer](https://github.com/googleapis/java-logging-servlet-initializer) package 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 store it using ContextHandler class. Http request and trace/span Id information will be 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. From 9f5b546b98152939c16b11fc73a936f211badcd6 Mon Sep 17 00:00:00 2001 From: Cindy Peng <148148319+cindy-peng@users.noreply.github.com> Date: Thu, 11 Jul 2024 17:05:50 -0700 Subject: [PATCH 2/5] update wording --- .readme-partials.yaml | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/.readme-partials.yaml b/.readme-partials.yaml index 7ba50520d..f0f16fb09 100644 --- a/.readme-partials.yaml +++ b/.readme-partials.yaml @@ -231,15 +231,15 @@ custom_content: | 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`. - The library provides three methods to update the context: + The library provides three methods to update trace/span Id: * Manually set trace/span Id The trace and span Ids can be set directly using `setTraceId()` and `setSpanId()` methods provided by `Context.Builder`. Alternatively it can also be parsed from the [W3C tracing context header](https://www.w3.org/TR/trace-context) using `loadW3CTraceParentContext()` or from the [Google Cloud tracing context header](https://cloud.google.com/trace/docs/trace-context#legacy-http-header) using `loadCloudTraceContext()`. Tracing information set using this method will take precedence over other methods below. - * Auto-population trace/span Id from OpenTelemetry context + * Auto-populate trace/span Id from OpenTelemetry context 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 from that span. More information about OpenTelemetry can be found [here](https://opentelemetry.io/docs/languages/java/). - * Using [servlet initializer](https://github.com/googleapis/java-logging-servlet-initializer) to populate trace/span Id from HTTP headers + * Use [servlet initializer](https://github.com/googleapis/java-logging-servlet-initializer) to populate trace/span Id from HTTP headers If trace/span Id is not manually set or auto-populated from OpenTelemetry context, you can use [servlet initializer](https://github.com/googleapis/java-logging-servlet-initializer) package 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 store it using ContextHandler class. Http request and trace/span Id information will be 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. From 0e4914f8507f77c70a17cde65c1e8087f6e8bef7 Mon Sep 17 00:00:00 2001 From: Cindy Peng <148148319+cindy-peng@users.noreply.github.com> Date: Fri, 12 Jul 2024 10:30:38 -0700 Subject: [PATCH 3/5] Fix comments --- .readme-partials.yaml | 19 ++++++++----------- 1 file changed, 8 insertions(+), 11 deletions(-) diff --git a/.readme-partials.yaml b/.readme-partials.yaml index f0f16fb09..b400fe98f 100644 --- a/.readme-partials.yaml +++ b/.readme-partials.yaml @@ -227,20 +227,17 @@ custom_content: | google-cloud-logging-servlet-initializer ``` - #### Population of log entrys' trace/span Id + #### 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`. + 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`. - The library provides three methods to update trace/span Id: - * Manually set trace/span Id - The trace and span Ids can be set directly using `setTraceId()` and `setSpanId()` methods provided by `Context.Builder`. Alternatively it can also be parsed from the [W3C tracing context header](https://www.w3.org/TR/trace-context) using `loadW3CTraceParentContext()` or from the [Google Cloud tracing context header](https://cloud.google.com/trace/docs/trace-context#legacy-http-header) using `loadCloudTraceContext()`. - Tracing information set using this method will take precedence over other methods below. + 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, 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](https://opentelemetry.io/docs/languages/java/). + * 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 [servlet initializer](https://github.com/googleapis/java-logging-servlet-initializer) to populate trace/span Id from HTTP headers - If trace/span Id is not manually set or auto-populated from OpenTelemetry context, you can use [servlet initializer](https://github.com/googleapis/java-logging-servlet-initializer) package 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 store it using ContextHandler class. Http request and trace/span Id information will be populated from the stored Context class instances. + * 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. From ff6f185362b48ab956d5e5cb7e5d4246b8293346 Mon Sep 17 00:00:00 2001 From: diegomarquezp Date: Fri, 12 Jul 2024 19:39:53 +0000 Subject: [PATCH 4/5] =?UTF-8?q?=F0=9F=A6=89=20Updates=20from=20Hermetic=20?= =?UTF-8?q?Build=20image?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- .repo-metadata.json | 9 +++++---- README.md | 21 +++++++++++++++++---- 2 files changed, 22 insertions(+), 8 deletions(-) diff --git a/.repo-metadata.json b/.repo-metadata.json index 5fd7eb1c6..670c70a55 100644 --- a/.repo-metadata.json +++ b/.repo-metadata.json @@ -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" -} +} \ No newline at end of file diff --git a/README.md b/README.md index 02feda489..bd59f71ea 100644 --- a/README.md +++ b/README.md @@ -19,7 +19,7 @@ If you are using Maven with [BOM][libraries-bom], add this to your pom.xml file: com.google.cloud libraries-bom - 26.40.0 + 26.43.0 pom import @@ -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' ``` @@ -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]`. @@ -329,6 +329,19 @@ If you use Maven, to use the servlet initializer add the following dependency to google-cloud-logging-servlet-initializer ``` +#### 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. @@ -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 From 59b95fce181b68f116789aec077968fbb4190a01 Mon Sep 17 00:00:00 2001 From: Cindy Peng <148148319+cindy-peng@users.noreply.github.com> Date: Fri, 12 Jul 2024 16:55:18 -0700 Subject: [PATCH 5/5] fix comments --- .readme-partials.yaml | 2 +- README.md | 4 ++-- 2 files changed, 3 insertions(+), 3 deletions(-) diff --git a/.readme-partials.yaml b/.readme-partials.yaml index b400fe98f..27cf6092f 100644 --- a/.readme-partials.yaml +++ b/.readme-partials.yaml @@ -227,7 +227,7 @@ custom_content: | google-cloud-logging-servlet-initializer ``` - #### Population of Log Entrys' Trace/Span ID + #### Population of Trace/Span ID fields in a LogEntry 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`. diff --git a/README.md b/README.md index bd59f71ea..d0cddab96 100644 --- a/README.md +++ b/README.md @@ -282,7 +282,7 @@ Cloud Function or GKE. The logger agent installed on these environments can capt The agent can parse structured logs printed to STDOUT and capture additional log metadata beside the log payload. The parsed information includes severity, source location, user labels, http request and tracing information. -#### Auto-population of log entrys' metadata +#### Auto-population of Metadata in a LogEntry LogEntry object metadata information such as [monitored resource](https://cloud.google.com/logging/docs/reference/v2/rest/v2/MonitoredResource), [Http request](https://cloud.google.com/logging/docs/reference/v2/rest/v2/LogEntry#HttpRequest) or @@ -329,7 +329,7 @@ If you use Maven, to use the servlet initializer add the following dependency to google-cloud-logging-servlet-initializer ``` -#### Population of Log Entrys' Trace/Span ID +#### Population of Trace/Span ID fields in a LogEntry 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`.