Skip to content

Commit d97ea70

Browse files
nexcodenexcode
committed
Improve README and examples
1 parent c189d73 commit d97ea70

2 files changed

Lines changed: 90 additions & 28 deletions

File tree

‎README.md‎

Lines changed: 86 additions & 28 deletions
Original file line numberDiff line numberDiff line change
@@ -5,13 +5,13 @@
55
[![GoReportCard](https://goreportcard.com/badge/github.com/nexcode/rpcplatform)](https://goreportcard.com/report/github.com/nexcode/rpcplatform)
66
[![CodeCov](https://codecov.io/gh/nexcode/rpcplatform/graph/badge.svg)](https://codecov.io/gh/nexcode/rpcplatform)
77

8-
An `easy-to-use` platform for creating microservices without complex infrastructure dependencies.
9-
Only [etcd](https://etcd.io) is required. Out of the box you get service discovery, tracing between
10-
services and other useful features. [gRPC](https://grpc.io) is used for communication between services.
8+
An **easy-to-use** platform for building microservices without complex infrastructure dependencies.
9+
Only [etcd](https://etcd.io) is required. Out of the box, you get service discovery, distributed tracing, and other useful features.
10+
[gRPC](https://grpc.io) is used for communication between services.
1111

1212
## etcd is required
1313

14-
If there is no etcd in your infrastructure, you can run it via
14+
If you don't have etcd in your infrastructure, you can run it via
1515
[Docker](https://etcd.io/docs/v3.6/op-guide/container/) for testing:
1616

1717
```shell
@@ -28,38 +28,98 @@ Just remember that the example above is for testing purposes!
2828

2929
## How does it work?
3030

31-
All you need to do is assign a name to your server. When it starts, it will automatically select a free port and listen on it (unless you specify otherwise).
32-
All clients will connect to this server by its name. If there are multiple servers with the same name, load balancing is distributed among them.
31+
All you need to do is assign a name to your server. When it starts, it automatically selects an available port and listens on it (unless you specify otherwise).
32+
All clients will connect to this server by its name. If there are multiple server instances with the same name, the load is automatically distributed among them.
3333

3434
> In the following code examples, error handling is omitted to improve readability. A pre-built [proto](examples/quickstart/proto) will also be used.
3535
36-
First, let's create a new `rpcplatform` instance:
36+
First, let's create a new `rpcplatform` instance and a new server named `myServerName`, register the implementation of our `Sum` service, and run it on localhost:
3737

3838
```go
39-
rpcp, err := rpcplatform.New("rpcplatform", etcdClient,
40-
rpcplatform.PlatformOptions.ClientOptions(
41-
rpcplatform.ClientOptions.GRPCOptions(grpc.WithTransportCredentials(insecure.NewCredentials())),
42-
),
39+
package main
40+
41+
import (
42+
"context"
43+
44+
"github.com/nexcode/rpcplatform"
45+
"github.com/nexcode/rpcplatform/examples/quickstart/proto"
46+
etcd "go.etcd.io/etcd/client/v3"
47+
"google.golang.org/grpc"
48+
"google.golang.org/grpc/credentials/insecure"
4349
)
50+
51+
type sumServer struct {
52+
proto.UnimplementedSumServer
53+
}
54+
55+
func (s *sumServer) Sum(_ context.Context, request *proto.SumRequest) (*proto.SumResponse, error) {
56+
return proto.SumResponse_builder{
57+
Sum: new(request.GetA() + request.GetB()),
58+
}.Build(), nil
59+
}
60+
61+
func main() {
62+
etcdClient, _ := etcd.New(etcd.Config{
63+
Endpoints: []string{"localhost:2379"},
64+
})
65+
66+
rpcp, _ := rpcplatform.New("rpcplatform", etcdClient,
67+
rpcplatform.PlatformOptions.ClientOptions(
68+
rpcplatform.ClientOptions.GRPCOptions(grpc.WithTransportCredentials(insecure.NewCredentials())),
69+
),
70+
)
71+
72+
server, _ := rpcp.NewServer("myServerName", "localhost:")
73+
proto.RegisterSumServer(server.Server(), &sumServer{})
74+
_ = server.Serve()
75+
}
4476
```
4577

46-
Now let's create a new server named `myServerName`, register the implementation of our `Sum` service and run it on localhost (`sumServer` implementation is omitted):
78+
For the client, we also create a new `rpcplatform` instance and a new client named `myServerName`:
4779

4880
```go
49-
server, err := rpcp.NewServer("myServerName", "localhost:")
50-
proto.RegisterSumServer(server.Server(), &sumServer{})
51-
err = server.Serve()
52-
```
81+
package main
82+
83+
import (
84+
"context"
85+
"fmt"
86+
"math/rand/v2"
87+
88+
"github.com/nexcode/rpcplatform"
89+
"github.com/nexcode/rpcplatform/examples/quickstart/proto"
90+
etcd "go.etcd.io/etcd/client/v3"
91+
"google.golang.org/grpc"
92+
"google.golang.org/grpc/credentials/insecure"
93+
)
5394

54-
And finally, we create a client that connects to our `myServerName` (`sumClient` usage is omitted):
95+
func main() {
96+
etcdClient, _ := etcd.New(etcd.Config{
97+
Endpoints: []string{"localhost:2379"},
98+
})
5599

56-
```go
57-
client, err := rpcp.NewClient("myServerName")
58-
sumClient := proto.NewSumClient(client.Client())
100+
rpcp, _ := rpcplatform.New("rpcplatform", etcdClient,
101+
rpcplatform.PlatformOptions.ClientOptions(
102+
rpcplatform.ClientOptions.GRPCOptions(grpc.WithTransportCredentials(insecure.NewCredentials())),
103+
),
104+
)
105+
106+
client, _ := rpcp.NewClient("myServerName")
107+
sumClient := proto.NewSumClient(client.Client())
108+
109+
resp, _ := sumClient.Sum(context.Background(), proto.SumRequest_builder{
110+
A: new(int64(rand.IntN(10))),
111+
B: new(int64(rand.IntN(10))),
112+
}.Build())
113+
114+
fmt.Println(resp.GetSum())
115+
}
59116
```
60117

61118
This setup is fully functional: you can add or remove copies of your server and create new clients dynamically.
62-
But to see our **service graph** and get **telemetry for all gRPC methods**, we need to run containers with telemetry services and enable telemetry in `rpcplatform`.
119+
120+
### OpenTelemetry
121+
122+
To visualize our **service graph** and get **telemetry for all gRPC methods**, we need to run containers with telemetry services and enable telemetry in `rpcplatform`.
63123

64124
Let's run containers with Zipkin and Jaeger:
65125

@@ -71,16 +131,14 @@ docker run -d --name jaeger -p 16686:16686 -p 4317:4317 jaegertracing/all-in-one
71131
Now let's create the necessary collectors and add the `OpenTelemetry` option to the `rpcplatform` instance:
72132

73133
```go
74-
otlpExporter, err := otlptracegrpc.New(context.Background(),
134+
otlpExporter, _ := otlptracegrpc.New(context.Background(),
75135
otlptracegrpc.WithEndpoint("localhost:4317"), otlptracegrpc.WithInsecure(),
76136
)
77137

78-
zipkinExporter, err := zipkin.New("http://localhost:9411/api/v2/spans")
138+
zipkinExporter, _ := zipkin.New("http://localhost:9411/api/v2/spans")
79139

80-
rpcp, err := rpcplatform.New("rpcplatform", etcdClient,
81-
rpcplatform.PlatformOptions.ClientOptions(
82-
rpcplatform.ClientOptions.GRPCOptions(grpc.WithTransportCredentials(insecure.NewCredentials())),
83-
),
140+
rpcp, _ := rpcplatform.New("rpcplatform", etcdClient,
141+
// other options...
84142
rpcplatform.PlatformOptions.OpenTelemetry("myServiceName", 1, otlpExporter, zipkinExporter),
85143
)
86144
```
@@ -91,7 +149,7 @@ The tracing dashboards are available at:
91149
| :------------------------------------------: | :------------------------------------------: |
92150
| ![Zipkin](examples/opentelemetry/zipkin.png) | ![Jaeger](examples/opentelemetry/jaeger.png) |
93151

94-
## Usage examples (with source code)
152+
## Usage examples
95153

96154
- [QuickStart](examples/quickstart): contains the simplest example without additional features
97155
- [OpenTelemetry](examples/opentelemetry): example integrating distributed tracing systems

‎examples/quickstart/server/main.go‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -58,6 +58,10 @@ func main() {
5858
),
5959
)
6060

61+
if err != nil {
62+
panic(err)
63+
}
64+
6165
server, err := rpcp.NewServer("myServerName", "localhost:")
6266
if err != nil {
6367
panic(err)

0 commit comments

Comments
 (0)