docs: Documentation update for OpenTelemetry and tracing (#1517)

* docs: Documentation update for OpenTelemetry and tracing * fix lint * 🦉 Updates from OwlBot post-processor See https://github.com/googleapis/repo-automation-bots/blob/main/packages/owl-bot/README.md * Update documentation * 🦉 Updates from OwlBot post-processor See https://github.com/googleapis/repo-automation-bots/blob/main/packages/owl-bot/README.md * fix comments * 🦉 Updates from OwlBot post-processor See https://github.com/googleapis/repo-automation-bots/blob/main/packages/owl-bot/README.md --------- Co-authored-by: Owl Bot <gcf-owl-bot[bot]@users.noreply.github.com>
googleapis · Jul 15, 2024 · a8c950d · a8c950d
1 parent 5b57cdb
commit a8c950d
Show file tree

Hide file tree

Showing 7 changed files with 112 additions and 86 deletions.
diff --git a/.readme-partials.yml b/.readme-partials.yml
@@ -80,6 +80,19 @@ body: |-
   If you already have a "raw" Http `request` object you can assign it to `entry.metadata.httpRequest` directly. More information about
   how the `request` is interpreted as raw can be found in the [code](https://github.com/googleapis/nodejs-logging/blob/15849160116a814ab71113138cb211c2e0c2d4b4/src/entry.ts#L224-L238).
 
+  ## Automatic Trace/Span ID Extraction
+  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`.
+
+  If not provided explicitly in a LogEntry, the Cloud Logging library automatically populates `trace`, `span_id`, and `trace_sampled` fields from detected OpenTelemetry span contexts, or from HTTP request headers.
+
+  ### Extracting 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 automatically populated from the active span. More information about OpenTelemetry can be found [here](https://opentelemetry.io/docs/languages/js/).
+
+  ### Extracting Trace/Span ID from HTTP Headers
+  If tracing fields are not provided explicitly and no OpenTelemetry context is detected, the `trace` / `span_id` fields are extracted automatically from HTTP headers. 
+  Trace information 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.
+
   ## Error handling with logs written or deleted asynchronously
 
   The `Log` class provide users the ability to write and delete logs asynchronously. However, there are cases when log entries

diff --git a/README.md b/README.md
@@ -170,6 +170,19 @@ how to populate the Http request metadata for log entries.
 If you already have a "raw" Http `request` object you can assign it to `entry.metadata.httpRequest` directly. More information about
 how the `request` is interpreted as raw can be found in the [code](https://github.com/googleapis/nodejs-logging/blob/15849160116a814ab71113138cb211c2e0c2d4b4/src/entry.ts#L224-L238).
 
+## Automatic Trace/Span ID Extraction
+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`.
+
+If not provided explicitly in a LogEntry, the Cloud Logging library automatically populates `trace`, `span_id`, and `trace_sampled` fields from detected OpenTelemetry span contexts, or from HTTP request headers.
+
+### Extracting 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 automatically populated from the active span. More information about OpenTelemetry can be found [here](https://opentelemetry.io/docs/languages/js/).
+
+### Extracting Trace/Span ID from HTTP Headers
+If tracing fields are not provided explicitly and no OpenTelemetry context is detected, the `trace` / `span_id` fields are extracted automatically from HTTP headers. 
+Trace information 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.
+
 ## Error handling with logs written or deleted asynchronously
 
 The `Log` class provide users the ability to write and delete logs asynchronously. However, there are cases when log entries

diff --git a/src/index.ts b/src/index.ts
@@ -21,7 +21,7 @@ import {callbackifyAll} from '@google-cloud/promisify';
 import arrify = require('arrify');
 import * as extend from 'extend';
 import * as gax from 'google-gax';
-// eslint-disable-next-line node/no-extraneous-import
+// eslint-disable-next-line n/no-extraneous-import
 import {ClientReadableStream, ClientDuplexStream} from '@grpc/grpc-js';
 // eslint-disable-next-line @typescript-eslint/no-var-requires
 const pumpify = require('pumpify');

diff --git a/system-test/fixtures/sample/src/index.js b/system-test/fixtures/sample/src/index.js
@@ -16,7 +16,7 @@
 // ** https://github.com/googleapis/gapic-generator-typescript **
 // ** All changes to this file may be overwritten. **
 
-/* eslint-disable node/no-missing-require, no-unused-vars */
+/* eslint-disable n/no-missing-require, no-unused-vars */
 const logging = require('@google-cloud/logging');
 
 function main() {

diff --git a/test/gapic_config_service_v2_v2.ts b/test/gapic_config_service_v2_v2.ts
@@ -4251,9 +4251,9 @@ describe('v2.ConfigServiceV2Client', () => {
       assert(
         (client.descriptors.page.listBuckets.createStream as SinonStub)
           .getCall(0)
-          .args[2].otherArgs.headers['x-goog-request-params'].includes(
-            expectedHeaderRequestParams
-          )
+          .args[2].otherArgs.headers[
+            'x-goog-request-params'
+          ].includes(expectedHeaderRequestParams)
       );
     });
 
@@ -4299,9 +4299,9 @@ describe('v2.ConfigServiceV2Client', () => {
       assert(
         (client.descriptors.page.listBuckets.createStream as SinonStub)
           .getCall(0)
-          .args[2].otherArgs.headers['x-goog-request-params'].includes(
-            expectedHeaderRequestParams
-          )
+          .args[2].otherArgs.headers[
+            'x-goog-request-params'
+          ].includes(expectedHeaderRequestParams)
       );
     });
 
@@ -4342,9 +4342,9 @@ describe('v2.ConfigServiceV2Client', () => {
       assert(
         (client.descriptors.page.listBuckets.asyncIterate as SinonStub)
           .getCall(0)
-          .args[2].otherArgs.headers['x-goog-request-params'].includes(
-            expectedHeaderRequestParams
-          )
+          .args[2].otherArgs.headers[
+            'x-goog-request-params'
+          ].includes(expectedHeaderRequestParams)
       );
     });
 
@@ -4384,9 +4384,9 @@ describe('v2.ConfigServiceV2Client', () => {
       assert(
         (client.descriptors.page.listBuckets.asyncIterate as SinonStub)
           .getCall(0)
-          .args[2].otherArgs.headers['x-goog-request-params'].includes(
-            expectedHeaderRequestParams
-          )
+          .args[2].otherArgs.headers[
+            'x-goog-request-params'
+          ].includes(expectedHeaderRequestParams)
       );
     });
   });
@@ -4547,9 +4547,9 @@ describe('v2.ConfigServiceV2Client', () => {
       assert(
         (client.descriptors.page.listViews.createStream as SinonStub)
           .getCall(0)
-          .args[2].otherArgs.headers['x-goog-request-params'].includes(
-            expectedHeaderRequestParams
-          )
+          .args[2].otherArgs.headers[
+            'x-goog-request-params'
+          ].includes(expectedHeaderRequestParams)
       );
     });
 
@@ -4595,9 +4595,9 @@ describe('v2.ConfigServiceV2Client', () => {
       assert(
         (client.descriptors.page.listViews.createStream as SinonStub)
           .getCall(0)
-          .args[2].otherArgs.headers['x-goog-request-params'].includes(
-            expectedHeaderRequestParams
-          )
+          .args[2].otherArgs.headers[
+            'x-goog-request-params'
+          ].includes(expectedHeaderRequestParams)
       );
     });
 
@@ -4637,9 +4637,9 @@ describe('v2.ConfigServiceV2Client', () => {
       assert(
         (client.descriptors.page.listViews.asyncIterate as SinonStub)
           .getCall(0)
-          .args[2].otherArgs.headers['x-goog-request-params'].includes(
-            expectedHeaderRequestParams
-          )
+          .args[2].otherArgs.headers[
+            'x-goog-request-params'
+          ].includes(expectedHeaderRequestParams)
       );
     });
 
@@ -4678,9 +4678,9 @@ describe('v2.ConfigServiceV2Client', () => {
       assert(
         (client.descriptors.page.listViews.asyncIterate as SinonStub)
           .getCall(0)
-          .args[2].otherArgs.headers['x-goog-request-params'].includes(
-            expectedHeaderRequestParams
-          )
+          .args[2].otherArgs.headers[
+            'x-goog-request-params'
+          ].includes(expectedHeaderRequestParams)
       );
     });
   });
