Skip to content

Commit 07e34a7

Browse files
fengli79fengli79
authored
Merge pull request #1043 from fengli79/master
Add an end to end example for gRPC A66 metrics.
2 parents 8132882 + 2fa5594 commit 07e34a7

File tree

17 files changed

+2126
-0
lines changed

17 files changed

+2126
-0
lines changed

‎examples/grpc-observability/README.md

Lines changed: 130 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,130 @@
1+
# gRPC-Observability Example
2+
3+
## Features
4+
5+
* End to end examples to generate the gRPC metrics with Prometheus, including:
6+
* A frontend microservice (
7+
in [gRPC-Spring](https://github.com/grpc-ecosystem/grpc-spring)), which
8+
keeps calling the backend microservices.
9+
* A backend microservice (
10+
in [gRPC-Spring](https://github.com/grpc-ecosystem/grpc-spring)), which
11+
serves unary/client streaming/server streaming and bidi streaming example
12+
services.
13+
* Instructions to containerize them and deploy them in kubernetes
14+
* Monitoring dashboards to support
15+
the [gRPC A66](https://github.com/grpc/proposal/blob/master/A66-otel-stats.md)
16+
spec.
17+
* Deploy the Grafana and import
18+
the [gRPC A66](https://github.com/grpc/proposal/blob/master/A66-otel-stats.md)
19+
dashboard
20+
21+
## Build the end to end example
22+
23+
Under the root directory of your grpc-spring repo
24+
25+
```
26+
./gradlew build
27+
```
28+
29+
## Run the end to end example
30+
31+
Run the backend microservice locally
32+
33+
```
34+
./gradlew examples:grpc-observability:backend:bootRun
35+
```
36+
37+
Run the frontend microservice locally. Please note that the backend needs to be
38+
started first to be ready to serve the client calls.
39+
40+
```
41+
./gradlew examples:grpc-observability:frontend:bootRun
42+
```
43+
44+
The backend microservice will
45+
46+
- listen on the TCP port 9091 for the gRPC calls from the frontend microservice.
47+
- listen on the TCP port 8081 for the Prometheus scrape requests.
48+
The frontend microservice will
49+
- send the unary/client streaming/server streaming/bidi streaming calls to the
50+
backend microservices via TCP port 9091.
51+
- listen on the TCP port 8080 for the Prometheus scrape requests.
52+
53+
## Containerize the frontend/backend microservices
54+
55+
Build the docker image for the backend microservice
56+
57+
```
58+
docker build -t grpc-observability/grpc-spring-example-backend examples/grpc-observability/backend
59+
```
60+
61+
Run the backend microservice with docker
62+
63+
```
64+
docker run --network host grpc-observability/grpc-spring-example-backend
65+
```
66+
67+
Build the docker image for the frontend microservice
68+
69+
```
70+
docker build -t grpc-observability/grpc-spring-example-frontend examples/grpc-observability/frontend
71+
```
72+
73+
Run the frontend microservice with docker
74+
75+
```
76+
docker run --network host grpc-observability/grpc-spring-example-frontend
77+
```
78+
79+
## Deploy the end to end example to kubernetes
80+
81+
To deploy the example to kubernetes, please upload the docker images to a
82+
registry by yourself and modify the frontend.yaml/backend.yaml with your docker
83+
image location, and then run following commands.
84+
85+
Deploy the backend microservice in kubernetes
86+
87+
```
88+
kubectl apply -f ./examples/grpc-observability/backend/backend.yaml
89+
```
90+
91+
Deploy the frontend microservice in kubernetes
92+
93+
```
94+
kubectl apply -f ./examples/grpc-observability/frontend/frontend.yaml
95+
```
96+
97+
## Set up the Prometheus to collect the gRPC metrics
98+
99+
Once the frontend/backend microservices are deployed (either locally or on
100+
cloud), you may set up the Prometheus to start scraping the metrics from them.
101+
Depends on where you run the frontend/backend microservices, you may need to
102+
deploy the Prometheus to a proper location to be able to access them, such as,
103+
the same cloud, etc.
104+
105+
If you
106+
use [Google Managed Prometheus](https://cloud.google.com/stackdriver/docs/managed-prometheus),
107+
you may need to configure the PodMonitoring resource to tell where are endpoints
108+
to scrape the Prometheus metrics.
109+
110+
```
111+
kubectl apply -f ./examples/grpc-observability/pod_monitoring.yaml
112+
```
113+
114+
## Set up the Grafana dashboard
115+
116+
Once we have the gRPC metrics scraped by the Prometheus, we may set up a Grafana
117+
server to visualize them.
118+
119+
- Set up a Grafana server, deploy it to a place where can connect the Prometheus
120+
server as its data source.
121+
- Create a Grafana dashboard by importing the
122+
[examples/grpc-observability/grafana/prometheus/microservices-grpc-dashboard.json](http://github.com/grpc-ecosystem/grpc-spring/blob/master/examples/grpc-observability/grafana/prometheus/microservices-grpc-dashboard.json)
123+
file.
124+
125+
If you
126+
use [Google Managed Prometheus](https://cloud.google.com/stackdriver/docs/managed-prometheus),
127+
you need to follow
128+
the [Grafana Query User Guide](https://cloud.google.com/stackdriver/docs/managed-prometheus/query)
129+
to set up the Grafana server
130+
and [data source syncer](https://github.com/GoogleCloudPlatform/prometheus-engine/tree/main/cmd/datasource-syncer).

‎examples/grpc-observability/backend/Dockerfile

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,3 @@
1+
FROM eclipse-temurin:17-jdk-alpine
2+
COPY build/libs/backend.jar backend.jar
3+
ENTRYPOINT ["java","-jar","/backend.jar"]

‎examples/grpc-observability/backend/backend.yaml

Lines changed: 52 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,52 @@
1+
# Copyright 2023 gRPC Authors
2+
#
3+
# Licensed under the Apache License, Version 2.0 (the "License");
4+
# you may not use this file except in compliance with the License.
5+
# You may obtain a copy of the License at
6+
#
7+
# https://www.apache.org/licenses/LICENSE-2.0
8+
#
9+
# Unless required by applicable law or agreed to in writing, software
10+
# distributed under the License is distributed on an "AS IS" BASIS,
11+
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12+
# See the License for the specific language governing permissions and
13+
# limitations under the License.
14+
#
15+
apiVersion: apps/v1
16+
kind: Deployment
17+
metadata:
18+
name: backend
19+
spec:
20+
replicas: 1
21+
selector:
22+
matchLabels:
23+
app: backend
24+
template:
25+
metadata:
26+
labels:
27+
app: backend
28+
monitor: prometheus
29+
spec:
30+
containers:
31+
- name: backend
32+
# Please upload the docker image of grpc-observability/grpc-spring-example-backend to an image registry, such as https://cloud.google.com/artifact-registry.
33+
image: <your image of the backend>
34+
ports:
35+
- name: monitoring
36+
containerPort: 8081
37+
- name: grpc
38+
containerPort: 9091
39+
---
40+
apiVersion: v1
41+
kind: Service
42+
metadata:
43+
name: backend
44+
spec:
45+
clusterIP: None
46+
selector:
47+
app: backend
48+
ports:
49+
- name: monitoring
50+
port: 8081
51+
- name: grpc
52+
port: 9091

‎examples/grpc-observability/backend/build.gradle

Lines changed: 26 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,26 @@
1+
// Copyright 2023 The gRPC-GCP-Mobile Authors
2+
// All rights reserved.
3+
//
4+
// Licensed under the Apache License, Version 2.0 (the "License");
5+
// you may not use this file except in compliance with the License.
6+
// You may obtain a copy of the License at
7+
//
8+
// http://www.apache.org/licenses/LICENSE-2.0
9+
//
10+
// Unless required by applicable law or agreed to in writing, software
11+
// distributed under the License is distributed on an "AS IS" BASIS,
12+
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13+
// See the License for the specific language governing permissions and
14+
// limitations under the License.
15+
//
16+
plugins {
17+
id 'org.springframework.boot'
18+
}
19+
20+
dependencies {
21+
implementation project(':examples:grpc-observability:proto')
22+
implementation project(':grpc-server-spring-boot-starter')
23+
implementation 'org.springframework.boot:spring-boot-starter-actuator'
24+
implementation "org.springframework.boot:spring-boot-starter-web"
25+
implementation 'io.micrometer:micrometer-registry-prometheus'
26+
}

‎examples/grpc-observability/backend/src/main/java/net/devh/boot/grpc/examples/observability/backend/BackendApplication.java

Lines changed: 29 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,29 @@
1+
/*
2+
* Copyright (c) 2016-2023 The gRPC-Spring Authors
3+
*
4+
* Licensed under the Apache License, Version 2.0 (the "License");
5+
* you may not use this file except in compliance with the License.
6+
* You may obtain a copy of the License at
7+
*
8+
* http://www.apache.org/licenses/LICENSE-2.0
9+
*
10+
* Unless required by applicable law or agreed to in writing, software
11+
* distributed under the License is distributed on an "AS IS" BASIS,
12+
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13+
* See the License for the specific language governing permissions and
14+
* limitations under the License.
15+
*/
16+
17+
package net.devh.boot.grpc.examples.observability.backend;
18+
19+
import org.springframework.boot.SpringApplication;
20+
import org.springframework.boot.autoconfigure.SpringBootApplication;
21+
22+
@SpringBootApplication
23+
public class BackendApplication {
24+
25+
public static void main(String[] args) {
26+
SpringApplication.run(BackendApplication.class, args);
27+
}
28+
29+
}

‎examples/grpc-observability/backend/src/main/java/net/devh/boot/grpc/examples/observability/backend/ExampleServiceImpl.java

Lines changed: 116 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,116 @@
1+
/*
2+
* Copyright (c) 2016-2023 The gRPC-Spring Authors
3+
*
4+
* Licensed under the Apache License, Version 2.0 (the "License");
5+
* you may not use this file except in compliance with the License.
6+
* You may obtain a copy of the License at
7+
*
8+
* http://www.apache.org/licenses/LICENSE-2.0
9+
*
10+
* Unless required by applicable law or agreed to in writing, software
11+
* distributed under the License is distributed on an "AS IS" BASIS,
12+
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13+
* See the License for the specific language governing permissions and
14+
* limitations under the License.
15+
*/
16+
17+
package net.devh.boot.grpc.examples.observability.backend;
18+
19+
import java.util.concurrent.ThreadLocalRandom;
20+
21+
import io.grpc.Status;
22+
import io.grpc.stub.StreamObserver;
23+
import net.devh.boot.grpc.examples.observability.proto.BidiStreamingRequest;
24+
import net.devh.boot.grpc.examples.observability.proto.BidiStreamingResponse;
25+
import net.devh.boot.grpc.examples.observability.proto.ClientStreamingRequest;
26+
import net.devh.boot.grpc.examples.observability.proto.ClientStreamingResponse;
27+
import net.devh.boot.grpc.examples.observability.proto.ExampleServiceGrpc.ExampleServiceImplBase;
28+
import net.devh.boot.grpc.examples.observability.proto.ServerStreamingRequest;
29+
import net.devh.boot.grpc.examples.observability.proto.ServerStreamingResponse;
30+
import net.devh.boot.grpc.examples.observability.proto.UnaryRequest;
31+
import net.devh.boot.grpc.examples.observability.proto.UnaryResponse;
32+
import net.devh.boot.grpc.server.service.GrpcService;
33+
34+
@GrpcService
35+
public class ExampleServiceImpl extends ExampleServiceImplBase {
36+
37+
private boolean InjectError() {
38+
// We create ~5% error.
39+
return ThreadLocalRandom.current().nextInt(0, 99) >= 95;
40+
}
41+
42+
@Override
43+
public void unaryRpc(UnaryRequest request,
44+
StreamObserver<UnaryResponse> responseObserver) {
45+
if (InjectError()) {
46+
responseObserver.onError(Status.INTERNAL.asException());
47+
} else {
48+
responseObserver.onNext(UnaryResponse.newBuilder().setMessage(request.getMessage()).build());
49+
responseObserver.onCompleted();
50+
}
51+
}
52+
53+
@Override
54+
public StreamObserver<ClientStreamingRequest> clientStreamingRpc(
55+
StreamObserver<ClientStreamingResponse> responseObserver) {
56+
return new StreamObserver<>() {
57+
@Override
58+
public void onNext(ClientStreamingRequest value) {
59+
responseObserver.onNext(
60+
ClientStreamingResponse.newBuilder().setMessage(value.getMessage()).build());
61+
}
62+
63+
@Override
64+
public void onError(Throwable t) {
65+
responseObserver.onError(t);
66+
}
67+
68+
@Override
69+
public void onCompleted() {
70+
if (InjectError()) {
71+
responseObserver.onError(Status.INTERNAL.asException());
72+
} else {
73+
responseObserver.onCompleted();
74+
}
75+
}
76+
};
77+
}
78+
79+
@Override
80+
public void serverStreamingRpc(ServerStreamingRequest request,
81+
StreamObserver<ServerStreamingResponse> responseObserver) {
82+
if (InjectError()) {
83+
responseObserver.onError(Status.INTERNAL.asException());
84+
} else {
85+
responseObserver.onNext(
86+
ServerStreamingResponse.newBuilder().setMessage(request.getMessage()).build());
87+
responseObserver.onCompleted();
88+
}
89+
}
90+
91+
@Override
92+
public StreamObserver<BidiStreamingRequest> bidiStreamingRpc(
93+
StreamObserver<BidiStreamingResponse> responseObserver) {
94+
return new StreamObserver<>() {
95+
@Override
96+
public void onNext(BidiStreamingRequest value) {
97+
responseObserver.onNext(
98+
BidiStreamingResponse.newBuilder().setMessage(value.getMessage()).build());
99+
}
100+
101+
@Override
102+
public void onError(Throwable t) {
103+
responseObserver.onError(t);
104+
}
105+
106+
@Override
107+
public void onCompleted() {
108+
if (InjectError()) {
109+
responseObserver.onError(Status.INTERNAL.asException());
110+
} else {
111+
responseObserver.onCompleted();
112+
}
113+
}
114+
};
115+
}
116+
}

‎examples/grpc-observability/backend/src/main/resources/application.properties

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,7 @@
1+
# Port serves the monitoring traffic.
2+
server.port=8081
3+
# Expose the prometheus metrics via the monitoring port.
4+
# By default, expose on `/actuator/prometheus`.
5+
management.endpoints.web.exposure.include=prometheus
6+
# Port serves the gRPC traffic.
7+
grpc.server.port=9091

‎examples/grpc-observability/frontend/Dockerfile

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,3 @@
1+
FROM eclipse-temurin:17-jdk-alpine
2+
COPY build/libs/frontend.jar frontend.jar
3+
ENTRYPOINT ["java","-jar","/frontend.jar"]

0 commit comments

Comments
 (0)