Grafana Tempo 在 HashiCorp Nomad 上的单二进制Monolithic部署指南【免费下载链接】tempoGrafana Tempo is a high volume, minimal dependency distributed tracing backend.项目地址: https://gitcode.com/GitHub_Trending/tempo1/tempo本指南基于仓库 example/nomad/tempo-monolith 目录下的 Nomad 作业定义系统讲解如何用一条nomad job run命令在 HashiCorp Nomad 集群中以单二进制monolithic模式部署 Grafana Tempo 并使用 S3 兼容对象存储作为后端。读完本文你将掌握tempo.hcl中每个变量与配置段的含义、端口与健康检查的编排方式以及-targetall、-config.expand-env等启动参数在 Tempo 源码中的真实作用可直接照搬到自己的 Nomad 环境。一、部署模式与适用场景Tempo 支持多种部署形态本示例采用的是monolithic mode单体模式即把全部功能组件打包进一个进程运行。在 cmd/tempo/app/modules.go 中可以看到Tempo 用SingleBinary常量标识该模式其值就是字符串allSingleBinary string all func IsSingleBinary(target string) bool { return target SingleBinary }从同一文件的模块依赖关系cmd/tempo/app/modules.go可以确认all这个复合目标实际组合了以下全部组件SingleBinary: {BackendScheduler, BackendWorker, QueryFrontend, Querier, Distributor, MetricsGenerator, LiveStore}也就是说分发器Distributor、查询前端QueryFrontend、查询器Querier、指标生成器MetricsGenerator等职责全部收敛在单一进程内。这种模式的优势是部署简单、依赖少、资源占用低适合开发环境、演示环境以及中小规模写入量的场景需要横向扩展时再切换到多进程的微服务模式。⚠️重要提示原文档原文本示例基于 Tempo2.x架构创建尚未针对 3.x 更新因为维护者并未在 Nomad 上部署。该示例目前处于deprecated废弃状态如果社区不更新它未来可能被移除。3.x 中新增了 LiveStore、PartitionRing 等组件部署形态与 2.x 已有差异请结合你实际使用的 Tempo 版本审慎参考。二、前置条件与作业文件结构2.1 前置条件原文档明确要求的唯一硬性前提是S3 兼容对象存储本示例的 trace 后端使用 S3因此需要一个可访问的 S3 兼容服务如 AWS S3、MinIO、Ceph RGW 等并准备好endpoint、access key、secret key。另外按仓库实际情况补充的环境前提一个可用的HashiCorp Nomad 集群或单节点 dev 模式且客户端节点安装了Docker 驱动——因为tempo.hcl中的 task 使用driver docker见 example/nomad/tempo-monolith/tempo.hcl节点能访问grafana/tempo:${var.version}镜像仓库如使用示例默认的 Prometheus Remote Write 地址http://prometheus.service.consul/api/v1/write则环境中应有 Consul DNS 服务发现及可用的 Prometheus否则请通过变量覆盖。2.2 文件清单example/nomad/tempo-monolith目录下只有两个文件文件作用tempo.hclNomad 作业定义HCL内含 Tempo 配置模板README.md原文档说明用法与变量其中 Tempo 自身的 YAML 配置并没有单独成文件而是以Nomadtemplate内联模板的形式嵌在tempo.hcl中渲染后写入local/config.yml。三、tempo.hcl 逐段详解3.1 变量定义可参数化配置作业顶部定义了 4 个variable与原文档中的变量表一一对应variable version { type string description Tempo version default 2.7.1 } variable prometheus_remote_write_url { type string description Prometheus Remote Write URL default http://prometheus.service.consul/api/v1/write } variable s3_url { type string description S3 URL default s3.dummy.url } variable s3_access_key_id { type string description S3 Access Key ID default any } variable s3_secret_access_key { type string description S3 Secret Access Key default any }变量速查表变量名默认值说明version2.7.1Tempo 镜像版本grafana/tempo:${var.version}s3_urls3.dummy.urlS3 存储 endpoint 地址注意tempo.hcl中默认值为s3.dummy.urlREADME 中写的是s3.dummy.url.com以 hcl 文件实际值为准s3_access_key_idanyS3 Access Key IDs3_secret_access_keyanyS3 Secret Access Keyprometheus_remote_write_urlhttp://prometheus.service.consul/api/v1/write指标生成器metrics_generatorRemote Write 目标any等占位默认值表明生产部署必须通过-var显式覆盖仅当你的 S3 恰好不需要校验凭据如本地 MinIO 关闭认证时才可沿用默认。3.2 作业骨架与网络端口job tempo { datacenters [*] group tempo { count 1 network { port http { to 3200 } port grpc {} port otlp { to 4317 } }datacenters [*]允许调度到任意数据中心可按需改成具体 DC 名count 1单实例部署符合单体模式语义三个端口映射http容器内3200端口——Tempo 的 HTTP API查询、/ready健康检查等grpc不固定to由容器默认监听——Tempo 内部 gRPC查询前端与查询器之间通信otlp容器内4317端口——OpenTelemetry 协议 gRPC 接收端点。3.3 服务发现与健康检查service { name tempo-http port http tags [] check { name tempo-http port http type http path /ready interval 20s timeout 1s } } service { name tempo-grpc port grpc tags [] check { port grpc type grpc interval 20s timeout 1s grpc_use_tls false tls_skip_verify true } } service { name tempo-otlp port otlp tags [] }tempo-http注册到 Consul并用HTTP 探活/ready每 20 秒检查一次超时 1 秒tempo-grpc使用gRPC 健康检查协议并显式关闭 TLSgrpc_use_tls false因为本示例是纯内网明文部署tempo-otlp仅注册服务供采集器通过服务发现找到 OTLP 端点不做健康检查。/ready探针并非任意占位路径。在 cmd/tempo/app/app.go 中Tempo 启动时会注册/ready处理器其实现同文件readyHandler见 cmd/tempo/app/app.go会逐个检查 Generator、Query Frontend、LiveStore 等模块的就绪状态全部就绪才返回200 OK否则返回503。因此这个探针能真实反映“服务可对外服务”而非仅仅是“进程存活”。3.4 task 定义与启动参数task tempo { driver docker user nobody kill_timeout 90s config { image grafana/tempo:${var.version} ports [http, grpc, otlp] args [ -targetall, -config.file/local/config.yml, -config.expand-envtrue, ] }要点user nobody以非 root 用户运行容器符合最小权限原则kill_timeout 90s给 Tempo 留出优雅关闭flush WAL、落盘 block的时间三个启动参数-targetall显式指定以单二进制模式启动。实际上在 cmd/tempo/app/config.go 中该 flag 的默认值就是SingleBinary即all这里显式写出更清晰-config.file/local/config.yml指定配置文件路径由下方template渲染生成-config.expand-envtrue允许在配置文件中展开环境变量。其实现位于 cmd/tempo/main.go读取配置文件原文后调用envsubst.EvalEnv做环境变量替换再以yaml.UnmarshalStrict严格解析。这意味着配置里可以放心使用$NOMAD_*这类 Nomad 注入的环境变量。3.5 内联 Tempo 配置模板template块把一段 YAML 渲染为容器内的local/config.ymlexample/nomad/tempo-monolith/tempo.hcl这是整个作业的核心server: log_level: info http_listen_port: {{ env NOMAD_PORT_http }} grpc_listen_port: {{ env NOMAD_PORT_grpc }} distributor: receivers: # this configuration will listen on all ports and protocols that tempo is capable of. otlp: protocols: http: grpc: endpoint: 0.0.0.0:{{ env NOMAD_PORT_otlp }} metrics_generator: processor: service_graphs: max_items: 10000 storage: path: {{ env NOMAD_ALLOC_DIR }}/tempo/wal remote_write: - url: ${var.prometheus_remote_write_url} send_exemplars: true storage: trace: backend: s3 wal: path: {{ env NOMAD_ALLOC_DIR }}/tempo/wal local: path: {{ env NOMAD_ALLOC_DIR }}/tempo/blocks s3: bucket: tempo # how to store data in s3 endpoint: ${var.s3_url} insecure: true access_key: ${var.s3_access_key_id} secret_key: ${var.s3_secret_access_key} overrides: defaults: metrics_generator: processors: - service-graphs - span-metrics逐段说明serverHTTP 与 gRPC 监听端口直接取自 Nomad 分配的动态端口环境变量NOMAD_PORT_http/NOMAD_PORT_grpc保证与 3.2 节的端口映射一致distributor.receivers启用 OTLP 接收器同时开放HTTP4318 语义与 gRPC协议gRPC 端点绑定0.0.0.0:NOMAD_PORT_otlp4317。注释点明这会“监听 Tempo 所支持的所有端口与协议”metrics_generator开启service-graphs处理器服务拓扑图max_items: 10000限制内存中的服务图条目数存储路径位于分配目录下的 WAL并通过 Remote Write 把指标发给 Prometheussend_exemplars: true会附带 exemplarstorage.trace后端选s3WAL 与本地缓存路径都放在NOMAD_ALLOC_DIRNomad 为每个分配提供的本地磁盘目录重启后即被清理适合缓存类数据S3 配置中insecure: true表示走HTTP 而非 HTTPS自建 S3 常用bucket 固定为tempoendpoint 与凭据来自变量overrides租户默认覆盖配置——为所有租户默认启用service-graphs与span-metrics两个指标生成处理器。3.6 资源限制resources { cpu 300 memory 1024 }CPU 300 MHz、内存 1024 MB。单体模式把全部组件塞进一个进程内存主要消耗在接收与批量写、WAL 缓冲、service-graphs 的max_items条目、以及查询时的 block 索引。生产环境建议根据实际写入量与查询量上调并观察/ready与日志再行调整。四、运行作业4.1 基本运行在包含tempo.hcl的目录下执行nomad job run tempo.hcl4.2 覆盖版本变量作业默认拉取grafana/tempo:2.7.1对应variable.version默认值。要换版本可以改 hcl 里的 default或直接命令行覆盖nomad job run -varversion2.7.1 tempo.hcl4.3 覆盖 S3 与 Prometheus 变量同理S3 与 Remote Write 参数务必显式指定例如nomad job run \ -vars3_urlminio.example.internal:9000 \ -vars3_access_key_idtempo \ -vars3_secret_access_keysecret \ -varprometheus_remote_write_urlhttp://prometheus.service.consul/api/v1/write \ tempo.hcl运行后可在 Consul 中发现tempo-http、tempo-grpc、tempo-otlp三个服务向 OTLP gRPC 端点4317写入 trace即可通过 HTTP API3200查询。五、验证与排障健康检查curl http://node-ip:http-port/ready返回200表示各模块就绪503 响应体会指出是哪个模块未就绪Generator / Query Frontend / LiveStore指标生成链路确认metrics_generator的 Remote Write 目标可达否则service-graphs/span-metrics生成的指标无法送达 Prometheus服务拓扑图与 RED 指标会缺失存储验证写入若干 trace 后检查 S3 buckettempo下是否出现 block 数据compact 任务会周期性把 WAL 落盘为 block 并上传模板渲染如果配置有误可先在本机渲染模板检查产物替换{{ env ... }}与${var.*}后执行tempo -config.fileconfig.yml -config.verifyTempo 支持-config.verify只校验配置不启动见 cmd/tempo/main.go。六、注意事项与局限以仓库为准版本适配示例面向 2.x 架构默认2.7.1。当前仓库源码已演进到包含 LiveStore、PartitionRing、BlockBuilder 等 3.x 组件的版本见 cmd/tempo/app/modules.go若用新版本镜像建议对照相应版本官方配置模板更新overrides与storage段S3 凭据安全凭据通过-var传入并最终进入作业定义注意保护 Nomad 作业定义与 Consul KV 的访问权限生产建议改用 Nomad 的template Vault 集成注入密钥而非明文变量单点形态count 1无副本、无多可用区冗余NOMAD_ALLOC_DIR中的数据随分配销毁而丢失已上传 S3 的 block 不受影响WAL/本地缓存可重建生产高可用请参考仓库 example/nomad/tempo-distributed 或分布式部署文档废弃状态如原文档所述此示例可能被移除建议以官方 Helm 或 example/docker-compose 中的单二进制示例作为长期维护的部署参考。七、参考资料本示例作业文件example/nomad/tempo-monolith/tempo.hcl原文档含变量表与用法example/nomad/tempo-monolith/README.md单二进制模式与-target定义cmd/tempo/app/modules.go、cmd/tempo/app/config.go配置加载与-config.expand-env实现cmd/tempo/main.go/ready就绪探针实现cmd/tempo/app/app.go【免费下载链接】tempoGrafana Tempo is a high volume, minimal dependency distributed tracing backend.项目地址: https://gitcode.com/GitHub_Trending/tempo1/tempo创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考