@@ -4841,9 +4841,9 @@ describe('v2.ConfigServiceV2Client', () => {
       assert(
         (client.descriptors.page.listSinks.createStream as SinonStub)
           .getCall(0)
-          .args[2].otherArgs.headers['x-goog-request-params'].includes(
-            expectedHeaderRequestParams
-          )
+          .args[2].otherArgs.headers[
+            'x-goog-request-params'
+          ].includes(expectedHeaderRequestParams)
       );
     });
 
@@ -4889,9 +4889,9 @@ describe('v2.ConfigServiceV2Client', () => {
       assert(
         (client.descriptors.page.listSinks.createStream as SinonStub)
           .getCall(0)
-          .args[2].otherArgs.headers['x-goog-request-params'].includes(
-            expectedHeaderRequestParams
-          )
+          .args[2].otherArgs.headers[
+            'x-goog-request-params'
+          ].includes(expectedHeaderRequestParams)
       );
     });
 
@@ -4931,9 +4931,9 @@ describe('v2.ConfigServiceV2Client', () => {
       assert(
         (client.descriptors.page.listSinks.asyncIterate as SinonStub)
           .getCall(0)
-          .args[2].otherArgs.headers['x-goog-request-params'].includes(
-            expectedHeaderRequestParams
-          )
+          .args[2].otherArgs.headers[
+            'x-goog-request-params'
+          ].includes(expectedHeaderRequestParams)
       );
     });
 
