chainguard-dev/go-grpc-kit

# gRPC Kit 用于 Go 的 gRPC 工具库 — 提供双工服务（gRPC + grpc-gateway）， Prometheus 指标、OpenTelemetry 链路追踪、客户端身份传播以及 预配置的拨号选项。 ## 包 ### `pkg/duplex` — 双工 gRPC + REST 网关服务器 在同一端口上同时提供 gRPC 和 [gRPC Gateway](https://grpc-ecosystem.github.io/grpc-gateway/) 服务。 支持通过 context 取消来实现优雅关闭。 ``` d := duplex.New(8080, grpc.ChainUnaryInterceptor(metrics.UnaryServerInterceptor()), ) pb.RegisterTypeServer(d.Server, impl.NewTypeServer()) if err := d.RegisterHandler(ctx, pb.RegisterTypeHandlerFromEndpoint); err != nil { log.Panicf("Failed to register gateway endpoint: %v", err) } if err := d.ListenAndServe(ctx); err != nil { log.Panicf("ListenAndServe() = %v", err) } ``` `duplex.New` 接受 `grpc.ServerOption`、`runtime.ServeMuxOption` 和 `grpc.DialOption`（用于内部回环连接）。 ### `pkg/options` — gRPC 客户端拨号选项 专为生产环境预配置的 gRPC 拨号选项： - **`GRPCOptions(url)`** — 返回 URL 的目标地址和拨号选项。 支持 `http`、`https`、`unix`、`bufnet` 和测试监听器方案。 - **`GRPCDialOptions()`** — 包含 OTEL 链路追踪、 Prometheus 客户端指标、客户端身份传播和重试支持的标准拨号选项。 - **`LoopbackDialOptions()`** — 用于 grpc-gateway 回环连接的精简拨号选项，省略了指标/追踪以避免重复计算。 - **`ClientOptions()`** — 将 `GRPCDialOptions()` 包装为 `google.golang.org/api/option.ClientOption`。 通过环境变量进行配置： | 变量 | 默认值 | 描述 | |----------|---------|-------------| | `ENABLE_CLIENT_HANDLING_TIME_HISTOGRAM` | `true` | 启用客户端处理时间直方图 | | `ENABLE_CLIENT_STREAM_RECEIVE_TIME_HISTOGRAM` | `true` | 启用客户端流接收直方图 | | `ENABLE_CLIENT_STREAM_SEND_TIME_HISTOGRAM` | `true` | 启用客户端流发送直方图 | | `GRPC_CLIENT_MAX_RETRY` | `0` | 最大重试次数（0 表示禁用） | ### `pkg/metrics` — Prometheus 指标与 OpenTelemetry 链路追踪 - **`UnaryServerInterceptor()`** / **`StreamServerInterceptor()`** — gRPC 服务器拦截器，记录带有 `cgclientid` 标签的 Prometheus 指标。 - **`SetupTracer(ctx)`** — 使用 OTLP gRPC 导出器初始化 OpenTelemetry 链路追踪。返回一个关闭函数。 - **`RegisterListenAndServe(server, addr, enablePprof)`** — 在后台启动一个指标 HTTP 服务器，提供 `/metrics` 以及可选的 `/debug/pprof/` 服务。 ### `pkg/trace` — Cloud Run Traceparent 保留 Cloud Run 可能会替换 `traceparent` 标头，从而导致丢失 span 上下文。此 包提供了 stats handler 来解决此问题： - **`PreserveTraceParentHandler`** — 客户端 handler，将 传出的 `traceparent` 复制到 `original-traceparent`。 - **`RestoreTraceParentHandler`** — 服务端 handler，如果 Cloud Run 替换了 `traceparent`，则从 `original-traceparent` 中恢复它。 用于可观测性的 Prometheus 计数器： `grpc_traceparent_preserved_total`、`grpc_traceparent_restore_attempted_total`、 `grpc_traceparent_restored_total`。 ### `pkg/interceptors/clientid` — 客户端身份传播 通过 gRPC metadata 自动传播调用者身份： - **`UnaryClientInterceptor()`** / **`StreamClientInterceptor()`** — 将 `cgclientid`（服务身份）和 `cgrequestid`（每次调用唯一的 UUID） 添加到传出的 metadata 中。 客户端 ID 解析顺序：`K_SERVICE` 环境变量 → `CG_CLIENT_ID` 环境变量 → 可执行文件路径。

标签：EVTX分析, GET参数, Go, gRPC, grpc-gateway, OpenTelemetry, Python工具, Ruby工具, SOC Prime, 开发工具, 日志审计, 用户代理, 自定义请求头