Skip to content

Commit d54fde0

Browse files
fengli79fengli79
committed
Add the readme for the grpc-observability example, with corresponding
k8s scripts.
1 parent 4ba09ee commit d54fde0

File tree

4 files changed

+242
-0
lines changed

4 files changed

+242
-0
lines changed

‎examples/grpc-observability/README.md

Lines changed: 129 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,129 @@
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 scrape 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+
kubectl apply -f ./examples/grpc-observability/pod_monitoring.yaml
111+
```
112+
113+
## Set up the Grafana dashboard
114+
115+
Once we have the gRPC metrics scraped by the Prometheus, we may set up a Grafana
116+
server to visualize them.
117+
118+
- Set up a Grafana server, deploy it to a place where can connect the Prometheus
119+
server as its data source.
120+
- Create a Grafana dashboard by importing the
121+
grpc-observability/grafana/prometheus/microservices-grpc-dashboard.json file.
122+
123+
If you
124+
use [Google Managed Prometheus](https://cloud.google.com/stackdriver/docs/managed-prometheus),
125+
you need to follow
126+
the [Grafana Query User Guide](https://cloud.google.com/stackdriver/docs/managed-prometheus/query)
127+
to set up the Grafana server
128+
and [data source syncer](https://github.com/GoogleCloudPlatform/prometheus-engine/tree/main/cmd/datasource-syncer).
129+

‎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/frontend/frontend.yaml

Lines changed: 49 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,49 @@
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: frontend
19+
spec:
20+
replicas: 1
21+
selector:
22+
matchLabels:
23+
app: frontend
24+
template:
25+
metadata:
26+
labels:
27+
app: frontend
28+
monitor: prometheus
29+
spec:
30+
containers:
31+
- name: frontend
32+
# Please upload the docker image of grpc-observability/grpc-spring-example-frontend to an image registry, such as https://cloud.google.com/artifact-registry.
33+
image: <your image of the frontend>
34+
imagePullPolicy: Always
35+
ports:
36+
- name: monitoring
37+
containerPort: 8080
38+
---
39+
apiVersion: v1
40+
kind: Service
41+
metadata:
42+
name: frontend
43+
spec:
44+
clusterIP: None
45+
selector:
46+
app: frontend
47+
ports:
48+
- name: monitoring
49+
port: 8080

‎examples/grpc-observability/pod_monitoring.yaml

Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,12 @@
1+
apiVersion: monitoring.googleapis.com/v1
2+
kind: PodMonitoring
3+
metadata:
4+
name: prometheus
5+
spec:
6+
selector:
7+
matchLabels:
8+
monitor: prometheus
9+
endpoints:
10+
- port: monitoring
11+
path: /actuator/prometheus
12+
interval: 30s

0 commit comments

Comments
 (0)