架构与系统设计 / 系统课时
用 Channelz 排查连接与子通道
用 Channelz 排查连接与子通道
当客户端已经拿到服务地址,却长期没有可用后端时,单看 DNS、错误码或业务日志往往只能看到表象。Channelz 可以把客户端 Channel、负载均衡器创建的 Subchannel 与底层 Socket 串起来,帮助你判断问题停在解析、建连、握手还是后端选择阶段。
学习目标
- 读懂 Channel、Subchannel、Socket 的职责与连接状态
- 按“顶层 Channel → 子通道 → Socket”的顺序缩小故障范围
- 定位“解析正常但没有 READY 后端”等典型连接问题
先在正确的进程里暴露 Channelz
Channelz 记录的是当前进程内的 gRPC 对象。要排查某个客户端的出站连接,就必须在持有这个客户端 Channel 的进程里暴露 Channelz;查询远端服务端进程,无法看到本地客户端的 Subchannel。
在 gRPC-Go 中,可在同一业务进程里增加一个仅供运维访问的管理端口。下面是片段示例,应放在业务进程初始化阶段,并在进程退出时一起关闭。
import (
"net"
"google.golang.org/grpc"
channelzservice "google.golang.org/grpc/channelz/service"
)
func startChannelzAdmin() (*grpc.Server, error) {
lis, err := net.Listen("tcp", "127.0.0.1:19090")
if err != nil {
return nil, err
}
adminServer := grpc.NewServer()
// Channelz 数据来自当前业务进程,管理端口只负责把这些数据暴露出来。
channelzservice.RegisterChannelzServiceToServer(adminServer)
go func() {
_ = adminServer.Serve(lis)
}()
return adminServer, nil
}该片段不会创建新的业务 Channel,只会把当前进程已有的 Channelz 数据暴露在 127.0.0.1:19090。生产环境不要把该端口直接暴露到公网,应使用回环地址、网络策略或独立管理网络限制访问。
沿层级读取真实连接状态
顶层 Channel 是应用直接创建的逻辑通道;负载均衡器通常会在其下维护一个或多个 Subchannel;真正建立起来的传输连接最终落到 Socket。Channelz 也允许 Channel 引用子 Channel,因此严格来说不是固定三层树,但排查常见客户端连接时,可以先沿 Channel → Subchannel → Socket 下钻。

下面的完整程序直接调用标准 grpc.channelz.v1.Channelz 服务。默认列出顶层 Channel,也可以按 ID 继续读取 Channel、Subchannel 或 Socket。
package main
import (
"context"
"flag"
"fmt"
"log"
"time"
"google.golang.org/grpc"
channelzpb "google.golang.org/grpc/channelz/grpc_channelz_v1"
"google.golang.org/grpc/credentials/insecure"
"google.golang.org/protobuf/encoding/protojson"
"google.golang.org/protobuf/proto"
)
func main() {
target := flag.String("target", "127.0.0.1:19090", "Channelz admin address")
kind := flag.String("kind", "top", "top|channel|subchannel|socket")
id := flag.Int64("id", 0, "entity id for channel/subchannel/socket")
flag.Parse()
conn, err := grpc.NewClient(*target, grpc.WithTransportCredentials(insecure.NewCredentials()))
if err != nil {
log.Fatal(err)
}
defer conn.Close()
client := channelzpb.NewChannelzClient(conn)
ctx, cancel := context.WithTimeout(context.Background(), 3*time.Second)
defer cancel()
var msg proto.Message
switch *kind {
case "top":
msg, err = client.GetTopChannels(ctx, &channelzpb.GetTopChannelsRequest{MaxResults: 50})
case "channel":
msg, err = client.GetChannel(ctx, &channelzpb.GetChannelRequest{ChannelId: *id})
case "subchannel":
msg, err = client.GetSubchannel(ctx, &channelzpb.GetSubchannelRequest{SubchannelId: *id})
case "socket":
msg, err = client.GetSocket(ctx, &channelzpb.GetSocketRequest{SocketId: *id})
default:
log.Fatalf("unknown kind %q", *kind)
}
if err != nil {
log.Fatal(err)
}
out, err := protojson.MarshalOptions{Indent: " "}.Marshal(msg)
if err != nil {
log.Fatal(err)
}
fmt.Println(string(out))
}预期结果:程序保存为 channelz-dump.go 后可以按 -kind 查询对应的 Channelz 实体;具体 ID、地址和计数由被检查进程的实时状态决定。
先执行顶层查询:
go run channelz-dump.go -target 127.0.0.1:19090 -kind top预期输出会包含当前进程的顶层 Channel、目标地址和连接状态。Channelz ID 会随进程变化:
{
"channel": [
{
"ref": {
"channelId": "<ID>"
},
"data": {
"state": {
"state": "READY"
},
"target": "dns:///orders.internal:50051"
},
"subchannelRef": [
{
"subchannelId": "<ID>"
}
]
}
],
"end": true
}拿到 subchannelId 后继续下钻:
go run channelz-dump.go -target 127.0.0.1:19090 -kind subchannel -id <ID>预期输出中应看到该 Subchannel 的状态;连接已经建立时通常还能看到 socketRef:
{
"subchannel": {
"ref": {
"subchannelId": "<ID>"
},
"data": {
"state": {
"state": "READY"
}
},
"socketRef": [
{
"socketId": "<ID>"
}
]
}
}再用 socketId 查询 Socket,就能检查实际远端地址以及流、消息和传输统计。实际地址、计数和 ID 都可能不同。
用状态组合判断卡在哪一层
如果顶层 Channel 是 IDLE,先确认是否真的发起过 RPC;仅创建客户端并不代表一定已经触发解析和建连。若 Channel 已进入 CONNECTING 或 TRANSIENT_FAILURE,再看它是否已经产生 Subchannel。
“DNS 工具能解析”但 Channel 下没有预期的 Subchannel,重点检查 gRPC 使用的 target、resolver scheme、Service Config 与负载均衡配置。系统 dig 成功只能证明系统解析链路可用,不能证明 gRPC resolver 已经把同一批地址提交给负载均衡器。
如果 Subchannel 已存在但全部处于 CONNECTING 或 TRANSIENT_FAILURE,说明候选后端已经进入连接层,问题更可能在路由、防火墙、端口、TLS 握手、后端监听状态或连接退避。此时不要继续反复检查 DNS,而应结合 Channel trace、连接日志和后端监听状态确认失败点。
如果至少一个 Subchannel 为 READY,说明已经存在可用传输。若业务 RPC 仍持续失败,应继续核对负载均衡选择、RPC 状态码、服务端健康状态与 Socket 统计,而不是把问题归因于“没有建立连接”。