channelz

README

go-grpc-channelz

An in-process Channelz UI for gRPC in Golang

What is Channelz?

Channelz is a gRPC spec for introspection into gRPC channels. Channels in gRPC represent connections and sockets. Channelz provides introspection into the current active grpc connections, including incoming and outgoing connections. The full spec can be found here

What is go-grpc-channelz?

go-grpc-channelz provides a web UI to view the current start of all gRPC channels. For each channel you'd be able to look into the remote peer, sub-channels, load balancing stategies, number of calls, socket activity and events and so on.

You install go-grpc-channelz into your service and expose it's web page and that's it. All in all, about 2-5 lines of code.

Screenshots

Usage

Channelz is implemented as a gRPC service. This service is turned off by by default, so you have to turn it on as so:

import (
	channelzservice "google.golang.org/grpc/channelz/service"
)

// Register the channelz gRPC service to grpcServer so that we can query it for this service.
channelzservice.RegisterChannelzServiceToServer(grpcServer)

In this example grpcServer is a grpc server that you create externally. In many cases this server already exists (you only need one) but if not then here's how to create it:

import "google.golang.org/grpc"

grpcServer := grpc.NewServer()

Now you should register the channelz web handler:

import channelz "github.com/rantav/go-grpc-channelz"

// Register the channelz handler and mount it to /foo.
// Resources will be available at /foo/channelz
http.Handle("/", channelz.CreateHandler("/foo", grpcBindAddress))

Where grpcBindAddress is the address to which grpcServer is bound. This could be for example ":8080" or "localhost:8080" etc. This address is required because the channelz web service accesses the channelz grpc service in order to query it.

Lastly, launch that web listener in order to serve the web UI:

// Listen and serve HTTP for the default serve mux
adminListener, err := net.Listen("tcp", ":8081")
if err != nil {
    log.Fatal(err)
}
go http.Serve(adminListener, nil)

Now the service will be available at http://localhost:8081/foo/channelz

A complete example:

import (
    "google.golang.org/grpc"
    channelzservice "google.golang.org/grpc/channelz/service"
    channelz "github.com/rantav/go-grpc-channelz"
)

grpcServer := grpc.NewServer()

// Register the channelz handler
http.Handle("/", channelz.CreateHandler("/foo", grpcBindAddress))

// Register the channelz gRPC service to grpcServer so that we can query it for this service.
channelzservice.RegisterChannelzServiceToServer(grpcServer)

// Listen and serve HTTP for the default serve mux
adminListener, err := net.Listen("tcp", ":8081")
if err != nil {
    log.Fatal(err)
}
go http.Serve(adminListener, nil)

Documentation

Index

• func CreateHandler(pathPrefix, grpcBindAddress string) http.Handler
• func CreateHandlerWithDialOpts(pathPrefix, grpcBindAddress string, dialOpts ...grpc.DialOption) http.Handler

Functions

func CreateHandler

func CreateHandler(pathPrefix, grpcBindAddress string) http.Handler

CreateHandler creates an http handler with the routes of channelz mounted to the provided prefix. pathPrefix is the prefix to which /channelz will be prepended grpcBindAddress is the TCP bind address for the gRPC service you'd like to monitor. grpcBindAddress is required since the channelz interface connects to this gRPC service. Typically you'd use the return value of CreateHandler as an argument to http.Handle For example:

http.Handle("/", channelz.CreateHandler("/foo", grpcBindAddress))

grpc.Dial is called using grpc.WithTransportCredentials(insecure.NewCredentials()). If you need custom DialOptions like credentials, TLS or interceptors, please refer to CreateHandlerWithDialOpts().

func CreateHandlerWithDialOpts

func CreateHandlerWithDialOpts(pathPrefix, grpcBindAddress string, dialOpts ...grpc.DialOption) http.Handler

CreateHandlerWithDialOpts is the same as CreateHandler but with custom []grpc.DialOption You need to provide all grpc.DialOption to be used for the internal call to grpc.Dial(). This typically includes some form of grpc.WithTransportCredentials(). Here's an example on how to use a bufconn instead of a real TCP listener: lis := bufconn.Listen(1024 * 1024) grpcserver.Serve(lis) http.Handle("/", channelzWeb.CreateHandlerWithDialOpts("/", "",

[]grpc.DialOption{
	grpc.WithTransportCredentials(insecure.NewCredentials()),
	grpc.WithContextDialer(func(ctx context.Context, s string) (net.Conn, error) {
		return lis.DialContext(ctx)
	}),
}...,

))