docs(pubsub-otel): add a streaming pull example (#331)

* docs(pubsub-otel): add a streaming pull example

* Update pubsub-open-telemetry/streaming_pull_subscriber.cc

pubsub-open-telemetry/BUILD.bazel

@@ -76,3 +76,12 @@ cc_binary(
         "@google_cloud_cpp//:pubsub",
     ],
 )
+
+cc_binary(
+    name = "streaming_pull_subscriber",
+    srcs = ["streaming_pull_subscriber.cc"],
+    deps = [
+        "@google_cloud_cpp//:opentelemetry",
+        "@google_cloud_cpp//:pubsub",
+    ],
+)

pubsub-open-telemetry/CMakeLists.txt

@@ -69,3 +69,9 @@ target_compile_features(unary_pull_subscriber PRIVATE cxx_std_14)
 target_link_libraries(
     unary_pull_subscriber PRIVATE google-cloud-cpp::pubsub
                                   google-cloud-cpp::opentelemetry)
+
+add_executable(streaming_pull_subscriber streaming_pull_subscriber.cc)
+target_compile_features(streaming_pull_subscriber PRIVATE cxx_std_14)
+target_link_libraries(
+    streaming_pull_subscriber PRIVATE google-cloud-cpp::pubsub
+                                      google-cloud-cpp::opentelemetry)

pubsub-open-telemetry/streaming_pull_subscriber.cc

@@ -0,0 +1,80 @@
+// Copyright 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
+//
+// https://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.
+
+//! [START pubsub_subscribe_otel_tracing]
+#include "google/cloud/opentelemetry/configure_basic_tracing.h"
+#include "google/cloud/opentelemetry_options.h"
+#include "google/cloud/pubsub/message.h"
+#include "google/cloud/pubsub/publisher.h"
+#include "google/cloud/pubsub/subscriber.h"
+#include "google/cloud/pubsub/subscription.h"
+#include <iostream>
+
+int main(int argc, char* argv[]) try {
+  if (argc != 4) {
+    std::cerr << "Usage: " << argv[0]
+              << " <project-id> <topic-id> <subscription-id>\n";
+    return 1;
+  }
+
+  std::string const project_id = argv[1];
+  std::string const topic_id = argv[2];
+  std::string const subscription_id = argv[3];
+
+  // Create a few namespace aliases to make the code easier to read.
+  namespace gc = ::google::cloud;
+  namespace otel = gc::otel;
+  namespace pubsub = gc::pubsub;
+
+  auto constexpr kWaitTimeout = std::chrono::seconds(30);
+
+  auto project = gc::Project(project_id);
+  auto configuration = otel::ConfigureBasicTracing(project);
+
+  // Publish a message with tracing enabled.
+  auto publisher = pubsub::Publisher(pubsub::MakePublisherConnection(
+      pubsub::Topic(project_id, topic_id),
+      gc::Options{}.set<gc::OpenTelemetryTracingOption>(true)));
+  // Block until the message is actually sent and throw on error.
+  auto id = publisher.Publish(pubsub::MessageBuilder().SetData("Hi!").Build())
+                .get()
+                .value();
+  std::cout << "Sent message with id: (" << id << ")\n";
+
+  // Receive a message using streaming pull with tracing enabled.
+  auto subscriber = pubsub::Subscriber(pubsub::MakeSubscriberConnection(
+      pubsub::Subscription(project_id, subscription_id),
+      gc::Options{}.set<gc::OpenTelemetryTracingOption>(true)));
+
+  auto session =
+      subscriber.Subscribe([&](pubsub::Message const& m, pubsub::AckHandler h) {
+        std::cout << "Received message " << m << "\n";
+        std::move(h).ack();
+      });
+
+  std::cout << "Waiting for messages on " + subscription_id + "...\n";
+
+  // Blocks until the timeout is reached.
+  auto result = session.wait_for(kWaitTimeout);
+  if (result == std::future_status::timeout) {
+    std::cout << "timeout reached, ending session\n";
+    session.cancel();
+  }
+
+  return 0;
+} catch (google::cloud::Status const& status) {
+  std::cerr << "google::cloud::Status thrown: " << status << "\n";
+  return 1;
+}
+//! [END pubsub_subscribe_otel_tracing]

pubsub-open-telemetry/subscriber.md

@@ -1,5 +1,67 @@
 # Subscriber
 
