Grafana Tempo 使用 Amazon S3 与 S3 兼容对象存储MinIO / SeaweedFS / rclone配置指南【免费下载链接】tempoGrafana Tempo is a high volume, minimal dependency distributed tracing backend.项目地址: https://gitcode.com/GitHub_Trending/tempo1/tempo导读本文基于 Grafana Tempo 官方文档系统讲解如何将 Tempo 的 trace 存储后端配置为 Amazon S3 或任意 S3 兼容对象存储覆盖身份认证、IAM 最小权限策略、本地测试环境SeaweedFS、rclone、MinIO的搭建与验证并深入结合仓库源码剖析 S3 后端的底层实现凭证链、multipart 上传、SSE 加密、hedged 请求等。读完本文你可以独立完成从对象存储选型、鉴权配置到数据落盘验证的完整闭环。Tempo 将 Amazon S3 及所有 S3 兼容对象存储如 MinIO、SeaweedFS、rclone 等作为 trace 数据的后端存储之一。要了解通用的存储配置选项可参考官方配置文档的 storage 章节。在仓库源码层面S3 后端的完整实现位于 tempodb/backend/s3/其中 config.go 定义了全部配置项s3.go 实现了读写、列举、压缩、版本化等全部存储接口。身份认证AuthenticationTempo 的 S3 后端支持多种认证方式按优先级依次尝试直到获取到有效凭证为止。官方文档列出的认证来源包括AWS 环境变量AWS_ACCESS_KEY_ID与AWS_SECRET_ACCESS_KEY配置文件中显式指定的静态凭证access_key与secret_keyMinIO 环境变量MINIO_ACCESS_KEY与MINIO_SECRET_KEYAWS 共享凭证配置文件~/.aws/credentialsMinIO 客户端凭证配置文件AWS IAM 服务账户角色IRSA通过 WebIdentityAWS EC2 实例角色AWS EKS Pod Identity从源码看这一多来源按序尝试的机制实现在 s3.go 的 fetchCreds 函数它构造了一个凭证 Provider 链credentials.NewChainCredentials依次包含静态凭证Static、AWS 环境变量EnvAWS、MinIO 环境变量EnvMinio、AWS 共享凭证文件FileAWSCredentials、MinIO 客户端凭证文件FileMinioClient以及 IAM 角色并在启动时提前调用GetWithContext校验凭证是否可得若全部失败则直接报错退出。最小权限 IAM 策略官方文档给出了一份bucket 已预先创建前提下 Tempo 所需的最小 IAM 权限策略可直接复制使用{ Version: 2012-10-17, Statement: [ { Sid: TempoPermissions, Effect: Allow, Action: [ s3:PutObject, s3:GetObject, s3:ListBucket, s3:DeleteObject, s3:GetObjectTagging, s3:PutObjectTagging ], Resource: [arn:aws:s3:::bucketname/*, arn:aws:s3:::bucketname] } ] }各权限项的用途与 Tempo 的存储行为一一对应s3:PutObject/s3:GetObject/s3:DeleteObject写入、读取与删除 block 数据文件对应源码中的Write、Read、Delete方法见 s3.gos3:ListBucketblocklist 轮询与租户索引构建需要列举 bucket 内容对应List与ListBlocks见 s3.gos3:GetObjectTagging/s3:PutObjectTaggingTempo 通过对象标签tags维护压缩/租户等元信息。生命周期策略Lifecycle policy官方文档建议为 bucket 配置生命周期策略在一天后删除未完成的分片上传incomplete multipart uploads。这一建议与源码中的写入路径直接相关Tempo 在追加写入较大对象时使用 multipart upload见下文底层实现小节若进程在完成上传前异常退出就会在 bucket 中遗留未完成的 upload 片段生命周期策略可防止这些碎片长期占用存储空间。本地 S3 兼容存储测试环境搭建官方文档强调本节工具仅用于本地测试与评估未与 Tempo 做全量兼容性验证不推荐用于生产。三个候选方案中SeaweedFS官方推荐的首选本地测试方案单命令启动且自带 Web UIrclone serve s3可将任意本地目录以 S3 兼容端点形式暴露但被 rclone 项目标记为 experimental存在已知限制MinIO同样受支持但其开源仓库已归档社区版仅以源码形式分发不再发布预编译二进制。方案一SeaweedFS推荐SeaweedFS 是 Apache 2.0 许可的分布式存储系统内置 S3 网关。从 SeaweedFS 的 releases 页面下载并安装创建数据目录并以 mini 模式启动sudo mkdir -p /data/seaweedfs sudo chown -R $USER:$USER /data/seaweedfs weed mini -dir/data/seaweedfsweed mini会启动一个完整的单节点环境其中 S3 网关监听8333端口。SeaweedFS 以前台方式运行后续步骤请在新终端中执行。使用 AWS CLI 创建名为tempo的 bucketaws --endpoint-url http://localhost:8333 s3 mb s3://tempo --no-sign-requestSeaweedFS mini 模式允许匿名访问因此--no-sign-request用于跳过凭证校验。使用前请先安装 AWS CLI。方案二rclone serve s3experimentalrclone 可以把任意本地目录暴露为 S3 兼容端点。按 rclone 官方安装指南完成安装创建数据目录并启动 S3 服务sudo mkdir -p /data/rclone-s3 sudo chown -R $USER:$USER /data/rclone-s3 rclone serve s3 /data/rclone-s3 --auth-key tempokey,temposecret --addr :8080服务在前台监听8080端口后续步骤请在新终端中执行。使用 AWS CLI 创建 bucket注意需传入--auth-key指定的凭证AWS_ACCESS_KEY_IDtempokey AWS_SECRET_ACCESS_KEYtemposecret \ aws --endpoint-url http://localhost:8080 s3 mb s3://tempo方案三MinIO需从源码构建MinIO 开源仓库已归档社区版仅提供源码需使用 Go 1.24 或更高版本自行编译也可参考其仓库说明构建 Docker 镜像。从源码安装 MinIOgo install github.com/minio/miniolatest创建数据目录并启动sudo mkdir -p /data/minio sudo chown -R $USER:$USER /data/minio minio server /data/minio --console-address :9001默认访问凭证为minioadmin/minioadminaccess key 与 secret key 相同。MinIO 前台运行后续步骤请在新终端执行。使用 MinIO 客户端mc创建 bucketmc alias set local http://localhost:9000 minioadmin minioadmin mc mb local/tempoTempo 对接 S3 的完整配置通用配置模板官方文档给出了一个可直接使用的完整配置示例其中metrics_generator为可选模块若要关闭它删除metrics_generator配置块以及 overrides 中的processors列表即可stream_over_http_enabled: true server: http_listen_port: 3200 distributor: receivers: otlp: protocols: grpc: endpoint: 0.0.0.0:4317 http: endpoint: 0.0.0.0:4318 backend_scheduler: provider: compaction: compaction: block_retention: 1h backend_worker: compaction: block_retention: 1h metrics_generator: registry: external_labels: source: tempo cluster: linux-monolithic storage: path: /tmp/tempo/generator/wal remote_write: - url: http://PROMETHEUS_URL/api/v1/write send_exemplars: true storage: trace: backend: s3 s3: endpoint: S3_ENDPOINT bucket: tempo access_key: S3_ACCESS_KEY secret_key: S3_SECRET_KEY insecure: true wal: path: /var/tempo/wal overrides: defaults: metrics_generator: processors: [service-graphs, span-metrics] usage_report: reporting_enabled: false其中PROMETHEUS_URL替换为你的 Prometheus 兼容存储地址例如localhost:9090。注意storage.trace.backend的合法取值为s3、azure、gcs、local这一约束定义在 modules/storage/config.go 的命令行标志说明中而storage.trace.wal.path的默认值为/var/tempo/wal见 modules/storage/config.goWAL 必须位于本地磁盘。各对象存储的 endpoint 与凭证对照官方文档针对三种本地对象存储给出了对应的 S3 配置块SeaweedFSmini 模式允许匿名访问access_key/secret_key可省略或随意填写storage: trace: backend: s3 s3: endpoint: localhost:8333 bucket: tempo insecure: truerclone serve s3使用--auth-key指定的凭证storage: trace: backend: s3 s3: endpoint: localhost:8080 bucket: tempo access_key: tempokey secret_key: temposecret insecure: trueMinIO默认凭证 minioadminstorage: trace: backend: s3 s3: endpoint: localhost:9000 bucket: tempo access_key: minioadmin secret_key: minioadmin insecure: true仓库中的真实部署示例可进一步佐证这一写法例如 example/docker-compose/distributed/tempo.yaml 中endpoint: minio:9000、insecure: true的容器内 MinIO 对接方式以及 example/nomad/tempo-monolith/tempo.hcl 中通过 Nomad 变量注入s3_url、s3_access_key_id、s3_secret_access_key的写法。验证数据已写入对象存储trace 数据开始流动后可按对象存储类型验证 bucket 内容SeaweedFS打开管理 UIhttp://localhost:23646或使用 AWS CLI 列举 bucketaws --endpoint-url http://localhost:8333 s3 ls s3://tempo/ --recursive --no-sign-request预期能看到形如single-tenant/block-id/data.parquet与single-tenant/block-id/meta.json的文件。rclone serve s3同样用 AWS CLI 列举rclone 无 Web UIAWS_ACCESS_KEY_IDtempokey AWS_SECRET_ACCESS_KEYtemposecret \ aws --endpoint-url http://localhost:8080 s3 ls s3://tempo/ --recursive预期文件结构与 SeaweedFS 一致。MinIO打开控制台http://localhost:9001检查tempobucket 下应存在work.json及租户数据目录。S3 后端配置项全览结合源码官方配置文档之外tempodb/backend/s3/config.go 定义了完整的Config结构以下配置项均可写入storage.trace.s3块也都有对应的命令行 flag如-storage.trace.s3.bucket配置项说明bucket存储 block 的 S3 bucket 名称bucket 名全局唯一用于后端路径匹配见 PathMatchesprefix存储 block 的 S3 根目录前缀endpointS3 端点地址region区域access_key/secret_key静态访问凭证session_token会话令牌临时凭证场景insecure是否使用 HTTP 而非 HTTPS本地对象存储通常设为truepart_sizemultipart 上传分片大小为 0 时保持旧行为立即上传不缓冲大于 0 时启用按固定分片大小缓冲的 R2 兼容分块见 Append 实现hedge_requests_at/hedge_requests_up_to请求对冲hedged request的触发延迟与最大并发数默认HedgeRequestsUpTo 2见 config.go用于降低长尾延迟retry_max_attempts/retry_backoff_initial/retry_backoff_max重试次数与退避参数默认继承 minio-go 的MaxRetry、DefaultRetryUnit、DefaultRetryCap见 config.go并会全局覆盖 minio 客户端行为见 internalNewsignature_v2是否使用 V2 签名代替 V4某些老式对象存储需要源码通过包装凭证 Provider 强制改写签名版本见 overrideSignatureVersionforcepathstyle是否强制 path-style 访问bucket_lookup_type为BucketLookupPath对某些不支持的虚拟主机风格端点的对象存储是必需的见 createCoreenable_dual_stack是否启用 IPv4/IPv6 双栈bucket_lookup_typebucket 查找类型默认由ForcePathStyle决定tags上传对象时附加的用户标签写入 PutObjectOptionsstorage_class对象存储类别metadata用户自定义元数据list_blocks_concurrencyblocklist 列举并发数默认 3见 config.goListBlocks会按 block UUID 边界分片并发列举见 s3.gosse.type/sse.kms_key_id/sse.kms_encryption_context/sse.encryption_key服务端加密配置支持SSE-KMS、SSE-S3、SSE-C三种类型见下方小节tls_min_version连接 S3 的最小 TLS 版本默认VersionTLS12见 config.go服务端加密SSESSEConfig定义了三种服务端加密类型常量定义见 config.goSSE-KMS使用 AWS KMS 密钥加密需配置kms_key_id可选kms_encryption_contextJSON 字符串若缺少kms_key_id会报错SSE-S3使用 S3 托管密钥AES-256加密无需额外参数SSE-C使用客户提供的密钥加密需配置encryption_key缺失同样报错。buildSSEConfig函数s3.go负责把配置翻译为 minio 的加密对象遇到未知类型返回unsupported S3 SSE type。值得注意的安全细节SSE 加密密钥属于敏感配置config_test.go 中的测试验证了序列化 YAML 时明文密钥会被flagext.Secret类型脱敏为********不会泄露到配置输出中。底层实现要点写入、multipart 与读取优化对象路径所有读写都会将prefix前置到对象键KeyPathWithPrefix并按ObjectFileName组织文件命名写入Write直接调用 minio 的PutObject完成上传Append则启动NewMultipartUpload分片上传CloseAppend汇总各分片调用CompleteMultipartUpload见 s3.go——这就是官方建议配置生命周期策略清理未完成分片上传的原因读取Read/ReadRange均通过hedgedCore带对冲的客户端执行GetObjectReadRange使用SetRange实现字节区间读取配合ReadAllWithEstimate按对象大小预分配缓冲提升 parquet 页/索引的按需读取效率见 s3.go版本化S3 原生不支持条件写头因此WriteVersioned/DeleteVersioned采用先读当前版本ETag→ 校验 → 再写/删的最佳努力方案见 s3.go源码注释中明确指出了其中存在的潜在竞态连接池创建 minio 客户端时会将MaxIdleConns与MaxIdleConnsPerHost提升到 100并对传输层接入 instrumentation 与可选的 hedged 统计指标见 createCore。常见问题与注意事项insecure: true仅在本地/内网测试可用生产环境对接 AWS S3 时应保持默认 HTTPS并优先使用 IAM 角色IRSA、EC2 Instance Role、EKS Pod Identity而非静态密钥。SeaweedFS 的匿名模式endpoint 填localhost:8333即可凭证字段可省略若填写了凭证但服务端拒绝可检查是否为--no-sign-request访问模式。MinIO 需从源码构建社区版不再发布二进制构建环境要求 Go 1.24若使用容器可按 MinIO 仓库说明自行构建镜像。WAL 与对象存储的职责区分storage.trace.wal.path指向本地磁盘默认/var/tempo/walWAL 负责短期写入缓冲S3 只承接最终落盘的 block 数据因此 S3 配置块中不要出现 WAL 路径。强制 path-style 访问当对象存储不支持虚拟主机风格访问常见于 MinIO、SeaweedFS、rclone 等自建服务或 bucket 名中含点号时可设置forcepathstyle: true规避 DNS 解析问题。通过上述配置与验证步骤你可以将 Grafana Tempo 无缝对接 AWS S3 或任意 S3 兼容存储并借助本地对象存储快速搭建一套可复现的分布式链路追踪测试环境。若要进一步了解存储层的通用选项缓存、pool、blocklist 轮询等可继续阅读官方配置文档的 storage 章节及 tempodb 目录下的实现。【免费下载链接】tempoGrafana Tempo is a high volume, minimal dependency distributed tracing backend.项目地址: https://gitcode.com/GitHub_Trending/tempo1/tempo创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考