1# gRPC-Go
2
3[][API]
4[](https://goreportcard.com/report/github.com/grpc/grpc-go)
5[](https://codecov.io/gh/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
17Simply add the following import to your code, and then `go [build|run|test]`
18will automatically fetch the necessary dependencies:
19
20
21```go
22import "google.golang.org/grpc"
23```
24
25> **Note:** If you are trying to access `grpc-go` from **China**, see the
26> [FAQ](#FAQ) below.
27
28## Learn more
29
30- [Go gRPC docs][], which include a [quick start][] and [API
31 reference][API] among other resources
32- [Low-level technical docs](Documentation) from this repository
33- [Performance benchmark][]
34- [Examples](examples)
35
36## FAQ
37
38### I/O Timeout Errors
39
40The `golang.org` domain may be blocked from some countries. `go get` usually
41produces an error like the following when this happens:
42
43```console
44$ go get -u google.golang.org/grpc
45package 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)
46```
47
48To build Go code, there are several options:
49
50- Set up a VPN and access google.golang.org through that.
51
52- With Go module support: it is possible to use the `replace` feature of `go
53 mod` to create aliases for golang.org packages. In your project's directory:
54
55 ```sh
56 go mod edit -replace=google.golang.org/grpc=github.com/grpc/grpc-go@latest
57 go mod tidy
58 go mod vendor
59 go build -mod=vendor
60 ```
61
62 Again, this will need to be done for all transitive dependencies hosted on
63 golang.org as well. For details, refer to [golang/go issue
64 #28652](https://github.com/golang/go/issues/28652).
65
66### Compiling error, undefined: grpc.SupportPackageIsVersion
67
68Please update to the latest version of gRPC-Go using
69`go get google.golang.org/grpc`.
70
71### How to turn on logging
72
73The default logger is controlled by environment variables. Turn everything on
74like this:
75
76```console
77$ export GRPC_GO_LOG_VERBOSITY_LEVEL=99
78$ export GRPC_GO_LOG_SEVERITY_LEVEL=info
79```
80
81### The RPC failed with error `"code = Unavailable desc = transport is closing"`
82
83This error means the connection the RPC is using was closed, and there are many
84possible reasons, including:
85 1. mis-configured transport credentials, connection failed on handshaking
86 1. bytes disrupted, possibly by a proxy in between
87 1. server shutdown
88 1. Keepalive parameters caused connection shutdown, for example if you have
89 configured your server to terminate connections regularly to [trigger DNS
90 lookups](https://github.com/grpc/grpc-go/issues/3170#issuecomment-552517779).
91 If this is the case, you may want to increase your
92 [MaxConnectionAgeGrace](https://pkg.go.dev/google.golang.org/grpc/keepalive?tab=doc#ServerParameters),
93 to allow longer RPC calls to finish.
94
95It can be tricky to debug this because the error happens on the client side but
96the root cause of the connection being closed is on the server side. Turn on
97logging on __both client and server__, and see if there are any transport
98errors.
99
100[API]: https://pkg.go.dev/google.golang.org/grpc
101[Go]: https://golang.org
102[Go module]: https://github.com/golang/go/wiki/Modules
103[gRPC]: https://grpc.io
104[Go gRPC docs]: https://grpc.io/docs/languages/go
105[Performance benchmark]: https://performance-dot-grpc-testing.appspot.com/explore?dashboard=5180705743044608
106[quick start]: https://grpc.io/docs/languages/go/quickstart
107[go-releases]: https://golang.org/doc/devel/release.html
View as plain text