@@ -4972,9 +4972,9 @@ describe('v2.ConfigServiceV2Client', () => {
       assert(
         (client.descriptors.page.listSinks.asyncIterate as SinonStub)
           .getCall(0)
-          .args[2].otherArgs.headers['x-goog-request-params'].includes(
-            expectedHeaderRequestParams
-          )
+          .args[2].otherArgs.headers[
+            'x-goog-request-params'
+          ].includes(expectedHeaderRequestParams)
       );
     });
   });
@@ -5135,9 +5135,9 @@ describe('v2.ConfigServiceV2Client', () => {
       assert(
         (client.descriptors.page.listLinks.createStream as SinonStub)
           .getCall(0)
-          .args[2].otherArgs.headers['x-goog-request-params'].includes(
-            expectedHeaderRequestParams
-          )
+          .args[2].otherArgs.headers[
+            'x-goog-request-params'
+          ].includes(expectedHeaderRequestParams)
       );
     });
 
@@ -5183,9 +5183,9 @@ describe('v2.ConfigServiceV2Client', () => {
       assert(
         (client.descriptors.page.listLinks.createStream as SinonStub)
           .getCall(0)
-          .args[2].otherArgs.headers['x-goog-request-params'].includes(
-            expectedHeaderRequestParams
-          )
+          .args[2].otherArgs.headers[
+            'x-goog-request-params'
+          ].includes(expectedHeaderRequestParams)
       );
     });
 
@@ -5225,9 +5225,9 @@ describe('v2.ConfigServiceV2Client', () => {
       assert(
         (client.descriptors.page.listLinks.asyncIterate as SinonStub)
           .getCall(0)
-          .args[2].otherArgs.headers['x-goog-request-params'].includes(
-            expectedHeaderRequestParams
-          )
+          .args[2].otherArgs.headers[
+            'x-goog-request-params'
+          ].includes(expectedHeaderRequestParams)
       );
     });
 
@@ -5266,9 +5266,9 @@ describe('v2.ConfigServiceV2Client', () => {
       assert(
         (client.descriptors.page.listLinks.asyncIterate as SinonStub)
           .getCall(0)
-          .args[2].otherArgs.headers['x-goog-request-params'].includes(
-            expectedHeaderRequestParams
-          )
+          .args[2].otherArgs.headers[
+            'x-goog-request-params'
+          ].includes(expectedHeaderRequestParams)
       );
     });
   });
