README.md
1# gRPC-Go
2
3[![Build Status](https://travis-ci.org/grpc/grpc-go.svg)](https://travis-ci.org/grpc/grpc-go)
4[![GoDoc](https://pkg.go.dev/badge/google.golang.org/grpc)][API]
5[![GoReportCard](https://goreportcard.com/badge/grpc/grpc-go)](https://goreportcard.com/report/github.com/grpc/grpc-go)
6
7The [Go][] implementation of [gRPC][]: A high performance, open source, general
8RPC framework that puts mobile and HTTP/2 first. For more information see the
9[Go gRPC docs][], or jump directly into the [quick start][].
10
11## Prerequisites
12
13- **[Go][]**: any one of the **three latest major** [releases][go-releases].
14
15## Installation
16
17With [Go module][] support (Go 1.11+), simply add the following import
18
19```go
20import "google.golang.org/grpc"
21```
22
23to your code, and then `go [build|run|test]` will automatically fetch the
24necessary dependencies.
25
26Otherwise, to install the `grpc-go` package, run the following command:
27
28```console
29$ go get -u google.golang.org/grpc
30```
31
32> **Note:** If you are trying to access `grpc-go` from **China**, see the
33> [FAQ](#FAQ) below.
34
35## Learn more
36
37- [Go gRPC docs][], which include a [quick start][] and [API
38 reference][API] among other resources
39- [Low-level technical docs](Documentation) from this repository
40- [Performance benchmark][]
41- [Examples](examples)
42
43## FAQ
44
45### I/O Timeout Errors
46
47The `golang.org` domain may be blocked from some countries. `go get` usually
48produces an error like the following when this happens:
49
50```console
51$ go get -u google.golang.org/grpc
52package google.golang.org/grpc: unrecognized import path "google.golang.org/grpc" (https fetch: Get https://google.golang.org/grpc?go-get=1: dial tcp 216.239.37.1:443: i/o timeout)
53```
54
55To build Go code, there are several options:
56
57- Set up a VPN and access google.golang.org through that.
58
59- Without Go module support: `git clone` the repo manually:
60
61 ```sh
62 git clone https://github.com/grpc/grpc-go.git $GOPATH/src/google.golang.org/grpc
63 ```
64
65 You will need to do the same for all of grpc's dependencies in `golang.org`,
66 e.g. `golang.org/x/net`.
67
68- With Go module support: it is possible to use the `replace` feature of `go
69 mod` to create aliases for golang.org packages. In your project's directory:
70
71 ```sh
72 go mod edit -replace=google.golang.org/grpc=github.com/grpc/grpc-go@latest
73 go mod tidy
74 go mod vendor
75 go build -mod=vendor
76 ```
77
78 Again, this will need to be done for all transitive dependencies hosted on
79 golang.org as well. For details, refer to [golang/go issue #28652](https://github.com/golang/go/issues/28652).
80
81### Compiling error, undefined: grpc.SupportPackageIsVersion
82
83#### If you are using Go modules:
84
85Ensure your gRPC-Go version is `require`d at the appropriate version in
86the same module containing the generated `.pb.go` files. For example,
87`SupportPackageIsVersion6` needs `v1.27.0`, so in your `go.mod` file:
88
89```go
90module <your module name>
91
92require (
93 google.golang.org/grpc v1.27.0
94)
95```
96
97#### If you are *not* using Go modules:
98
99Update the `proto` package, gRPC package, and rebuild the `.proto` files:
100
101```sh
102go get -u github.com/golang/protobuf/{proto,protoc-gen-go}
103go get -u google.golang.org/grpc
104protoc --go_out=plugins=grpc:. *.proto
105```
106
107### How to turn on logging
108
109The default logger is controlled by environment variables. Turn everything on
110like this:
111
112```console
113$ export GRPC_GO_LOG_VERBOSITY_LEVEL=99
114$ export GRPC_GO_LOG_SEVERITY_LEVEL=info
115```
116
117### The RPC failed with error `"code = Unavailable desc = transport is closing"`
118
119This error means the connection the RPC is using was closed, and there are many
120possible reasons, including:
121 1. mis-configured transport credentials, connection failed on handshaking
122 1. bytes disrupted, possibly by a proxy in between
123 1. server shutdown
124 1. Keepalive parameters caused connection shutdown, for example if you have configured
125 your server to terminate connections regularly to [trigger DNS lookups](https://github.com/grpc/grpc-go/issues/3170#issuecomment-552517779).
126 If this is the case, you may want to increase your [MaxConnectionAgeGrace](https://pkg.go.dev/google.golang.org/grpc/keepalive?tab=doc#ServerParameters),
127 to allow longer RPC calls to finish.
128
129It can be tricky to debug this because the error happens on the client side but
130the root cause of the connection being closed is on the server side. Turn on
131logging on __both client and server__, and see if there are any transport
132errors.
133
134[API]: https://pkg.go.dev/google.golang.org/grpc
135[Go]: https://golang.org
136[Go module]: https://github.com/golang/go/wiki/Modules
137[gRPC]: https://grpc.io
138[Go gRPC docs]: https://grpc.io/docs/languages/go
139[Performance benchmark]: https://performance-dot-grpc-testing.appspot.com/explore?dashboard=5180705743044608
140[quick start]: https://grpc.io/docs/languages/go/quickstart
141[go-releases]: https://golang.org/doc/devel/release.html
142