+## Setup
+
+To begin, you need to setup the following resources in your project.
+
+#### Create the Cloud Pub/Sub subscription attached to a topic
+
+If you don't already have them, create a topic and a subscription with pull
+delivery.
+
+Export the following environment variables:
+
+```sh
+export=GOOGLE_CLOUD_PROJECT=[PROJECT-ID]
+export=GOOGLE_CLOUD_SUBSCRIPTION=[SUBSCRIPTION-ID]
+export=GOOGLE_CLOUD_TOPIC=[TOPIC-ID]
+```
+
+Use the CLI to create the resources:
+
+```sh
+gcloud pubsub topics create "--project=${GOOGLE_CLOUD_PROJECT}" ${GOOGLE_CLOUD_TOPIC}
+gcloud pubsub subscriptions create "--project=${GOOGLE_CLOUD_PROJECT}" "--topic=${GOOGLE_CLOUD_TOPIC}" ${GOOGLE_CLOUD_SUBSCRIPTION}
+```
+
+#### Publish a message
+
+Make sure you publish a message with tracing enabled. If not, the traces will
+not be linked.
+
+## Streaming pull subscriber
+
+### Build and run using CMake and Vcpkg
+
+```sh
+cd cpp-samples/pubsub-open-telemetry
+cmake -S . -B .build -DCMAKE_TOOLCHAIN_FILE=$HOME/vcpkg/scripts/buildsystems/vcpkg.cmake -G Ninja
+cmake --build .build --target streaming_pull_subscriber
+```
+
+#### Run the subscriber with streaming pull
+
+```shell
+.build/streaming_pull_subscriber ${GOOGLE_CLOUD_PROJECT} ${GOOGLE_CLOUD_TOPIC} ${GOOGLE_CLOUD_SUBSCRIPTION}
+```
+
+### Build and run using Bazel
+
+#### 1. Download or clone this repo
+
+```shell
+git clone https://github.com/GoogleCloudPlatform/cpp-samples
+```
+
+#### 2. Compile and run these examples
+
+```shell
+cd cpp-samples/pubsub-open-telemetry
+bazel run //:streaming_pull_subscriber -- ${GOOGLE_CLOUD_PROJECT} ${GOOGLE_CLOUD_TOPIC} ${GOOGLE_CLOUD_SUBSCRIPTION}
+```
+
+## Unary pull subscriber
+
 To try receiving a message using unary pull, run the `unary_pull_subscriber`
 application. It publishes a message to a topic and then pulls the same message
 from a subscription, and then exports the spans to cloud trace.
@@ -10,7 +72,7 @@ data. We currently do not support OTel ABI 2.0 with CMake.
 
 For setup instructions, refer to the [README.md](README.md).
 
-## Example traces
+### Example traces
 
 To find the traces, navigate to the Cloud Trace UI.
 
@@ -34,36 +96,7 @@ To find the traces, navigate to the Cloud Trace UI.
 
 ![Screenshot of the ack span in the Cloud Trace UI.](assets/otel2/unary_ack_span.png)
 
-### Setup
-
-### Create the Cloud Pub/Sub subscription attached to a topic
-
-If you don't already have them, create a topic and a subscription with pull
-delivery.
-
-Export the following environment variables:
-
-```sh
-export=GOOGLE_CLOUD_PROJECT=[PROJECT-ID]
-export=GOOGLE_CLOUD_SUBSCRIPTION=[SUBSCRIPTION-ID]
-export=GOOGLE_CLOUD_TOPIC=[TOPIC-ID]
-```
-
-Use the CLI to create the resources:
-
-```sh
-gcloud pubsub topics create "--project=${GOOGLE_CLOUD_PROJECT}" ${GOOGLE_CLOUD_TOPIC}
-gcloud pubsub subscriptions create "--project=${GOOGLE_CLOUD_PROJECT}" "--topic=${GOOGLE_CLOUD_TOPIC}" ${GOOGLE_CLOUD_SUBSCRIPTION}
-```
-
-### Publish a message
-
-Make sure you publish a message with tracing enabled. If not, the traces will
-not be linked.
-
-## Build and run
-
-### Using CMake and Vcpkg
+### Build and run using CMake and Vcpkg
 
 ```sh
 cd cpp-samples/pubsub-open-telemetry
@@ -77,15 +110,15 @@ cmake --build .build --target unary_pull_subscriber
 .build/unary_pull_subscriber ${GOOGLE_CLOUD_PROJECT} ${GOOGLE_CLOUD_TOPIC} ${GOOGLE_CLOUD_SUBSCRIPTION}
 ```
 
-## Build and run using Bazel
+### Build and run using Bazel
 
-### 1. Download or clone this repo
+#### 1. Download or clone this repo
 
 ```shell
 git clone https://github.com/GoogleCloudPlatform/cpp-samples
 ```
 
-### 2. Compile and run these examples
+#### 2. Compile and run these examples
 
 ```shell
 cd cpp-samples/pubsub-open-telemetry