@@ -5432,9 +5432,9 @@ describe('v2.ConfigServiceV2Client', () => {
       assert(
         (client.descriptors.page.listExclusions.createStream as SinonStub)
           .getCall(0)
-          .args[2].otherArgs.headers['x-goog-request-params'].includes(
-            expectedHeaderRequestParams
-          )
+          .args[2].otherArgs.headers[
+            'x-goog-request-params'
+          ].includes(expectedHeaderRequestParams)
       );
     });
 
@@ -5478,9 +5478,9 @@ describe('v2.ConfigServiceV2Client', () => {
       assert(
         (client.descriptors.page.listExclusions.createStream as SinonStub)
           .getCall(0)
-          .args[2].otherArgs.headers['x-goog-request-params'].includes(
-            expectedHeaderRequestParams
-          )
+          .args[2].otherArgs.headers[
+            'x-goog-request-params'
+          ].includes(expectedHeaderRequestParams)
       );
     });
 
@@ -5521,9 +5521,9 @@ describe('v2.ConfigServiceV2Client', () => {
       assert(
         (client.descriptors.page.listExclusions.asyncIterate as SinonStub)
           .getCall(0)
-          .args[2].otherArgs.headers['x-goog-request-params'].includes(
-            expectedHeaderRequestParams
-          )
+          .args[2].otherArgs.headers[
+            'x-goog-request-params'
+          ].includes(expectedHeaderRequestParams)
       );
     });
 
@@ -5561,9 +5561,9 @@ describe('v2.ConfigServiceV2Client', () => {
       assert(
         (client.descriptors.page.listExclusions.asyncIterate as SinonStub)
           .getCall(0)
-          .args[2].otherArgs.headers['x-goog-request-params'].includes(
-            expectedHeaderRequestParams
-          )
+          .args[2].otherArgs.headers[
+            'x-goog-request-params'
+          ].includes(expectedHeaderRequestParams)
       );
     });
   });

diff --git a/test/gapic_logging_service_v2_v2.ts b/test/gapic_logging_service_v2_v2.ts
@@ -1206,9 +1206,9 @@ describe('v2.LoggingServiceV2Client', () => {
       assert(
         (client.descriptors.page.listLogs.createStream as SinonStub)
           .getCall(0)
-          .args[2].otherArgs.headers['x-goog-request-params'].includes(
-            expectedHeaderRequestParams
-          )
+          .args[2].otherArgs.headers[
+            'x-goog-request-params'
+          ].includes(expectedHeaderRequestParams)
       );
     });
 
@@ -1254,9 +1254,9 @@ describe('v2.LoggingServiceV2Client', () => {
       assert(
         (client.descriptors.page.listLogs.createStream as SinonStub)
           .getCall(0)
-          .args[2].otherArgs.headers['x-goog-request-params'].includes(
-            expectedHeaderRequestParams
-          )
+          .args[2].otherArgs.headers[
+            'x-goog-request-params'
+          ].includes(expectedHeaderRequestParams)
       );
     });
 
@@ -1292,9 +1292,9 @@ describe('v2.LoggingServiceV2Client', () => {
       assert(
         (client.descriptors.page.listLogs.asyncIterate as SinonStub)
           .getCall(0)
-          .args[2].otherArgs.headers['x-goog-request-params'].includes(
-            expectedHeaderRequestParams
-          )
+          .args[2].otherArgs.headers[
+            'x-goog-request-params'
+          ].includes(expectedHeaderRequestParams)
       );
     });
 
@@ -1333,9 +1333,9 @@ describe('v2.LoggingServiceV2Client', () => {
       assert(
         (client.descriptors.page.listLogs.asyncIterate as SinonStub)
           .getCall(0)
-          .args[2].otherArgs.headers['x-goog-request-params'].includes(
-            expectedHeaderRequestParams
-          )
+          .args[2].otherArgs.headers[
+            'x-goog-request-params'
+          ].includes(expectedHeaderRequestParams)
       );
     });
   });