feat: add support for OTel context propagation and harmonized spans

.gitignore

@@ -5,7 +5,7 @@
 /.nyc_output
 /docs/
 /out/
-/build/
+**/build/
 system-test/secrets.js
 system-test/*key.json
 *.lock

README.md

@@ -163,15 +163,16 @@ Samples are in the [`samples/`](https://github.com/googleapis/nodejs-pubsub/tree
 | Listen with exactly-once delivery | [source code](https://github.com/googleapis/nodejs-pubsub/blob/main/samples/listenForMessagesWithExactlyOnceDelivery.js) | [![Open in Cloud Shell][shell_img]](https://console.cloud.google.com/cloudshell/open?git_repo=https://github.com/googleapis/nodejs-pubsub&page=editor&open_in_editor=samples/listenForMessagesWithExactlyOnceDelivery.js,samples/README.md) |
 | Listen For Protobuf Messages | [source code](https://github.com/googleapis/nodejs-pubsub/blob/main/samples/listenForProtobufMessages.js) | [![Open in Cloud Shell][shell_img]](https://console.cloud.google.com/cloudshell/open?git_repo=https://github.com/googleapis/nodejs-pubsub&page=editor&open_in_editor=samples/listenForProtobufMessages.js,samples/README.md) |
 | Listen For Messages With Custom Attributes | [source code](https://github.com/googleapis/nodejs-pubsub/blob/main/samples/listenWithCustomAttributes.js) | [![Open in Cloud Shell][shell_img]](https://console.cloud.google.com/cloudshell/open?git_repo=https://github.com/googleapis/nodejs-pubsub&page=editor&open_in_editor=samples/listenWithCustomAttributes.js,samples/README.md) |
+| Subscribe with OpenTelemetry Tracing | [source code](https://github.com/googleapis/nodejs-pubsub/blob/main/samples/listenWithOpenTelemetryTracing.js) | [![Open in Cloud Shell][shell_img]](https://console.cloud.google.com/cloudshell/open?git_repo=https://github.com/googleapis/nodejs-pubsub&page=editor&open_in_editor=samples/listenWithOpenTelemetryTracing.js,samples/README.md) |
 | Modify Push Configuration | [source code](https://github.com/googleapis/nodejs-pubsub/blob/main/samples/modifyPushConfig.js) | [![Open in Cloud Shell][shell_img]](https://console.cloud.google.com/cloudshell/open?git_repo=https://github.com/googleapis/nodejs-pubsub&page=editor&open_in_editor=samples/modifyPushConfig.js,samples/README.md) |
-| OpenTelemetry Tracing | [source code](https://github.com/googleapis/nodejs-pubsub/blob/main/samples/openTelemetryTracing.js) | [![Open in Cloud Shell][shell_img]](https://console.cloud.google.com/cloudshell/open?git_repo=https://github.com/googleapis/nodejs-pubsub&page=editor&open_in_editor=samples/openTelemetryTracing.js,samples/README.md) |
 | Publish Avro Records to a Topic | [source code](https://github.com/googleapis/nodejs-pubsub/blob/main/samples/publishAvroRecords.js) | [![Open in Cloud Shell][shell_img]](https://console.cloud.google.com/cloudshell/open?git_repo=https://github.com/googleapis/nodejs-pubsub&page=editor&open_in_editor=samples/publishAvroRecords.js,samples/README.md) |
 | Publish Batched Messages | [source code](https://github.com/googleapis/nodejs-pubsub/blob/main/samples/publishBatchedMessages.js) | [![Open in Cloud Shell][shell_img]](https://console.cloud.google.com/cloudshell/open?git_repo=https://github.com/googleapis/nodejs-pubsub&page=editor&open_in_editor=samples/publishBatchedMessages.js,samples/README.md) |
 | Publish Message | [source code](https://github.com/googleapis/nodejs-pubsub/blob/main/samples/publishMessage.js) | [![Open in Cloud Shell][shell_img]](https://console.cloud.google.com/cloudshell/open?git_repo=https://github.com/googleapis/nodejs-pubsub&page=editor&open_in_editor=samples/publishMessage.js,samples/README.md) |
 | Publish Message With Custom Attributes | [source code](https://github.com/googleapis/nodejs-pubsub/blob/main/samples/publishMessageWithCustomAttributes.js) | [![Open in Cloud Shell][shell_img]](https://console.cloud.google.com/cloudshell/open?git_repo=https://github.com/googleapis/nodejs-pubsub&page=editor&open_in_editor=samples/publishMessageWithCustomAttributes.js,samples/README.md) |
 | Publish Ordered Message | [source code](https://github.com/googleapis/nodejs-pubsub/blob/main/samples/publishOrderedMessage.js) | [![Open in Cloud Shell][shell_img]](https://console.cloud.google.com/cloudshell/open?git_repo=https://github.com/googleapis/nodejs-pubsub&page=editor&open_in_editor=samples/publishOrderedMessage.js,samples/README.md) |
 | Publish Protobuf Messages to a Topic | [source code](https://github.com/googleapis/nodejs-pubsub/blob/main/samples/publishProtobufMessages.js) | [![Open in Cloud Shell][shell_img]](https://console.cloud.google.com/cloudshell/open?git_repo=https://github.com/googleapis/nodejs-pubsub&page=editor&open_in_editor=samples/publishProtobufMessages.js,samples/README.md) |
 | Publish with flow control | [source code](https://github.com/googleapis/nodejs-pubsub/blob/main/samples/publishWithFlowControl.js) | [![Open in Cloud Shell][shell_img]](https://console.cloud.google.com/cloudshell/open?git_repo=https://github.com/googleapis/nodejs-pubsub&page=editor&open_in_editor=samples/publishWithFlowControl.js,samples/README.md) |
+| Publish with OpenTelemetry Tracing | [source code](https://github.com/googleapis/nodejs-pubsub/blob/main/samples/publishWithOpenTelemetryTracing.js) | [![Open in Cloud Shell][shell_img]](https://console.cloud.google.com/cloudshell/open?git_repo=https://github.com/googleapis/nodejs-pubsub&page=editor&open_in_editor=samples/publishWithOpenTelemetryTracing.js,samples/README.md) |
 | Publish With Retry Settings | [source code](https://github.com/googleapis/nodejs-pubsub/blob/main/samples/publishWithRetrySettings.js) | [![Open in Cloud Shell][shell_img]](https://console.cloud.google.com/cloudshell/open?git_repo=https://github.com/googleapis/nodejs-pubsub&page=editor&open_in_editor=samples/publishWithRetrySettings.js,samples/README.md) |
 | Quickstart | [source code](https://github.com/googleapis/nodejs-pubsub/blob/main/samples/quickstart.js) | [![Open in Cloud Shell][shell_img]](https://console.cloud.google.com/cloudshell/open?git_repo=https://github.com/googleapis/nodejs-pubsub&page=editor&open_in_editor=samples/quickstart.js,samples/README.md) |
 | Remove Dead Letter Policy | [source code](https://github.com/googleapis/nodejs-pubsub/blob/main/samples/removeDeadLetterPolicy.js) | [![Open in Cloud Shell][shell_img]](https://console.cloud.google.com/cloudshell/open?git_repo=https://github.com/googleapis/nodejs-pubsub&page=editor&open_in_editor=samples/removeDeadLetterPolicy.js,samples/README.md) |

package.json

@@ -51,8 +51,8 @@
     "@google-cloud/precise-date": "^4.0.0",
     "@google-cloud/projectify": "^4.0.0",
     "@google-cloud/promisify": "^4.0.0",
-    "@opentelemetry/api": "~1.8.0",
-    "@opentelemetry/semantic-conventions": "~1.21.0",
+    "@opentelemetry/api": "~1.9.0",
+    "@opentelemetry/semantic-conventions": "~1.25.1",
     "arrify": "^2.0.0",
     "extend": "^3.0.2",
     "google-auth-library": "^9.3.0",
@@ -64,7 +64,8 @@
   },
   "devDependencies": {
     "@grpc/proto-loader": "^0.7.0",
-    "@opentelemetry/tracing": "^0.24.0",
+    "@opentelemetry/core": "^1.17.0",
+    "@opentelemetry/sdk-trace-base": "^1.17.0",
     "@types/duplexify": "^3.6.4",
     "@types/extend": "^3.0.0",
     "@types/lodash.snakecase": "^4.1.6",

samples/README.md

@@ -60,15 +60,16 @@ guides.
   * [Listen with exactly-once delivery](#listen-with-exactly-once-delivery)
   * [Listen For Protobuf Messages](#listen-for-protobuf-messages)
   * [Listen For Messages With Custom Attributes](#listen-for-messages-with-custom-attributes)
+  * [Subscribe with OpenTelemetry Tracing](#subscribe-with-opentelemetry-tracing)
   * [Modify Push Configuration](#modify-push-configuration)
-  * [OpenTelemetry Tracing](#opentelemetry-tracing)
   * [Publish Avro Records to a Topic](#publish-avro-records-to-a-topic)
   * [Publish Batched Messages](#publish-batched-messages)
   * [Publish Message](#publish-message)
   * [Publish Message With Custom Attributes](#publish-message-with-custom-attributes)
   * [Publish Ordered Message](#publish-ordered-message)
   * [Publish Protobuf Messages to a Topic](#publish-protobuf-messages-to-a-topic)
   * [Publish with flow control](#publish-with-flow-control)
+  * [Publish with OpenTelemetry Tracing](#publish-with-opentelemetry-tracing)
   * [Publish With Retry Settings](#publish-with-retry-settings)
   * [Quickstart](#quickstart)
   * [Remove Dead Letter Policy](#remove-dead-letter-policy)
@@ -862,37 +863,37 @@ __Usage:__
 
 
 
-### Modify Push Configuration
+### Subscribe with OpenTelemetry Tracing
 
-Modifies the configuration of an existing push subscription.
+Demonstrates how to enable OpenTelemetry tracing in a subscriber.
 
-View the [source code](https://github.com/googleapis/nodejs-pubsub/blob/main/samples/modifyPushConfig.js).
+View the [source code](https://github.com/googleapis/nodejs-pubsub/blob/main/samples/listenWithOpenTelemetryTracing.js).
 
-[![Open in Cloud Shell][shell_img]](https://console.cloud.google.com/cloudshell/open?git_repo=https://github.com/googleapis/nodejs-pubsub&page=editor&open_in_editor=samples/modifyPushConfig.js,samples/README.md)
+[![Open in Cloud Shell][shell_img]](https://console.cloud.google.com/cloudshell/open?git_repo=https://github.com/googleapis/nodejs-pubsub&page=editor&open_in_editor=samples/listenWithOpenTelemetryTracing.js,samples/README.md)
 
 __Usage:__
 
 
-`node modifyPushConfig.js <topic-name-or-id> <subscription-name-or-id>`
+`node listenWithOpenTelemetryTracing.js <subscription-name-or-id>`
 
 
 -----
 
 
 
 
-### OpenTelemetry Tracing
+### Modify Push Configuration
 
-Demonstrates how to enable OpenTelemetry tracing in a publisher or subscriber.
+Modifies the configuration of an existing push subscription.
 
-View the [source code](https://github.com/googleapis/nodejs-pubsub/blob/main/samples/openTelemetryTracing.js).
+View the [source code](https://github.com/googleapis/nodejs-pubsub/blob/main/samples/modifyPushConfig.js).
 
-[![Open in Cloud Shell][shell_img]](https://console.cloud.google.com/cloudshell/open?git_repo=https://github.com/googleapis/nodejs-pubsub&page=editor&open_in_editor=samples/openTelemetryTracing.js,samples/README.md)
+[![Open in Cloud Shell][shell_img]](https://console.cloud.google.com/cloudshell/open?git_repo=https://github.com/googleapis/nodejs-pubsub&page=editor&open_in_editor=samples/modifyPushConfig.js,samples/README.md)
 
 __Usage:__
 
 
-`node openTelemetryTracing.js <topic-name-or-id> <subscription-name-or-id>`
+`node modifyPushConfig.js <topic-name-or-id> <subscription-name-or-id>`
 
 
 -----
@@ -1033,6 +1034,25 @@ __Usage:__
 
 
 
+### Publish with OpenTelemetry Tracing
+
+Demonstrates how to enable OpenTelemetry tracing in a publisher.
+
+View the [source code](https://github.com/googleapis/nodejs-pubsub/blob/main/samples/publishWithOpenTelemetryTracing.js).
+
+[![Open in Cloud Shell][shell_img]](https://console.cloud.google.com/cloudshell/open?git_repo=https://github.com/googleapis/nodejs-pubsub&page=editor&open_in_editor=samples/publishWithOpenTelemetryTracing.js,samples/README.md)
+
+__Usage:__
+
+
+`node openTelemetryTracing.js <topic-name-or-id>`
+
+
+-----
+
+
+
+
 ### Publish With Retry Settings
 
 Publishes a message to a topic with retry settings.

samples/listenWithOpenTelemetryTracing.js

@@ -0,0 +1,134 @@
+// Copyright 2020-2024 Google LLC
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//      http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+// This is a generated sample, using the typeless sample bot. Please
+// look for the source TypeScript sample (.ts) for modifications.
+'use strict';
+
+/**
+ * This sample demonstrates how to add OpenTelemetry tracing to the
+ * Google Cloud Pub/Sub API.
+ *
+ * For more information, see the README.md under /pubsub and the documentation
+ * at https://cloud.google.com/pubsub/docs.
+ */
+
+// sample-metadata:
+//   title: Subscribe with OpenTelemetry Tracing
+//   description: Demonstrates how to enable OpenTelemetry tracing in a subscriber.
+//   usage: node listenWithOpenTelemetryTracing.js <subscription-name-or-id>
+
+const OTEL_TIMEOUT = 2;
+const SUBSCRIBER_TIMEOUT = 10;
+
+// [START pubsub_subscribe_otel_tracing]
+/**
+ * TODO(developer): Uncomment these variables before running the sample.
+ */
+// const subscriptionNameOrId = 'YOUR_SUBSCRIPTION_OR_ID';
+
+// Imports the Google Cloud client library
+const {PubSub} = require('@google-cloud/pubsub');
+
+// Imports the OpenTelemetry API
+const {NodeTracerProvider} = require('@opentelemetry/sdk-trace-node');
+const {diag, DiagConsoleLogger, DiagLogLevel} = require('@opentelemetry/api');
+const {SimpleSpanProcessor} = require('@opentelemetry/sdk-trace-base');
+
+// To output to the console for testing, use the ConsoleSpanExporter.
+// import {ConsoleSpanExporter} from '@opentelemetry/sdk-trace-base';
+
+// To output to Cloud Trace, import the OpenTelemetry bridge library.
+const {
+  TraceExporter,
+} = require('@google-cloud/opentelemetry-cloud-trace-exporter');
+
+const {Resource} = require('@opentelemetry/resources');
+const {
+  SEMRESATTRS_SERVICE_NAME,
+} = require('@opentelemetry/semantic-conventions');
+
+// Enable the diagnostic logger for OpenTelemetry
+diag.setLogger(new DiagConsoleLogger(), DiagLogLevel.DEBUG);
+
+// Log spans out to the console, for testing.
+// const exporter = new ConsoleSpanExporter();
+
+// Log spans out to Cloud Trace, for production.
+const exporter = new TraceExporter();
+
+// Build a tracer provider and a span processor to do
+// something with the spans we're generating.
+const provider = new NodeTracerProvider({
+  resource: new Resource({
+    [SEMRESATTRS_SERVICE_NAME]: 'otel subscriber example',
+  }),
+});
+const processor = new SimpleSpanProcessor(exporter);
+provider.addSpanProcessor(processor);
+provider.register();
+
+// Creates a client; cache this for further use.
+const pubSubClient = new PubSub({enableOpenTelemetryTracing: true});
+
+async function subscriptionListen(subscriptionNameOrId) {
+  const subscriber = pubSubClient.subscription(subscriptionNameOrId);
+
+  // Message handler for subscriber
+  const messageHandler = async message => {
+    console.log(`Message ${message.id} received.`);
+    message.ack();
+  };
+
+  // Error handler for subscriber
+  const errorHandler = async error => {
+    console.log('Received error:', error);
+  };
+
+  // Listens for new messages from the topic
+  subscriber.on('message', messageHandler);
+  subscriber.on('error', errorHandler);
+
+  // Ensures that all spans got flushed by the exporter. This function
+  // is in service to making sure that any buffered Pub/Sub messages
+  // and/or OpenTelemetry spans are properly flushed to the server
+  // side. In normal usage, you'd only need to do something like this
+  // on process shutdown.
+  async function shutdown() {
+    await subscriber.close();
+    await processor.forceFlush();
+    await new Promise(r => setTimeout(r, OTEL_TIMEOUT * 1000));
+  }
+
+  // Wait a bit for the subscription to receive messages, then shut down
+  // gracefully. This is for the sample only; normally you would not need
+  // this delay.
+  await new Promise(r =>
+    setTimeout(async () => {
+      subscriber.removeAllListeners();
+      await shutdown();
+      r();
+    }, SUBSCRIBER_TIMEOUT * 1000)
+  );
+}
+// [END pubsub_subscribe_otel_tracing]
+
+function main(subscriptionNameOrId = 'YOUR_SUBSCRIPTION_NAME_OR_ID') {
+  subscriptionListen(subscriptionNameOrId).catch(err => {
+    console.error(err.message);
+    process.exitCode = 1;
+  });
+}
+
+main(...process.argv.slice(2));