Skip to content
This repository was archived by the owner on Jul 31, 2023. It is now read-only.

Commit c19efee

Browse files
g-easyg-easy
authored
Add gRPC example. (#63)
1 parent a66d09a commit c19efee

10 files changed

Lines changed: 473 additions & 3 deletions

File tree

‎README.md‎

Lines changed: 4 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -16,6 +16,9 @@ This is not an officially supported Google product.
1616

1717
## Quickstart
1818

19+
Please refer to [`examples/grpc/`](examples/grpc/README.md) for an example RPC
20+
server that integrates gRPC, Stackdriver, and Prometheus.
21+
1922
Please refer to
2023
[`trace/examples/span_example.cc`](opencensus/trace/examples/span_example.cc)
2124
for tracing and
@@ -32,7 +35,7 @@ for stats.
3235

3336
## Language support
3437

35-
* STL is required. (e.g. `libstdc++', 'libc++', etc)
38+
* STL is required. (e.g. `libstdc++`, `libc++`, etc)
3639
* C++11 is required.
3740
* [`absl`](https://github.com/abseil/abseil-cpp/) is used for its building blocks.
3841
* [`googletest`](https://github.com/google/googletest/) is used for tests.

‎examples/grpc/BUILD‎

Lines changed: 80 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,80 @@
1+
# Copyright 2018, OpenCensus 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+
# http://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+
load("//opencensus:copts.bzl", "DEFAULT_COPTS", "TEST_COPTS")
16+
load("@com_github_grpc_grpc//bazel:cc_grpc_library.bzl", "cc_grpc_library")
17+
18+
licenses(["notice"]) # Apache License 2.0
19+
20+
package(default_visibility = ["//visibility:private"])
21+
22+
cc_grpc_library(
23+
name = "hello_proto",
24+
srcs = ["hello.proto"],
25+
generate_mock = False,
26+
proto_only = False,
27+
use_external = True,
28+
well_known_protos = False,
29+
deps = [],
30+
)
31+
32+
cc_library(
33+
name = "stackdriver",
34+
srcs = ["stackdriver.cc"],
35+
hdrs = ["stackdriver.h"],
36+
copts = DEFAULT_COPTS,
37+
deps = [
38+
"//opencensus/exporters/stats/stackdriver:stackdriver_exporter",
39+
"//opencensus/exporters/trace/stackdriver:stackdriver_exporter",
40+
"@com_google_absl//absl/strings",
41+
],
42+
)
43+
44+
cc_binary(
45+
name = "hello_client",
46+
srcs = ["hello_client.cc"],
47+
copts = DEFAULT_COPTS,
48+
deps = [
49+
":hello_proto",
50+
":stackdriver",
51+
"//opencensus/exporters/stats/stackdriver:stackdriver_exporter",
52+
"//opencensus/exporters/stats/stdout:stdout_exporter",
53+
"//opencensus/exporters/trace/stackdriver:stackdriver_exporter",
54+
"//opencensus/exporters/trace/stdout:stdout_exporter",
55+
"//opencensus/plugins/grpc:grpc_plugin",
56+
"//opencensus/trace",
57+
"@com_github_grpc_grpc//:grpc++",
58+
"@com_google_absl//absl/strings",
59+
],
60+
)
61+
62+
cc_binary(
63+
name = "hello_server",
64+
srcs = ["hello_server.cc"],
65+
copts = DEFAULT_COPTS,
66+
deps = [
67+
":hello_proto",
68+
":stackdriver",
69+
"//opencensus/exporters/stats/prometheus:prometheus_exporter",
70+
"//opencensus/exporters/stats/stackdriver:stackdriver_exporter",
71+
"//opencensus/exporters/stats/stdout:stdout_exporter",
72+
"//opencensus/exporters/trace/stackdriver:stackdriver_exporter",
73+
"//opencensus/exporters/trace/stdout:stdout_exporter",
74+
"//opencensus/plugins/grpc:grpc_plugin",
75+
"//opencensus/trace",
76+
"@com_github_grpc_grpc//:grpc++",
77+
"@com_google_absl//absl/strings",
78+
"@prometheus_cpp",
79+
],
80+
)

‎examples/grpc/README.md‎

Lines changed: 97 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,97 @@
1+
# Example RPC server
2+
3+
This example uses:
4+
5+
* gRPC to create an RPC server and client.
6+
* The OpenCensus gRPC plugin to instrument the RPC server.
7+
* The Stackdriver exporter to export stats and traces.
8+
* The Prometheus exporter to export stats.
9+
* Debugging exporters to print stats and traces to stdout.
10+
11+
Usage:
12+
13+
```shell
14+
bazel build :all
15+
../../bazel-bin/examples/grpc/hello_server 9001
16+
../../bazel-bin/examples/grpc/hello_client [::]:9001
17+
```
18+
19+
You can see the Prometheus stats on http://127.0.0.1:8080/metrics
20+
21+
To increase gRPC verbosity, try:
22+
23+
```shell
24+
env GRPC_VERBOSITY=DEBUG ../../bazel-bin/examples/grpc/hello_server 9001
25+
env GRPC_VERBOSITY=DEBUG ../../bazel-bin/examples/grpc/hello_client [::]:9001
26+
```
27+
28+
## Stackdriver
29+
30+
In order to be able to push your stats to [Stackdriver Monitoring](https://cloud.google.com/monitoring/), you must:
31+
32+
1. [Create a Cloud project](https://support.google.com/cloud/answer/6251787?hl=en).
33+
1. [Enable billing](https://support.google.com/cloud/answer/6288653#new-billing).
34+
1. [Enable the Stackdriver Monitoring API](https://app.google.stackdriver.com/).
35+
1. [Make sure you have a Premium Stackdiver account](https://cloud.google.com/monitoring/accounts/tiers).
36+
37+
To use our Stackdriver Stats exporter, your Stackdriver account needs to have
38+
permission to [create custom metrics](https://cloud.google.com/monitoring/custom-metrics/creating-metrics),
39+
and that requires a [Premium tier Stackdriver account](https://cloud.google.com/monitoring/accounts/tiers#this_request_is_only_available_in_the_premium_tier).
40+
Please note that by default all new Stackdriver accounts are Basic tier. To
41+
upgrade to a Premium tier Stackdriver account, follow the instructions
42+
[here](https://cloud.google.com/monitoring/accounts/tiers#start-premium).
43+
44+
## Running the example on GCE
45+
46+
Log in to a GCE instance:
47+
48+
```shell
49+
gcloud compute --project myproject ssh myinstance
50+
```
51+
52+
Install the build tools:
53+
54+
```shell
55+
sudo apt install pkg-config zip g++ zlib1g-dev unzip python
56+
wget https://github.com/bazelbuild/bazel/releases/download/0.11.0/bazel-0.11.0-installer-linux-x86_64.sh
57+
chmod +x bazel-0.11.0-installer-linux-x86_64.sh
58+
./bazel-0.11.0-installer-linux-x86_64.sh --user
59+
```
60+
61+
Build the example:
62+
63+
```shell
64+
git clone https://github.com/census-instrumentation/opencensus-cpp.git
65+
cd opencensus-cpp/examples/grpc
66+
bazel build :all
67+
```
68+
69+
Install the gRPC certificates on the VM: (you only need to do this once)
70+
71+
```shell
72+
sudo mkdir -p /usr/share/grpc
73+
sudo cp $(bazel info output_base)/external/com_github_grpc_grpc/etc/roots.pem /usr/share/grpc/roots.pem
74+
```
75+
76+
Run the server but set `STACKDRIVER_PROJECT_ID`, e.g.:
77+
78+
```shell
79+
env STACKDRIVER_PROJECT_ID=myproject ../../bazel-bin/examples/grpc/hello_server 9001
80+
env STACKDRIVER_PROJECT_ID=myproject ../../bazel-bin/examples/grpc/hello_client [::]:9001
81+
```
82+
83+
When running on GCE, the credentials used to authenticate to Stackdriver are
84+
determined automatically from the VM.
85+
86+
### Stats
87+
88+
Go to https://console.cloud.google.com/monitoring to see stats:
89+
90+
* Click on Resources → Metrics Explorer.
91+
* Choose the "global" Resource Type.
92+
93+
### Tracing
94+
95+
Go to https://console.cloud.google.com/traces/traces to see traces. Example:
96+
97+
![Example trace](https://i.imgur.com/heo9SU8.png)

‎examples/grpc/hello.proto‎

Lines changed: 19 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,19 @@
1+
syntax = "proto3";
2+
3+
package examples;
4+
5+
// The hello service says hello.
6+
service HelloService {
7+
// Sends a greeting.
8+
rpc SayHello (HelloRequest) returns (HelloReply) {}
9+
}
10+
11+
// The request message containing the user's name.
12+
message HelloRequest {
13+
string name = 1;
14+
}
15+
16+
// The response message containing the greeting.
17+
message HelloReply {
18+
string message = 1;
19+
}

‎examples/grpc/hello_client.cc‎

Lines changed: 91 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,91 @@
1+
// Copyright 2018, OpenCensus 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+
// http://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+
#include <cstdlib>
16+
#include <iostream>
17+
#include <memory>
18+
#include <string>
19+
20+
#include <grpc++/grpc++.h>
21+
22+
#include "examples/grpc/hello.grpc.pb.h"
23+
#include "examples/grpc/hello.pb.h"
24+
#include "examples/grpc/stackdriver.h"
25+
#include "opencensus/exporters/stats/stackdriver/stackdriver_exporter.h"
26+
#include "opencensus/exporters/stats/stdout/stdout_exporter.h"
27+
#include "opencensus/exporters/trace/stackdriver/stackdriver_exporter.h"
28+
#include "opencensus/exporters/trace/stdout/stdout_exporter.h"
29+
#include "opencensus/plugins/grpc/grpc_plugin.h"
30+
#include "opencensus/trace/sampler.h"
31+
32+
namespace {
33+
34+
using examples::HelloReply;
35+
using examples::HelloRequest;
36+
using examples::HelloService;
37+
38+
} // namespace
39+
40+
int main(int argc, char** argv) {
41+
if (argc != 2) {
42+
std::cerr << "Usage: " << argv[0] << " host:port\n";
43+
return 1;
44+
}
45+
const std::string hostport = argv[1];
46+
47+
// Register the OpenCensus gRPC plugin to enable stats and tracing in gRPC.
48+
opencensus::RegisterGrpcPlugin();
49+
50+
// Register exporters for Stackdriver.
51+
RegisterStackdriverExporters();
52+
53+
// Trace all outgoing RPCs.
54+
opencensus::trace::TraceConfig::SetCurrentTraceParams(
55+
{128, 128, 128, 128, opencensus::trace::ProbabilitySampler(1.0)});
56+
57+
// For debugging, register exporters that just write to stdout.
58+
opencensus::exporters::stats::StdoutExporter::Register();
59+
opencensus::exporters::trace::StdoutExporter::Register();
60+
61+
// Create a Channel to send RPCs over.
62+
std::shared_ptr<grpc::Channel> channel =
63+
grpc::CreateChannel(hostport, grpc::InsecureChannelCredentials());
64+
std::unique_ptr<HelloService::Stub> stub = HelloService::NewStub(channel);
65+
66+
// Send the RPC.
67+
{
68+
// The client Span ends when ctx falls out of scope.
69+
grpc::ClientContext ctx;
70+
HelloRequest request;
71+
HelloReply reply;
72+
request.set_name("world");
73+
std::cout << "Sending request: \"" << request.ShortDebugString() << "\"\n";
74+
75+
grpc::Status status = stub->SayHello(&ctx, request, &reply);
76+
77+
std::cout << "Got status: " << status.error_code() << ": \""
78+
<< status.error_message() << "\"\n";
79+
std::cout << "Got reply: \"" << reply.ShortDebugString() << "\"\n";
80+
}
81+
82+
// Disable tracing any further RPCs (which will be sent by exporters).
83+
opencensus::trace::TraceConfig::SetCurrentTraceParams(
84+
{128, 128, 128, 128, opencensus::trace::ProbabilitySampler(0.0)});
85+
86+
// Sleep while exporters run in the background.
87+
std::cout << "Client sleeping, ^C to exit.\n";
88+
while (true) {
89+
absl::SleepFor(absl::Seconds(10));
90+
}
91+
}

0 commit comments

Comments
 (0)