Grafana Tempo 托管对象存储配置指南：S3、GCS 与 Azure 后端详解

Grafana Tempo 托管对象存储配置指南S3、GCS 与 Azure 后端详解【免费下载链接】tempoGrafana Tempo is a high volume, minimal dependency distributed tracing backend.项目地址: https://gitcode.com/GitHub_Trending/tempo1/tempo本指南基于 Grafana Tempo 官方文档与仓库源码系统讲解 Tempo 对 Amazon S3及 S3 兼容存储、Google Cloud StorageGCS和 Azure Blob Storage 三大托管对象存储的支持方式包括认证机制、最小权限 IAM 策略、本地开发环境搭建、完整可运行的 YAML 配置示例以及 hedged requests、blocklist 轮询等关键调优项。读完本文你将能够为 Tempo 正确选择并配置托管存储后端并能在本地用 SeaweedFS、rclone 或 MinIO 快速验证整套链路。本文对应的官方文档为 docs/sources/tempo/configuration/hosted-storage/通用存储配置参数详见配置主文档的 Storage 章节。托管存储概览Tempo 的持久化 trace 数据以 Parquet 块block的形式存放在对象存储中支持 Amazon S3、GCS、Azure 以及本地文件系统四种后端。其中本地文件系统仅用于开发与测试生产环境强烈推荐使用对象存储——本地后端在分布式部署中只有所有组件共享同一块磁盘时才能正确检索 trace而 Tempo 从设计上就更面向对象存储而非本地磁盘。三大托管存储的定位如下详见 hosted-storage 目录下各自的子页面Amazon S3 与 S3 兼容存储除 AWS S3 本身外还支持 MinIO、SeaweedFS、rclone 等 S3 兼容对象存储是本地测试的首选路径Google Cloud Storage重点说明 GCS 的认证方式与所需的最小 IAM 权限Azure Blob Storage覆盖共享密钥、托管身份、Workload Identity 三种认证以及单体/分布式两种部署模式的配置样例。在配置层面所有后端都收敛在storage.trace配置块下通过backend字段选择具体后端storage: trace: # 取值gcs、s3、azure 或 locallocal 仅支持单体模式 # 对应 CLI 参数-storage.trace.backend [backend: string]Tempo 要求后端中存在一个顶层桶bucket/container来维护对象结构各后端均支持用prefix选项将对象嵌套进共享桶中实现多环境共用存储。Amazon S3 与 S3 兼容存储Tempo 支持 Amazon S3 以及一切兼容 S3 API 的对象存储作为 trace 存储后端包括 MinIO、SeaweedFS、rclone 等。支持的认证方式S3 后端支持以下认证方法按官方文档顺序AWS 环境变量AWS_ACCESS_KEY_ID与AWS_SECRET_ACCESS_KEY在配置文件的access_key与secret_key字段中直接指定静态访问密钥MinIO 环境变量MINIO_ACCESS_KEY与MINIO_SECRET_KEYAWS 共享凭证文件shared credentials configuration fileMinIO 客户端凭证配置文件AWS IAM通过 WebIdentity 的 IRSA 方式AWS EC2 实例角色EC2 instance roleAWS EKS Pod Identity。最小权限 IAM 策略在桶已预先创建的前提下Tempo 需要的最小 S3 权限如下将bucketname替换为实际桶名{ 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] } ] }策略中的s3:GetObjectTagging与s3:PutObjectTagging对应 Tempo 写入对象标签的能力——S3 后端支持在storage.trace.s3.tags中配置对象标签便于在 S3 生命周期规则中按标签过滤清理。此外官方建议配置生命周期策略删除一天前尚未完成的分片上传incomplete multipart uploads避免产生孤儿分片占用存储。本地 S3 兼容存储测试用官方为本地测试推荐了几种 S3 兼容方案并明确提示这些工具仅用于本地测试与评估未经 Tempo 完整验证不建议用于生产。三者的取舍如下工具特点备注SeaweedFS单命令启动、自带 Web UI官方推荐weed mini同时启动 S3 网关端口 8333rclone serve s3把任意本地目录暴露为 S3 端点rclone 官方标记为实验性存在已知限制MinIO功能完善开源仓库已归档社区版仅以源码形式发布需用 Go 1.24 自行编译SeaweedFS从 SeaweedFS 官方 releases 页面下载并安装创建数据目录并以 mini 模式启动前台运行需另开终端执行后续步骤sudo mkdir -p /data/seaweedfs sudo chown -R $USER:$USER /data/seaweedfs weed mini -dir/data/seaweedfs使用 AWS CLI 创建tempo桶。SeaweedFS mini 模式允许匿名访问因此用--no-sign-request跳过凭证校验aws --endpoint-url http://localhost:8333 s3 mb s3://tempo --no-sign-requestrclone serve s3实验性按 rclone 官方安装指南安装创建数据目录并启动 S3 服务前台运行端口 8080sudo 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使用--auth-key设置的凭证创建桶AWS_ACCESS_KEY_IDtempokey AWS_SECRET_ACCESS_KEYtemposecret \ aws --endpoint-url http://localhost:8080 s3 mb s3://tempoMinIOMinIO 开源仓库已归档社区版仅以源码形式分发、不再发布预编译二进制需用 Go 1.24 从源码安装go install github.com/minio/miniolatest创建数据目录并启动服务默认 access key 与 secret key 均为minioadmin控制台在 9001 端口sudo mkdir -p /data/minio sudo chown -R $USER:$USER /data/minio minio server /data/minio --console-address :9001用 MinIO 客户端mc创建桶mc alias set local http://localhost:9000 minioadmin minioadmin mc mb local/tempoTempo 连接 S3 兼容存储的配置下面是一份完整的单机monolithic配置示例使用 S3 后端并附带 metrics-generator。请将S3_ENDPOINT、S3_ACCESS_KEY、S3_SECRET_KEY、PROMETHEUS_URL替换为实际值如需禁用 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注意wal.path是本地 WAL 目录而非对象存储路径usage_report.reporting_enabled: false用于关闭匿名用量上报。针对上文三种本地存储storage.trace.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: trueMinIOstorage: trace: backend: s3 s3: endpoint: localhost:9000 bucket: tempo access_key: minioadmin secret_key: minioadmin insecure: true验证数据是否写入trace 开始流入后可按对应工具检查桶内数据SeaweedFS打开管理 UIhttp://localhost:23646或用 AWS CLI 递归列出aws --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无 Web UIAWS_ACCESS_KEY_IDtempokey AWS_SECRET_ACCESS_KEYtemposecret \ aws --endpoint-url http://localhost:8080 s3 ls s3://tempo/ --recursiveMinIO打开控制台http://localhost:9001在tempo桶中应能看到work.json与租户数据目录。S3 后端的更多参数与源码佐证配置主文档的 Storage 章节 给出了storage.trace.s3的完整参数表核心项包括参数说明默认值bucket/prefix桶名与可选对象前缀用于嵌套共享桶-endpointS3 或兼容存储的 API 端点-region区域通常可从端点推断部分兼容存储需要显式指定-access_key/secret_key/session_token静态凭证-insecure端点是否走 HTTPfalsepart_size分片上传的分片大小字节0 禁用分片上传非 0 时必须不小于 5 MiB52428800forcepathstyle是否使用路径式请求-signature_v2使用 V2 签名替代 V4falseenable_dual_stack启用双栈端点做 DNS 解析-bucket_lookup_type0: Auto1: DNS2: Path设置了forcepathstyle时该项被忽略0hedge_requests_at/hedge_requests_up_to对冲请求延迟与最大请求数见下文公共调优0禁用/2retry_max_attempts/retry_backoff_initial/retry_backoff_max失败重试次数与指数退避上下限minio 默认值10 次 / 200ms / 1stags/metadata/storage_class对象标签、用户元数据、存储类-tls_cert_path/tls_key_path/tls_ca_path/tls_server_name/tls_insecure_skip_verify/tls_min_versionTLS 客户端配置默认最低 TLS1.2-sse服务端加密type支持SSE-KMS、SSE-S3、SSE-C分别配合kms_key_id、kms_encryption_context或encryption_key32 字节-上述字段与源码 tempodb/backend/s3/config.go 中的Config结构体一一对应例如HedgeRequestsUpTo在RegisterFlagsAndApplyDefaults中被默认设为2重试相关默认值直接取自 minio-go 的MaxRetry、DefaultRetryUnit、DefaultRetryCapSSEKMS、SSES3、SSEC三个加密类型也是由该文件中的常量定义并校验不支持的 SSE 类型会返回errUnsupportedSSEType。需要留意的是native_aws_auth_enabled已被标记为弃用——它除了在启动时打印警告外没有任何作用请改用 IAM 角色、环境变量等原生 AWS 认证机制。Google Cloud StorageGCSGCS 后端的配置参数同样位于storage.trace.gcs块详见配置主文档 Storage 章节并在 gcs 子页面 中补充了认证与权限要求。认证方式GCS 后端支持两种认证方式Google Cloud Platform 环境变量GOOGLE_APPLICATION_CREDENTIALS指向服务账号 JSON 密钥文件Google Cloud Platform Workload Identity用于 GKE 等场景无需落盘密钥。从源码 tempodb/backend/gcs/config.go 看GCS 后端通过 Go 官方的cloud.google.com/go/storage客户端自动继承应用默认凭证ADC因此配置文件中不需要也没有静态密钥字段认证完全交给上述两种机制。需要的 IAM 权限与 GCS 通信的服务账号应被授予桶级权限即被分配在接收 trace 的桶上并拥有以下 IAM 权限storage.objects.createstorage.objects.deletestorage.objects.getstorage.buckets.getstorage.objects.list与 S3 的最小策略类似这组权限覆盖了 Tempo 写入块、读取块、删除块压缩/保留清理以及列桶/租户索引轮询的完整生命周期。GCS 配置要点storage.trace.gcs块的主要参数参数说明bucket_nameGCS 桶名如tempoprefix可选对象前缀用于在共享桶内嵌套endpointAPI 端点覆盖如https://storage.googleapis.com/storage/v1/chunk_buffer_size读缓冲大小默认 10 MBinsecure是否禁用认证与证书校验默认falselist_blocks_concurrency并发 list 调用数默认 3max_retries压缩与保留删除操作的重试次数默认 3object_cache_control对象 Cache-Control 头object_metadata写入对象的用户元数据key-value 映射hedge_requests_at/hedge_requests_up_to对冲请求参数其中hedge_requests_up_to同样默认2见源码 tempodb/backend/gcs/config.go 的RegisterFlagsAndApplyDefaults。Azure Blob StorageTempo 支持 Azure Blob Storage且同时覆盖单体monolithic与分布式distributed两种部署模式详见 azure 子页面。其核心特性包括对象布局自定义container_name并通过可选prefix在共享容器中嵌套对象性能hedge_requests_at/hedge_requests_up_to对冲请求降低长尾延迟区域/主权云通过endpoint_suffix配置端点后缀如 US Gov、Germany 等本地开发支持 Azurite 模拟器非blob.*开头的端点样式会被自动识别运维兼容 Azure Storage 生命周期策略用于容器清理文档附示例。支持的认证方式Azure 后端支持三种认证共享密钥Shared key在配置中指定storage_account_key或设置环境变量AZURE_STORAGE_KEY托管身份Managed Identity系统/用户分配设置use_managed_identity: true用户分配的托管身份还需设置user_assigned_id为对应 client ID系统分配则无需额外配置Azure Workload Identity联合令牌需在集群上启用 Workload Identity为服务账号添加所需 label 与 annotation 及 Pod label并在配置中设置use_federated_token: true。存储账号名必须在配置文件的storage_account_name字段或环境变量AZURE_STORAGE_ACCOUNT中指定。这些字段与源码 tempodb/backend/azure/config.go 中Config结构体的UseManagedIdentity、UseFederatedToken、UserAssignedID、ContainerName、StorageAccountName一一对应。单体模式配置示例Helm Kubernetes Secrets以下示例使用 Helm 配置 Azure 存储访问密钥来自 Kubernetes Secret。注意需开启config.expand-env以支持配置中的${ENV_VAR}环境变量展开展开发生在 YAML 解析之前未定义变量会被替换为空字符串可用${VAR:-default}指定默认值tempo: storage: trace: backend: azure azure: container_name: container-name storage_account_name: storage-account-name storage_account_key: ${STORAGE_ACCOUNT_ACCESS_KEY} extraArgs: config.expand-env: true extraEnv: - name: STORAGE_ACCOUNT_ACCESS_KEY valueFrom: secretKeyRef: name: secret-name key: STORAGE_ACCOUNT_ACCESS_KEY使用 Azure Workload Identity 时则无需任何密钥tempo: storage: trace: backend: azure azure: container_name: container-name storage_account_name: storage-account-name use_federated_token: true分布式模式配置示例分布式模式通常使用tempo-distributedHelm chart 安装。此时trace配置需要作用于 Values 根部的storage对象且extraArgs与extraEnv必须分别应用到以下每个服务distributorblockBuilderliveStorequerierqueryFrontendbackendSchedulerbackendWorker将下面的片段加入你的custom.yaml或values.yaml注意各服务的extraArgs使用命令行参数形式-config.expand-envtrue而extraEnv均引用同一个 Secretstorage: trace: backend: azure azure: container_name: tempo-traces storage_account_name: stgappgeneraluks storage_account_key: ${STORAGE_ACCOUNT_ACCESS_KEY} distributor: extraArgs: - -config.expand-envtrue extraEnv: - name: STORAGE_ACCOUNT_ACCESS_KEY valueFrom: secretKeyRef: name: tempo-traces-stg-key key: tempo-traces-key blockBuilder: extraArgs: - -config.expand-envtrue extraEnv: - name: STORAGE_ACCOUNT_ACCESS_KEY valueFrom: secretKeyRef: name: tempo-traces-stg-key key: tempo-traces-key liveStore: extraArgs: - -config.expand-envtrue extraEnv: - name: STORAGE_ACCOUNT_ACCESS_KEY valueFrom: secretKeyRef: name: tempo-traces-stg-key key: tempo-traces-key querier: extraArgs: - -config.expand-envtrue extraEnv: - name: STORAGE_ACCOUNT_ACCESS_KEY valueFrom: secretKeyRef: name: tempo-traces-stg-key key: tempo-traces-key queryFrontend: extraArgs: - -config.expand-envtrue extraEnv: - name: STORAGE_ACCOUNT_ACCESS_KEY valueFrom: secretKeyRef: name: tempo-traces-stg-key key: tempo-traces-key backendScheduler: extraArgs: - -config.expand-envtrue extraEnv: - name: STORAGE_ACCOUNT_ACCESS_KEY valueFrom: secretKeyRef: name: tempo-traces-stg-key key: tempo-traces-key backendWorker: extraArgs: - -config.expand-envtrue extraEnv: - name: STORAGE_ACCOUNT_ACCESS_KEY valueFrom: secretKeyRef: name: tempo-traces-stg-key key: tempo-traces-key使用 Azurite 进行本地开发可以用 Azurite 模拟器在本地验证 Azure 配置。Tempo 会把所有不以blob.开头的endpoint_suffix视为 Azurite并自动切换到模拟器的 URL 样式。配置方式backend设为azure提供模拟器的账号与密钥将endpoint_suffix指向模拟器的host:port遇到问题时可尝试使用模拟器的 FQDN例如azurite-host.azure.local:10000storage: trace: blocklist_poll: 1s backend: azure azure: container_name: container-name # how to store data in azure endpoint_suffix: azurite-host.svc.cluster.local:10000 # Azurite emulator host:port storage_account_name: STORAGE-ACCOUNT-NAME storage_account_key: STORAGE_ACCOUNT_ACCESS_KEYAzure 下的 blocklist 轮询调优在 Azure 上托管 Tempo 时可能需要调整两个值以保证 blocklist 轮询稳定成功若遇到并行上传 blob 时报 The specified block list is invalid 的问题尝试将blocklist_poll_tenant_index_builders设为1若出现类似下面的 DNS 解析失败尝试增大blocklist_poll_jitter_msreading storage container: Head https://tempoe**************.blob.core.windows.net/tempo/single-tenant/d8aafc48-5796-4221-ac0b-58e001d18515/meta.compacted.json?timeout61: dial tcp: lookup tempoe**************.blob.core.windows.net on 10.0.0.10:53: dial udp 10.0.0.10:53: operation was canceled调优后的配置可能类似storage: trace: blocklist_poll_tenant_index_builders: 1 blocklist_poll_jitter_ms: 500blocklist_poll_jitter_ms的作用是给并发 blocklist 轮询叠加一个最大毫秒数的随机偏移避免轮询周期同时打满后端请求blocklist_poll_tenant_index_builders则是参与构建租户索引的最大 worker 数默认 2其余组件会直接下载索引。可选存储账号生命周期管理策略以下 Azure Storage Account 管理策略示例用于在文件被删除一段时间后清理容器中的对象。第一个规则TempoBlobRetention在 blob 被修改 60 天后删除仅作用于tempo-data前缀下的 blockBlob第二个规则VersionRetention在版本创建 7 天后删除{ id: /subscriptions/00000000-0000-0000000000000000000000/resourceGroups/resourceGroupName/providers/Microsoft.Storage/storageAccounts/accountName/managementPolicies/default, lastModifiedTime: 2021-11-30T19:19:54.85545500:00, name: DefaultManagementPolicy, policy: { rules: [ { definition: { actions: { baseBlob: { delete: { daysAfterLastAccessTimeGreaterThan: null, daysAfterModificationGreaterThan: 60.0 }, enableAutoTierToHotFromCool: null, tierToArchive: null, tierToCool: null }, snapshot: null, version: null }, filters: { blobIndexMatch: null, blobTypes: [blockBlob], prefixMatch: [tempo-data] } }, enabled: true, name: TempoBlobRetention, type: Lifecycle }, { definition: { actions: { baseBlob: null, snapshot: null, version: { delete: { daysAfterCreationGreaterThan: 7.0 }, tierToArchive: null, tierToCool: null } }, filters: { blobIndexMatch: null, blobTypes: [blockBlob], prefixMatch: [] } }, enabled: true, name: VersionRetention, type: Lifecycle } ] }, resourceGroup: resource-group-name, type: Microsoft.Storage/storageAccounts/managementPolicies }Azure 后端常用参数storage.trace.azure块的主要参数汇总参数说明默认值container_name存储 trace 的容器名-prefix可选对象前缀-endpoint_suffixAzure 端点后缀默认全局core.windows.net中国blob.core.chinacloudapi.cn、德国blob.core.cloudapi.de、美国政府blob.core.usgovcloudapi.net-storage_account_name存储账号名也可用AZURE_STORAGE_ACCOUNT-storage_account_key共享密钥也可用AZURE_STORAGE_KEY-use_managed_identity启用托管身份认证falseuser_assigned_id用户分配托管身份的 client ID-use_federated_token启用 Workload Identity需AZURE_CLIENT_ID、AZURE_TENANT_ID、AZURE_AUTHORITY_HOST、AZURE_FEDERATED_TOKEN_FILE环境变量falsemax_buffers并发上传数4buffer_size上传缓冲大小字节31457283 MiBhedge_requests_at/hedge_requests_up_to对冲请求参数0禁用/2跨后端的公共调优hedged requests 与存储容量估算三个托管后端GCS、S3、Azure都支持 hedged requests对冲请求见配置主文档的 Hedged requests 小节。对冲机制通过配置延迟后在重复发起一次相同请求来降低长尾读延迟Tempo 使用先返回的响应丢弃另一个。两个参数hedge_requests_at发起重复请求前的等待延迟建议设置为后端请求的 p99 延迟默认0禁用hedge_requests_up_to最多发起多少个请求含原始请求默认2必须设置hedge_requests_at后才生效。对冲在 querier 节点上效果最显著读延迟直接影响查询性能对其他组件影响很小。三个后端的源码tempodb/backend/s3/config.go、tempodb/backend/gcs/config.go、tempodb/backend/azure/config.go均把HedgeRequestsUpTo默认初始化为2与文档保持一致。关于容量规划官方建议每日摄入字节数 × 保留天数 所需存储字节数。同时注意同一 Tempo 部署中不能混用本地与对象存储Grafana Labs 内部使用本地存储时采用 SSD机械硬盘未经过测试。对象存储上还会生成single-tenant/block-id/data.parquet与meta.json等对象它们在轮询blocklist与查询中被持续访问这也是 IAM 权限需要同时覆盖读写与列举的原因。小结本指南完整覆盖了 Grafana Tempo 托管对象存储的三大后端S3 及 S3 兼容存储支持多种 AWS 原生认证与静态密钥给出了最小 IAM 策略并提供了 SeaweedFS、rclone、MinIO 三种本地测试环境的一键搭建流程与对应 Tempo 配置GCS依托应用默认凭证只需为服务账号配置 5 项桶级 IAM 权限Azure Blob Storage共享密钥 / 托管身份 / Workload Identity 三种认证覆盖单体与分布式两种部署模式并针对 Azurite 模拟、blocklist 轮询抖动与生命周期清理给出了可直接落地的方案。无论是生产环境的云上部署还是本地开发验证配置的核心都收敛在storage.trace块backend选择后端各后端子块s3/gcs/azure配置端点、凭证与调优参数。结合本文给出的源码路径tempodb/backend/s3/config.go、tempodb/backend/gcs/config.go、tempodb/backend/azure/config.go与配置主文档 Storage 章节即可在任意受支持的托管存储上稳定运行 Tempo。【免费下载链接】tempoGrafana Tempo is a high volume, minimal dependency distributed tracing backend.项目地址: https://gitcode.com/GitHub_Trending/tempo1/tempo创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考