google.golang.org/grpc@v1.74.2/README.md (about)

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