Jaeger Remote Storage：用 gRPC 共享单节点存储后端的完整部署指南

Jaeger Remote Storage用 gRPC 共享单节点存储后端的完整部署指南【免费下载链接】jaegerCNCF Jaeger, a Distributed Tracing Platform项目地址: https://gitcode.com/GitHub_Trending/ja/jaeger导读jaeger-remote-storage是 CNCF Jaeger 项目中一个独立的可执行程序它把内存memory或 Badger 这类单节点存储实现封装成 gRPC 服务对外暴露 Jaeger Remote Storage gRPC API让 Jaeger 的采集器、查询器等组件可以通过网络远程使用这些存储后端。本文基于 cmd/remote-storage/README.md 及其对应的 入口代码、服务端实现 与示例配置系统讲解该二进制的工作原理、完整配置项、多租户开启方式以及如何与主 Jaeger 进程集成。读完你可以独立搭建一个可对外提供 gRPC 远程存储能力的 Jaeger 存储服务并理解其内部调用链。一、Remote Storage 是什么设计定位与适用场景jaeger-remote-storage的定位在 main.go 中写得很明确它允许共享内存存储或 Badger 等单节点存储实现并实现 Jaeger Remote Storage gRPC API。换句话说它解决的核心问题是存储能力的远程化默认情况下jaeger主进程v2通过jaeger_storage扩展在进程内加载存储后端存储与业务进程强耦合使用jaeger-remote-storage后存储被剥离成独立进程通过标准 gRPC 协议对外服务实现存储与 Jaeger 各组件的解耦部署单机上的内存存储和 Badger 是进程内库无法被其他主机上的 Jaeger 组件直接访问Remote Storage 服务正是为这类后端提供了网络访问入口。从源码结构看jaeger-remote-storage复用了与主jaeger二进制完全一致的存储配置格式app/config.go 中Storage字段的注释明确说明该配置与主jaeger二进制相同但只应定义一个后端因此它本质上是一个存储专用化的轻量服务只负责暴露存储 API不承载采集、查询 UI 等职责。二、构建与启动从源码到运行2.1 构建二进制项目根目录的 Makefile 体系scripts/makefiles/BuildBinaries.mk会构建各 cmd 子目录下的二进制。构建完成后产物即jaeger-remote-storage在 Docker 场景下Dockerfile 将remote-storage-linux-$TARGETARCH复制进镜像并以ENTRYPOINT启动。2.2 命令行启动使用--config-file指定 YAML 配置文件启动./jaeger-remote-storage --config-file config.yaml如果不提供任何配置文件进程也不会拒绝启动。查看 main.go 的loadConfig逻辑当 Viper 未加载到配置文件时会回退到 DefaultConfig()即默认启用memory 存储、监听:17271、max_traces: 1000000并在日志中提示 No configuration file provided, using default configuration (memory storage on :17271)。main.go中还挂载了一组辅助子命令main.go与主jaeger二进制保持一致的使用习惯子命令作用version输出版本信息docs输出命令行帮助文档status查询服务健康状态基于管理端口printconfig打印当前生效配置featuregate查看/切换特性开关2.3 默认端口约定端口定义集中在 ports/ports.go端口用途17271RemoteStorageGRPCgRPC 远程存储 API 服务端口17270RemoteStorageAdminHTTP管理 HTTP 端口健康检查、指标等由flags.NewService(ports.RemoteStorageAdminHTTP)创建三、YAML 配置详解3.1 配置文件总体结构README 给出的最小配置骨架如下对应的完整示例见仓库内 cmd/remote-storage/config.yaml# Server configuration grpc: endpoint: :17271 # gRPC endpoint for remote storage API # Storage configuration storage: backends: default-storage: memory: max_traces: 100000 # Multi-tenancy configuration (optional) multi_tenancy: enabled: false该配置映射到 app/config.go 中的Config结构体type Config struct { GRPC configgrpc.ServerConfig mapstructure:grpc Tenancy tenancy.Options mapstructure:multi_tenancy Storage storageconfig.Config mapstructure:storage }三个顶层段落分别对应grpcgRPC 服务端配置来自 OTel Collector 的configgrpc.ServerConfig支持endpoint、TLS、keepalive 等标准字段storage.backends存储后端定义格式与主 Jaeger 的jaeger_storage扩展完全一致multi_tenancy可选的多租户开关。3.2 校验规则只允许一个后端与主jaeger二进制不同Remote Storage 服务只支持一个存储后端。这是配置校验的硬性约束见 app/config.gofunc (c *Config) Validate() error { // Validate storage configuration if err : c.Storage.Validate(); err ! nil { return err } // Ensure only one backend is defined for remote-storage if len(c.Storage.TraceBackends) 1 { return fmt.Errorf(remote-storage only supports a single storage backend, but %d were configured, len(c.Storage.TraceBackends)) } return nil }对应的测试用例覆盖了各类边界app/config_test.gostorage.backends: {}空 map→ 报错 at least one storage backend is required后端配置为空对象empty-storage: {}→ 同样报错同时配置两个后端 → 报错 remote-storage only supports a single storage backend。如果配置合法GetStorageName()app/config.go会取出第一个后端名称作为实际使用的存储若取不到任何后端main.go 会直接logger.Fatal(No storage backend configured)。3.3 存储后端与主 Jaeger v2 完全一致的格式Remote Storage 的存储配置格式与 Jaeger v2 的jaeger_storage扩展完全相同因此所有官方后端memory、Badger、gRPC 等均可直接复用。README 给出了三种典型配置Memory 存储storage: backends: memory-storage: memory: max_traces: 100000max_traces控制内存中最多保留的 trace 数量超过上限的旧数据会被淘汰。默认配置未提供配置文件时同样使用 memory上限为1_000_000app/config.go。Badger 存储storage: backends: badger-storage: badger: directories: keys: /tmp/jaeger/badger/keys values: /tmp/jaeger/badger/values ephemeral: false ttl: spans: 168h # 7 days仓库自带的 cmd/remote-storage/config-badger.yaml 还补充了维护与指标相关的可选参数storage: backends: badger-storage: badger: directories: keys: /tmp/jaeger/badger/keys values: /tmp/jaeger/badger/values ephemeral: false maintenance_interval: 5m # Badger 后台维护GC、值日志清理间隔 metrics_update_interval: 10s # 存储指标刷新间隔 ttl: spans: 168h # trace 数据存活时间TTL参数说明directories.keys/directories.valuesBadger 键值日志的存储目录分别写入键和值ephemeral: false关闭临时模式数据持久化到磁盘若为true则使用内存临时存储进程退出即丢失maintenance_intervalBadger 值日志value log的压缩/清理周期metrics_update_interval内部指标更新的时间间隔ttl.spansspan 数据的生存期168h即 7 天到期数据自动过期删除。gRPC 存储级联转发storage: backends: grpc-storage: grpc: endpoint: remote-server:17271 tls: insecure: trueRemote Storage 服务同样可以把另一个远程 gRPC 存储当作后端例如做代理/网关此时endpoint指向目标 gRPC 存储地址tls.insecure: true表示明文连接。3.4 多租户Multi-tenancy开启多租户只需将multi_tenancy.enabled置为true并指定租户识别方式grpc: host-port: :17271 multi_tenancy: enabled: true header: x-tenant tenants: - tenant1 - tenant2 storage: backends: default-storage: memory: max_traces: 100000注意 README 中此处grpc段落使用了host-port键名与前面示例的endpoint等价二者均可用于指定监听地址。开启后服务端在 createGRPCServer 中追加十项拦截器tenancy.NewGuardingUnaryInterceptor/tenancy.NewGuardingStreamInterceptor对未携带合法租户信息的请求进行拦截客户端需在请求中携带x-tenant请求头或 gRPC metadata标明所属租户且租户必须位于tenants白名单内app/config_test.go 的用例验证了enabled、header、tenants三个字段能被正确解析。四、服务端实现原理4.1 从存储工厂到 gRPC Handler 的启动链路jaeger-remote-storage的启动流程main.go大致为从配置中取出唯一存储后端名称GetStorageName调用storageconfig.CreateTraceStorageFactory创建存储工厂tracestore.Factory。注意此处传入的认证解析器为nil——Remote Storage 服务自身不做远端认证解析断言工厂同时实现depstore.Factory依赖关系存储接口否则启动失败并提示 Storage does not implement dependency store将工厂交给app.NewServer创建 gRPC 服务并Start主进程通过svc.RunAndThen注册关闭钩子退出时依次关闭 gRPC 服务器与存储工厂main.go。4.2 gRPC 服务内部构造在 server.go 的NewServer中存储工厂被拆分为三个能力组件reader, err : ts.CreateTraceReader() // trace 读取 writer, err : ts.CreateTraceWriter() // trace 写入 depReader, err : ds.CreateDependencyReader() // 依赖关系读取随后grpcstorage.NewHandler(reader, writer, depReader)组装出完整的 v2 存储处理器注册到 gRPC 服务器上server.go 中同时注册了grpc.health.v1.Health健康服务并启用 gRPC reflection。从测试代码 server_test.go 可以看到一个可用的 Remote Storage 服务对外暴露的服务集合为服务作用jaeger.storage.v2.TraceReader读取/查询 tracejaeger.storage.v2.DependencyReader读取服务依赖关系opentelemetry.proto.collector.trace.v1.TraceService接收 OTLP 写入的 trace 数据grpc.health.v1.Health健康检查拦截器链上还挂载了bearertoken.NewUnaryServerInterceptor/bearertoken.NewStreamServerInterceptorserver.go使服务端支持 Bearer Token 认证。4.3 TLS 能力grpc配置段支持 OTel Collector 标准的 TLS 服务端配置。测试 server_test.go 系统地覆盖了 7 种 TLS 场景包括明文连接、客户端不信任服务器证书、主机名不匹配、双向 TLSmTLS以及客户端证书签发 CA 不匹配等可作为配置 mTLS 时的行为参考。五、与 Jaeger 主进程集成要让主jaegerv2进程通过 gRPC 使用 Remote Storage 服务需在其配置的jaeger_storage扩展中把存储后端声明为grpc类型extensions: jaeger_storage: backends: some-storage: grpc: endpoint: localhost:17271 tls: insecure: true仓库提供了完整的集成示例 cmd/jaeger/config-remote-storage.yaml其中还展示了读写分离的配置技巧——查询走 17271写入走独立的 OTLP 端口extensions: jaeger_storage: backends: some-storage: grpc: endpoint: ${env:REMOTE_STORAGE_ENDPOINT:-localhost:17271} tls: insecure: true writer: endpoint: ${env:REMOTE_STORAGE_WRITER_ENDPOINT:-0.0.0.0:4316} tls: insecure: true exporters: jaeger_storage_exporter: trace_storage: some-storage要点说明endpoint指向jaeger-remote-storage的 gRPC 端口Jaeger 从这里读取trace 与依赖关系writer.endpoint可指向 OTLP TraceService 端口用于写入trace 数据允许读写走不同端口/地址两处地址均支持环境变量占位并带默认值便于在不同环境间复用同一份配置。关于客户端侧 gRPC 存储后端的更多细节服务契约、集成测试认证方法等可继续阅读 internal/storage/v2/grpc/README.md。六、验证与测试6.1 使用 gRPC reflection 验证服务端默认启用 gRPC reflection你可以直接用grpcurl列出服务快速确认 Remote Storage 已正常就绪grpcurl -plaintext localhost:17271 list # 预期输出中包含 # jaeger.storage.v2.DependencyReader # jaeger.storage.v2.TraceReader # opentelemetry.proto.collector.trace.v1.TraceService # grpc.health.v1.Health这与 server_test.go 中validateGRPCServer的断言集合一致。6.2 单元测试仓库为 Remote Storage 提供了完整的单元测试app/config_test.go覆盖配置加载、默认配置、非法后端、多后端拒绝、多租户解析等场景app/server_test.go覆盖存储工厂创建失败、端口监听失败、TLS 握手各分支、端口:0随机分配及 gRPC 服务注册正确性app/package_test.go通过testutils.VerifyGoLeaks校验无 goroutine 泄漏。6.3 定制存储的合规认证如果你的目标是自己实现一个自定义 gRPC 存储后端并接入 Jaeger可以运行官方集成测试套件进行合规认证详见 internal/storage/v2/grpc/README.mdSTORAGEgrpc \ CUSTOM_STORAGEtrue \ REMOTE_STORAGE_ENDPOINT${MY_REMOTE_STORAGE_ENDPOINT} \ REMOTE_STORAGE_WRITER_ENDPOINT${MY_REMOTE_STORAGE_WRITER_ENDPOINT} \ PURGER_ENDPOINT${MY_PURGER_ENDPOINT} \ make jaeger-v2-storage-integration-test其中PURGER_ENDPOINT是测试要求后端额外提供的一个 HTTP 清理接口用于在每次测试前重置存储状态。七、完整部署示例7.1 内存后端零配置即可运行# 不传配置自动使用内存存储监听 :17271max_traces1000000 ./jaeger-remote-storage或显式使用 cmd/remote-storage/config.yaml./jaeger-remote-storage --config-file config.yaml7.2 Badger 持久化后端./jaeger-remote-storage --config-file config-badger.yaml对应配置见 cmd/remote-storage/config-badger.yaml数据持久化在/tmp/jaeger/badger/下span 数据保留 7 天。7.3 端到端Remote Storage Jaeger 查询启动 Remote Storage内存或 Badger 后端监听:17271启动主jaeger配置指向cmd/jaeger/config-remote-storage.yaml使其jaeger_storage扩展通过 gRPC 连接 Remote Storage向主 Jaeger 的 OTLP 端口发送 trace 数据写入经独立 writer 端口落入 Remote Storage通过 Jaeger UI默认 16686即可查询到写入的 trace——此时存储已经完全运行在独立进程中主 Jaeger 进程内不再持有存储实例。总结jaeger-remote-storage把 Jaeger 的存储能力从进程内解耦为独立 gRPC 服务它以与主二进制完全一致的storage.backends配置格式支持 memory、Badger 等后端通过jaeger.storage.v2系列 API OTLP TraceService 对外提供服务并内置健康检查、gRPC reflection、Bearer Token 认证、多租户与完整 TLS 支持。无论是想在多机环境中共享单机存储、把存储独立扩容还是为自定义 gRPC 存储后端做合规接入它都是一个轻量且标准的落地方案。【免费下载链接】jaegerCNCF Jaeger, a Distributed Tracing Platform项目地址: https://gitcode.com/GitHub_Trending/ja/jaeger创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考