diff --git a/examples/example-gcp-csm-observability/README.md b/examples/example-gcp-csm-observability/README.md new file mode 100644 index 00000000000..cbb206fbb46 --- /dev/null +++ b/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`. diff --git a/examples/example-gcp-csm-observability/build.gradle b/examples/example-gcp-csm-observability/build.gradle new file mode 100644 index 00000000000..ae09acaae40 --- /dev/null +++ b/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.65.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 + } +} diff --git a/examples/example-gcp-csm-observability/csm-client.Dockerfile b/examples/example-gcp-csm-observability/csm-client.Dockerfile new file mode 100644 index 00000000000..31a3262e863 --- /dev/null +++ b/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"] diff --git a/examples/example-gcp-csm-observability/csm-server.Dockerfile b/examples/example-gcp-csm-observability/csm-server.Dockerfile new file mode 100644 index 00000000000..675b450143f --- /dev/null +++ b/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"] diff --git a/examples/example-gcp-csm-observability/settings.gradle b/examples/example-gcp-csm-observability/settings.gradle new file mode 100644 index 00000000000..6b7615117d6 --- /dev/null +++ b/examples/example-gcp-csm-observability/settings.gradle @@ -0,0 +1 @@ +rootProject.name = 'example-gcp-csm-observability' diff --git a/examples/example-gcp-csm-observability/src/main/java/io/grpc/examples/csmobservability/CsmObservabilityClient.java b/examples/example-gcp-csm-observability/src/main/java/io/grpc/examples/csmobservability/CsmObservabilityClient.java new file mode 100644 index 00000000000..a613ef222ac --- /dev/null +++ b/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(); + } + } +} diff --git a/examples/example-gcp-csm-observability/src/main/java/io/grpc/examples/csmobservability/CsmObservabilityServer.java b/examples/example-gcp-csm-observability/src/main/java/io/grpc/examples/csmobservability/CsmObservabilityServer.java new file mode 100644 index 00000000000..65bb3a96742 --- /dev/null +++ b/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 responseObserver) { + HelloReply reply = HelloReply.newBuilder().setMessage("Hello " + req.getName()).build(); + responseObserver.onNext(reply); + responseObserver.onCompleted(); + } + } +} diff --git a/examples/example-gcp-csm-observability/src/main/proto/helloworld/helloworld.proto b/examples/example-gcp-csm-observability/src/main/proto/helloworld/helloworld.proto new file mode 100644 index 00000000000..64a8c09ee16 --- /dev/null +++ b/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; +}