examples: Add GCP CSM Observability example (#11267)

Add GCP CSM observability example client and example server.

examples/example-gcp-csm-observability/README.md

@@ -0,0 +1,43 @@
+gRPC GCP CSM Observability Example
+================
+
+The GCP CSM Observability example consists of a Hello World client and a Hello World server and shows how to configure CSM Observability
+for gRPC client and gRPC server.
+
+## Configuration
+
+`CsmObservabilityClient` takes the following command-line arguments -
+* user - Name to be greeted.
+* target - Server address. Default value is `xds:///helloworld:50051`.
+  * When client tries to connect to target, gRPC would use xDS to resolve this target and connect to the server backend.
+* prometheusPort - Port used for exposing prometheus metrics. Default value is `9464`.
+
+
+`CsmObservabilityServer` takes the following command-line arguments -
+* port - Port used for running Hello World server. Default value is `50051`.
+* prometheusPort - Port used for exposing prometheus metrics. Default value is `9464`.
+
+## Build the example
+
+From the `grpc-java/examples/`directory i.e,
+```
+cd grpc-java/examples
+```
+Run the following to generate client and server images respectively.
+
+Client:
+```
+docker build -f example-gcp-csm-observability/csm-client.Dockerfile .
+```
+Server:
+```
+docker build -f example-gcp-csm-observability/csm-server.Dockerfile .
+```
+
+To push to a registry, add a tag to the image either by adding a `-t` flag to `docker build` command above or run:
+
+```
+docker image tag ${sha from build command above} ${tag}
+```
+
+And then push the tagged image using `docker push`.

examples/example-gcp-csm-observability/build.gradle

@@ -0,0 +1,78 @@
+plugins {
+    // Provide convenience executables for trying out the examples.
+    id 'application'
+    id 'com.google.protobuf' version '0.9.4'
+    // Generate IntelliJ IDEA's .idea & .iml project files
+    id 'idea'
+    id 'java'
+}
+
+repositories {
+    maven { // The google mirror is less flaky than mavenCentral()
+        url "https://maven-central.storage-download.googleapis.com/maven2/"
+    }
+    mavenCentral()
+    mavenLocal()
+}
+
+java {
+    sourceCompatibility = JavaVersion.VERSION_1_8
+    targetCompatibility = JavaVersion.VERSION_1_8
+}
+
+// IMPORTANT: You probably want the non-SNAPSHOT version of gRPC. Make sure you
+// are looking at a tagged version of the example and not "master"!
+
+// Feel free to delete the comment at the next line. It is just for safely
+// updating the version in our release process.
+def grpcVersion = '1.66.0-SNAPSHOT' // CURRENT_GRPC_VERSION
+def protocVersion = '3.25.1'
+def openTelemetryVersion = '1.38.0'
+def openTelemetryPrometheusVersion = '1.38.0-alpha'
+
+dependencies {
+    implementation "io.grpc:grpc-protobuf:${grpcVersion}"
+    implementation "io.grpc:grpc-stub:${grpcVersion}"
+    implementation "io.grpc:grpc-gcp-csm-observability:${grpcVersion}"
+    implementation "io.opentelemetry:opentelemetry-sdk:${openTelemetryVersion}"
+    implementation "io.opentelemetry:opentelemetry-sdk-metrics:${openTelemetryVersion}"
+    implementation "io.opentelemetry:opentelemetry-exporter-logging:${openTelemetryVersion}"
+    implementation "io.opentelemetry:opentelemetry-exporter-prometheus:${openTelemetryPrometheusVersion}"
+    compileOnly "org.apache.tomcat:annotations-api:6.0.53"
+    runtimeOnly "io.grpc:grpc-xds:${grpcVersion}"
+    runtimeOnly "io.grpc:grpc-netty-shaded:${grpcVersion}"
+}
+
+protobuf {
+    protoc { artifact = "com.google.protobuf:protoc:${protocVersion}" }
+    plugins {
+        grpc { artifact = "io.grpc:protoc-gen-grpc-java:${grpcVersion}" }
+    }
+    generateProtoTasks {
+        all()*.plugins { grpc {} }
+    }
+}
+
+startScripts.enabled = false
+
+task CsmObservabilityHelloWorldServer(type: CreateStartScripts) {
+    mainClass = 'io.grpc.examples.csmobservability.CsmObservabilityServer'
+    applicationName = 'csm-observability-server'
+    outputDir = new File(project.buildDir, 'tmp/scripts/' + name)
+    classpath = startScripts.classpath
+}
+
+task CsmObservabilityHelloWorldClient(type: CreateStartScripts) {
+    mainClass = 'io.grpc.examples.csmobservability.CsmObservabilityClient'
+    applicationName = 'csm-observability-client'
+    outputDir = new File(project.buildDir, 'tmp/scripts/' + name)
+    classpath = startScripts.classpath
+}
+
+application {
+    applicationDistribution.into('bin') {
+        from(CsmObservabilityHelloWorldServer)
+        from(CsmObservabilityHelloWorldClient)
+        fileMode = 0755
+    }
+}

examples/example-gcp-csm-observability/csm-client.Dockerfile

@@ -0,0 +1,47 @@
+# Copyright 2024 gRPC authors.
+#
+# 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.
+
+#
+# Stage 1: Build CSM client
+#
+
+FROM eclipse-temurin:11-jdk AS build
+
+WORKDIR /grpc-java/examples
+COPY . .
+
+RUN cd example-gcp-csm-observability && ../gradlew installDist -PskipCodegen=true -PskipAndroid=true
+
+#
+# Stage 2:
+#
+# - Copy only the necessary files to reduce Docker image size.
+# - Have an ENTRYPOINT script which will launch the CSM client
+#   with the given parameters.
+#
+
+FROM eclipse-temurin:11-jre
+
+WORKDIR /grpc-java/
+COPY --from=build /grpc-java/examples/example-gcp-csm-observability/build/install/example-gcp-csm-observability/. .
+
+# Intentionally after the COPY to force the update on each build.
+# Update Ubuntu system packages:
+RUN apt-get update \
+    && apt-get -y upgrade \
+    && apt-get -y autoremove \
+    && rm -rf /var/lib/apt/lists/*
+
+# Client
+ENTRYPOINT ["bin/csm-observability-client"]

examples/example-gcp-csm-observability/csm-server.Dockerfile

@@ -0,0 +1,47 @@
+# Copyright 2024 gRPC authors.
+#
+# 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.
+
+#
+# Stage 1: Build CSM server
+#
+
+FROM eclipse-temurin:11-jdk AS build
+
+WORKDIR /grpc-java/examples
+COPY . .
+
+RUN cd example-gcp-csm-observability && ../gradlew installDist -PskipCodegen=true -PskipAndroid=true
+
+#
+# Stage 2:
+#
+# - Copy only the necessary files to reduce Docker image size.
+# - Have an ENTRYPOINT script which will launch the CSM server
+#   with the given parameters.
+#
+
+FROM eclipse-temurin:11-jre
+
+WORKDIR /grpc-java/
+COPY --from=build /grpc-java/examples/example-gcp-csm-observability/build/install/example-gcp-csm-observability/. .
+
+# Intentionally after the COPY to force the update on each build.
+# Update Ubuntu system packages:
+RUN apt-get update \
+    && apt-get -y upgrade \
+    && apt-get -y autoremove \
+    && rm -rf /var/lib/apt/lists/*
+
+# Server
+ENTRYPOINT ["bin/csm-observability-server"]

examples/example-gcp-csm-observability/settings.gradle

@@ -0,0 +1 @@
+rootProject.name = 'example-gcp-csm-observability'

examples/example-gcp-csm-observability/src/main/java/io/grpc/examples/csmobservability/CsmObservabilityClient.java

@@ -0,0 +1,149 @@
+/*
+ * Copyright 2024 The gRPC Authors
+ *
+ * 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.
+ */
+
+package io.grpc.examples.csmobservability;
+
+import io.grpc.Channel;
+import io.grpc.Grpc;
+import io.grpc.InsecureChannelCredentials;
+import io.grpc.ManagedChannel;
+import io.grpc.ManagedChannelBuilder;
+import io.grpc.StatusRuntimeException;
+import io.grpc.examples.helloworld.GreeterGrpc;
+import io.grpc.examples.helloworld.HelloReply;
+import io.grpc.examples.helloworld.HelloRequest;
+import io.grpc.gcp.csm.observability.CsmObservability;
+import io.opentelemetry.exporter.logging.LoggingMetricExporter;
+import io.opentelemetry.exporter.prometheus.PrometheusHttpServer;
+import io.opentelemetry.sdk.OpenTelemetrySdk;
+import io.opentelemetry.sdk.metrics.SdkMeterProvider;
+import java.util.concurrent.TimeUnit;
+import java.util.concurrent.atomic.AtomicBoolean;
+import java.util.logging.Level;
+import java.util.logging.Logger;
+
+/**
+ * A simple CSM observability client that requests a greeting from the {@link HelloWorldServer} and
+ * generates CSM telemetry data based on the configuration.
+ */
+public class CsmObservabilityClient {
+  private static final Logger logger = Logger.getLogger(CsmObservabilityClient.class.getName());
+
+  private final GreeterGrpc.GreeterBlockingStub blockingStub;
+
+  /** Construct client for accessing HelloWorld server using the existing channel. */
+  public CsmObservabilityClient(Channel channel) {
+    blockingStub = GreeterGrpc.newBlockingStub(channel);
+  }
+
+  /** Say hello to server. */
+  public void greet(String name) {
+    logger.info("Will try to greet " + name + " ...");
+    HelloRequest request = HelloRequest.newBuilder().setName(name).build();
+    HelloReply response;
+    try {
+      response = blockingStub.sayHello(request);
+    } catch (StatusRuntimeException e) {
+      logger.log(Level.WARNING, "RPC failed: {0}", e.getStatus());
+      return;
+    }
+    logger.info("Greeting: " + response.getMessage());
+  }
+
+  /**
+   * Greet server. If provided, the first element of {@code args} is the name to use in the
+   * greeting. The second argument is the target server.
+   */
+  public static void main(String[] args) throws Exception {
+    String user = "world";
+    String target = "xds:///helloworld:50051";
+    int prometheusPort = 9464;
+    AtomicBoolean sendRpcs = new AtomicBoolean(true);
+    if (args.length > 0) {
+      if ("--help".equals(args[0])) {
+        System.err.println("Usage: [name [target [prometheusPort]]]");
+        System.err.println("");
+        System.err.println("  name    The name you wish to be greeted by. Defaults to " + user);
+        System.err.println("  target  The server to connect to. Defaults to " + target);
+        System.err.println("  prometheusPort  The port to expose prometheus metrics. Defaults to " + prometheusPort);
+        System.exit(1);
+      }
+      user = args[0];
+    }
+    if (args.length > 1) {
+      target = args[1];
+    }
+    if (args.length > 2) {
+      prometheusPort = Integer.parseInt(args[2]);
+    }
+
+    Thread mainThread = Thread.currentThread();
+
+    Runtime.getRuntime().addShutdownHook(new Thread() {
+      @Override
+      public void run() {
+        // Use stderr here since the logger may have been reset by its JVM shutdown hook.
+        System.err.println("*** shutting down gRPC client since JVM is shutting down");
+
+        sendRpcs.set(false);
+        try {
+          mainThread.join();
+        } catch (InterruptedException e) {
+          e.printStackTrace(System.err);
+        }
+        System.err.println("*** client shut down");
+      }
+    });
+
+    // Adds a PrometheusHttpServer to convert OpenTelemetry metrics to Prometheus format and
+    // expose these via a HttpServer exporter to the SdkMeterProvider.
+    SdkMeterProvider sdkMeterProvider = SdkMeterProvider.builder()
+        .registerMetricReader(
+            PrometheusHttpServer.builder().setPort(prometheusPort).build())
+        .build();
+
+    // Initialize OpenTelemetry SDK with MeterProvider configured with Prometeheus.
+    OpenTelemetrySdk openTelemetrySdk =
+        OpenTelemetrySdk.builder().setMeterProvider(sdkMeterProvider).build();
+
+    // Initialize CSM Observability.
+    CsmObservability observability = CsmObservability.newBuilder()
+        .sdk(openTelemetrySdk)
+        .build();
+    // Registers CSM observabiity globally.
+    observability.registerGlobal();
+
+    // Create a communication channel to the server, known as a Channel.
+    ManagedChannel channel = Grpc.newChannelBuilder(target, InsecureChannelCredentials.create())
+        .build();
+    CsmObservabilityClient client = new CsmObservabilityClient(channel);
+
+    try {
+      // Run RPCs every second.
+      while (sendRpcs.get()) {
+        client.greet(user);
+        // Sleep for a bit before sending the next RPC.
+        Thread.sleep(1000);
+      }
+    } finally {
+      channel.shutdownNow().awaitTermination(5, TimeUnit.SECONDS);
+      // Shut down CSM Observability.
+      observability.close();
+      // Shut down OpenTelemetry SDK.
+      openTelemetrySdk.close();
+    }
+  }
+}

examples/example-gcp-csm-observability/src/main/java/io/grpc/examples/csmobservability/CsmObservabilityServer.java

@@ -0,0 +1,135 @@
+/*
+ * Copyright 2024 The gRPC Authors
+ *
+ * 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.
+ */
+
+package io.grpc.examples.csmobservability;
+
+import io.grpc.Grpc;
+import io.grpc.InsecureServerCredentials;
+import io.grpc.Server;
+import io.grpc.examples.helloworld.GreeterGrpc;
+import io.grpc.examples.helloworld.HelloReply;
+import io.grpc.examples.helloworld.HelloRequest;
+import io.grpc.gcp.csm.observability.CsmObservability;
+import io.grpc.stub.StreamObserver;
+import io.opentelemetry.exporter.prometheus.PrometheusHttpServer;
+import io.opentelemetry.sdk.OpenTelemetrySdk;
+import io.opentelemetry.sdk.metrics.SdkMeterProvider;
+import java.io.IOException;
+import java.util.concurrent.TimeUnit;
+import java.util.logging.Logger;
+
+/**
+ * CSM Observability server that manages startup/shutdown of a {@code Greeter} server and generates
+ * CSM telemetry based on the configuration.
+ */
+public class CsmObservabilityServer {
+  private static final Logger logger = Logger.getLogger(CsmObservabilityServer.class.getName());
+
+  private Server gRPCServer;
+  private void start(int port) throws IOException {
+    gRPCServer = Grpc.newServerBuilderForPort(port, InsecureServerCredentials.create())
+        .addService(new GreeterImpl())
+        .build()
+        .start();
+    logger.info("Server started, listening on " + port);
+  }
+
+  private void stop() throws InterruptedException {
+    if (gRPCServer != null) {
+      gRPCServer.shutdown().awaitTermination(30, TimeUnit.SECONDS);
+    }
+  }
+
+  private void blockUntilShutdown() throws InterruptedException {
+    if (gRPCServer != null) {
+      gRPCServer.awaitTermination();
+    }
+  }
+
+  /**
+   * Main launches the server from the command line.
+   */
+  public static void main(String[] args) throws IOException, InterruptedException {
+    /* The port on which the server should run. */
+    int port = 50051;
+    int prometheusPort = 9464;
+
+    if (args.length > 0) {
+      if ("--help".equals(args[0])) {
+        System.err.println("Usage: [port [prometheus_port]]");
+        System.err.println("");
+        System.err.println("  port  The port on which server will run. Defaults to " + port);
+        System.err.println("  prometheusPort  The port to expose prometheus metrics. Defaults to " + prometheusPort);
+        System.exit(1);
+      }
+      port = Integer.parseInt(args[0]);
+    }
+    if (args.length > 1) {
+      prometheusPort = Integer.parseInt(args[1]);
+    }
+
+    // Adds a PrometheusHttpServer to convert OpenTelemetry metrics to Prometheus format and
+    // expose these via a HttpServer exporter to the SdkMeterProvider.
+    SdkMeterProvider sdkMeterProvider = SdkMeterProvider.builder()
+        .registerMetricReader(
+            PrometheusHttpServer.builder().setPort(prometheusPort).build())
+        .build();
+
+    // Initialize OpenTelemetry SDK with MeterProvider configured with Prometheus metrics exporter
+    OpenTelemetrySdk openTelemetrySdk =
+        OpenTelemetrySdk.builder().setMeterProvider(sdkMeterProvider).build();
+
+    // Initialize CSM Observability
+    CsmObservability observability = CsmObservability.newBuilder()
+        .sdk(openTelemetrySdk)
+        .build();
+    // Registers CSM observabiity globally
+    observability.registerGlobal();
+
+    final CsmObservabilityServer server = new CsmObservabilityServer();
+    server.start(port);
+
+    Runtime.getRuntime().addShutdownHook(new Thread() {
+      @Override
+      public void run() {
+        System.err.println("*** shutting down gRPC server since JVM is shutting down");
+        try {
+          server.stop();
+        } catch (InterruptedException e) {
+          e.printStackTrace(System.err);
+        }
+        // Shut down CSM observability.
+        observability.close();
+        // Shut down OpenTelemetry SDK.
+        openTelemetrySdk.close();
+
+        System.err.println("*** server shut down");
+      }
+    });
+
+    server.blockUntilShutdown();
+  }
+
+  static class GreeterImpl extends GreeterGrpc.GreeterImplBase {
+
+    @Override
+    public void sayHello(HelloRequest req, StreamObserver<HelloReply> responseObserver) {
+      HelloReply reply = HelloReply.newBuilder().setMessage("Hello " + req.getName()).build();
+      responseObserver.onNext(reply);
+      responseObserver.onCompleted();
+    }
+  }
+}

examples/example-gcp-csm-observability/src/main/proto/helloworld/helloworld.proto

@@ -0,0 +1,39 @@
+/*
+ * Copyright 2023 The gRPC Authors
+ *
+ * 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.
+ */
+syntax = "proto3";
+
+option java_multiple_files = true;
+option java_package = "io.grpc.examples.helloworld";
+option java_outer_classname = "HelloWorldProto";
+option objc_class_prefix = "HLW";
+
+package helloworld;
+
+// The greeting service definition.
+service Greeter {
+  // Sends a greeting
+  rpc SayHello (HelloRequest) returns (HelloReply) {}
+}
+
+// The request message containing the user's name.
+message HelloRequest {
+  string name = 1;
+}
+
+// The response message containing the greetings
+message HelloReply {
+  string message = 1;
+}