Vector 的 gcp_stackdriver_metrics 组件将指标数据批量写入 GCP Cloud Monitoring 的完整配置与实现剖析【免费下载链接】vectorA high-performance observability data pipeline.项目地址: https://gitcode.com/GitHub_Trending/vect/vector导读gcp_stackdriver_metrics是 Vector 的一个指标专用 Sink原 Stackdriver现已更名为 GCP Cloud Monitoring用于把 Vector 管道中的 metrics 通过 REST 接口批量投递到 Google Cloud Monitoring 的v3/projects/{project}/timeSeries端点。读完本文你将掌握该组件的完整配置字段含认证、资源、批处理、TLS 与重试、它支持哪些指标类型及其底层编码逻辑并能从源码层面理解 Vector 如何构造请求、控制速率与处理确认。组件定位与能力概览根据组件元数据定义 gcp_stackdriver_metrics.cue该组件的关键属性如下属性值说明组件类型sink只作为数据出口使用输入类型仅 metrics不支持 logs 和 traces支持的指标 kindcounter、gaugedistribution、histogram、set、summary均不支持投递语义at_least_once至多一次之外的 at-least-once 保证退出方式batch以批为单位发送健康检查禁用healthcheck: enabled: false有状态否stateful: false服务提供方GCP协议HTTPSSSL requiredREST 接口认证与权限方面从 CUE 中的permissions.iam段可以看到该组件要求 GCP IAM 策略monitoring: timeSeries.create且标注其同时适用于healthcheck与operation两种场景——也就是说写入时使用的服务账号必须具备timeSeries.create权限。完整配置说明下面按照配置字段逐一展开。所有字段的描述文案与仓库 生成的 CUE 配置数据 保持一致。基础字段type必填固定为gcp_stackdriver_metrics。project_id必填string要发布指标的目标 GCP 项目 ID。例如my-project。它决定了最终请求 URI 中v3/projects/{project_id}/timeSeries里的项目段。resource必填object受监控资源monitored resource指标会与这个资源关联上报。结构包含type必填受监控资源类型例如global、gce_instanceCompute Engine VM 实例其余键该资源类型对应的 descriptor 中列出的所有 label 值例如 Compute Engine VM 使用projectId、instanceId、zone。CUE 中给出的一个示例对象为resource: type: global instanceId: Twilight projectId: vector-123456 zone: us-central1-a在源码中resource对应 GcpTypedResource 结构体它携带type和labels两个字段。认证字段api_key可选stringGCP API 密钥。credentials_path可选string服务账号凭证 JSON 文件的路径。两者的取值逻辑与文档描述一致二选一配置api_key或credentials_path若都未设置检查环境变量GOOGLE_APPLICATION_CREDENTIALS中指定的文件名若环境变量也未设置则尝试获取当前运行实例GCE 实例的实例服务账号如果程序不在 GCE 上运行且上述都未配置则必须显式提供 API key 或服务账号凭证文件。在 build 方法 中可以看到认证通过self.auth.build(Scope::MonitoringWrite)构建即请求会附带monitoring写入作用域并在启动后通过auth.spawn_regenerate_token()启动后台令牌刷新。default_namespace可选string默认namespace用于没有命名空间的指标的默认 namespace。因为 Cloud Monitoring 中同名的指标只能靠 namespace 区分而并非所有指标都自带 namespace。默认值由 default_metric_namespace_value 返回即字符串namespace。batch可选批处理行为。针对该组件的默认批处理设置见 StackdriverMetricsDefaultBatchSettings参数默认值max_events1max_bytes无限制Nonetimeout_secs1.0request可选出站请求的中间件设置可配置并发/速率限制、超时与重试行为。两点值得注意该组件默认速率限制为每秒 1000 个请求由 StackdriverMetricsTowerRequestConfigDefaults 中RATE_LIMIT_NUM 1_000指定文档提示重试退避策略遵循斐波那契数列。此外还支持proxy代理与tls配置tls默认启用、可验证证书与主机名。压缩compression默认关闭——在请求构建器中 compression() 直接返回Compression::None。acknowledgements可选与retry_strategy可选acknowledgements控制端到端确认End-to-End Acknowledgements如何处理组件元数据中标记acknowledgements: trueretry_strategyHTTP 类 Sink 的可配置重试策略作用于客户端错误响应如 4xx/5xx 的分类处理。一个可用的完整配置示例sinks: stackdriver_metrics: type: gcp_stackdriver_metrics project_id: vector-123456 resource: type: gce_instance projectId: vector-123456 instanceId: Twilight zone: us-central1-a credentials_path: /path/to/service-account.json default_namespace: vector batch: max_events: 100 timeout_secs: 5 request: concurrency: 10 acknowledgements: enabled: true inputs: - my_metrics_source注意CUE 元数据显示该组件的编码不依赖通用 codecencoding: codec: enabled: false因为编码逻辑完全内置于 Stackdriver 编码器中见下文。工作流程与底层实现请求端点的构造endpoint字段被标记为serde(skip)即对配置者不可见其默认值固定为https://monitoring.googleapis.com见 default_endpoint。验证阶段会在该基础 URI 上拼接v3/projects/{project_id}/timeSeries这一拼接逻辑见 validate 方法并有单元测试 validate_produces_usable_values 断言最终 URI 为https://monitoring.googleapis.com/v3/projects/test-project/timeSeries。指标过滤只接受 Counter 与 GaugeSink 的主循环在 StackdriverMetricsSink::run_inner 中实现管道依次为过滤filter_map只放行Counter与Gauge两种指标值其他类型会打印warn!(Unsupported metric type: ...)日志后被丢弃归一化通过normalized_with_default::StackdriverMetricsNormalize()将 counter/gauge 转为绝对值make_absolute避免增量值在 at-least-once 重试场景下重复累加造成失真批处理按字节大小配置分批次请求构建交给 StackdriverMetricsRequestBuilder 编码并封装为 HTTP 请求驱动发送into_driver(self.service).run()底层服务是带http_response_retry_logic的HttpService出站请求以POSTContent-Type: application/json发出并由GcpAuthenticator附加Authorization头见 StackdriverMetricsServiceRequestBuilder::build。编码逻辑指标如何映射为 Cloud Monitoring 的 TimeSeriesStackdriverMetricsEncoder::encode_input 将一批VecMetric编码为 Cloud Monitoring REST v3 的timeSeries创建请求体核心映射规则为指标类型名custom.googleapis.com/{namespace}/metrics/{metric_name}。这里的 namespace 优先取指标自身的 namespace否则回退到default_namespace配置值Countermetric_kind为Cumulative区间的start_time为 Sink 启动时刻startedend_time为指标时间戳缺省为当前时间Gaugemetric_kind为Gauge区间start_time为None只有end_time数值类型统一以int64_value上报value_type: Int64即浮点数值会被截断为 i64标签处理指标 tags 通过into_iter_single收集为 HashMap 作为metric.labels。这里有一个重要行为与文档how_it_works中Duplicate tag names一节一致多个同名 tag 无法发送到 GCPVector 只会发送每个 tag 名的最后一个值HashMap 的收集行为天然实现“后者覆盖前者”资源关联每条 timeSeries 都携带配置中的resourcetype labels。使用限制与注意事项该组件仅接受 metrics 输入且只有counter与gauge两类会被真正发送其余类型会被静默丢弃伴随警告日志数值以 int64 上报对小数精度敏感的场景需要留意默认批大小为 1 事件 / 1 秒超时高吞吐场景建议按目标服务容量调大batch.max_events/batch.timeout_secs默认每秒 1000 请求的速率上限通常足够但若调大request.concurrency时需注意该限制健康检查被禁用无法通过vector validate之外的运行时健康接口探测到该 Sink 的连通性IAM 上必须授予服务账号monitoring: timeSeries.create权限。参考路径汇总内容路径组件文档页gcp_stackdriver_metrics.md组件元数据CUEgcp_stackdriver_metrics.cue配置结构体与验证逻辑config.rs指标过滤与主循环sink.rs请求构建与编码器request_builder.rsGcpTypedResource 定义gcp/mod.rs【免费下载链接】vectorA high-performance observability data pipeline.项目地址: https://gitcode.com/GitHub_Trending/vect/vector创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
Vector 的 gcp_stackdriver_metrics 组件：将指标数据批量写入 GCP Cloud Monitoring 的完整配置与实现剖析
Vector 的 gcp_stackdriver_metrics 组件将指标数据批量写入 GCP Cloud Monitoring 的完整配置与实现剖析【免费下载链接】vectorA high-performance observability data pipeline.项目地址: https://gitcode.com/GitHub_Trending/vect/vector导读gcp_stackdriver_metrics是 Vector 的一个指标专用 Sink原 Stackdriver现已更名为 GCP Cloud Monitoring用于把 Vector 管道中的 metrics 通过 REST 接口批量投递到 Google Cloud Monitoring 的v3/projects/{project}/timeSeries端点。读完本文你将掌握该组件的完整配置字段含认证、资源、批处理、TLS 与重试、它支持哪些指标类型及其底层编码逻辑并能从源码层面理解 Vector 如何构造请求、控制速率与处理确认。组件定位与能力概览根据组件元数据定义 gcp_stackdriver_metrics.cue该组件的关键属性如下属性值说明组件类型sink只作为数据出口使用输入类型仅 metrics不支持 logs 和 traces支持的指标 kindcounter、gaugedistribution、histogram、set、summary均不支持投递语义at_least_once至多一次之外的 at-least-once 保证退出方式batch以批为单位发送健康检查禁用healthcheck: enabled: false有状态否stateful: false服务提供方GCP协议HTTPSSSL requiredREST 接口认证与权限方面从 CUE 中的permissions.iam段可以看到该组件要求 GCP IAM 策略monitoring: timeSeries.create且标注其同时适用于healthcheck与operation两种场景——也就是说写入时使用的服务账号必须具备timeSeries.create权限。完整配置说明下面按照配置字段逐一展开。所有字段的描述文案与仓库 生成的 CUE 配置数据 保持一致。基础字段type必填固定为gcp_stackdriver_metrics。project_id必填string要发布指标的目标 GCP 项目 ID。例如my-project。它决定了最终请求 URI 中v3/projects/{project_id}/timeSeries里的项目段。resource必填object受监控资源monitored resource指标会与这个资源关联上报。结构包含type必填受监控资源类型例如global、gce_instanceCompute Engine VM 实例其余键该资源类型对应的 descriptor 中列出的所有 label 值例如 Compute Engine VM 使用projectId、instanceId、zone。CUE 中给出的一个示例对象为resource: type: global instanceId: Twilight projectId: vector-123456 zone: us-central1-a在源码中resource对应 GcpTypedResource 结构体它携带type和labels两个字段。认证字段api_key可选stringGCP API 密钥。credentials_path可选string服务账号凭证 JSON 文件的路径。两者的取值逻辑与文档描述一致二选一配置api_key或credentials_path若都未设置检查环境变量GOOGLE_APPLICATION_CREDENTIALS中指定的文件名若环境变量也未设置则尝试获取当前运行实例GCE 实例的实例服务账号如果程序不在 GCE 上运行且上述都未配置则必须显式提供 API key 或服务账号凭证文件。在 build 方法 中可以看到认证通过self.auth.build(Scope::MonitoringWrite)构建即请求会附带monitoring写入作用域并在启动后通过auth.spawn_regenerate_token()启动后台令牌刷新。default_namespace可选string默认namespace用于没有命名空间的指标的默认 namespace。因为 Cloud Monitoring 中同名的指标只能靠 namespace 区分而并非所有指标都自带 namespace。默认值由 default_metric_namespace_value 返回即字符串namespace。batch可选批处理行为。针对该组件的默认批处理设置见 StackdriverMetricsDefaultBatchSettings参数默认值max_events1max_bytes无限制Nonetimeout_secs1.0request可选出站请求的中间件设置可配置并发/速率限制、超时与重试行为。两点值得注意该组件默认速率限制为每秒 1000 个请求由 StackdriverMetricsTowerRequestConfigDefaults 中RATE_LIMIT_NUM 1_000指定文档提示重试退避策略遵循斐波那契数列。此外还支持proxy代理与tls配置tls默认启用、可验证证书与主机名。压缩compression默认关闭——在请求构建器中 compression() 直接返回Compression::None。acknowledgements可选与retry_strategy可选acknowledgements控制端到端确认End-to-End Acknowledgements如何处理组件元数据中标记acknowledgements: trueretry_strategyHTTP 类 Sink 的可配置重试策略作用于客户端错误响应如 4xx/5xx 的分类处理。一个可用的完整配置示例sinks: stackdriver_metrics: type: gcp_stackdriver_metrics project_id: vector-123456 resource: type: gce_instance projectId: vector-123456 instanceId: Twilight zone: us-central1-a credentials_path: /path/to/service-account.json default_namespace: vector batch: max_events: 100 timeout_secs: 5 request: concurrency: 10 acknowledgements: enabled: true inputs: - my_metrics_source注意CUE 元数据显示该组件的编码不依赖通用 codecencoding: codec: enabled: false因为编码逻辑完全内置于 Stackdriver 编码器中见下文。工作流程与底层实现请求端点的构造endpoint字段被标记为serde(skip)即对配置者不可见其默认值固定为https://monitoring.googleapis.com见 default_endpoint。验证阶段会在该基础 URI 上拼接v3/projects/{project_id}/timeSeries这一拼接逻辑见 validate 方法并有单元测试 validate_produces_usable_values 断言最终 URI 为https://monitoring.googleapis.com/v3/projects/test-project/timeSeries。指标过滤只接受 Counter 与 GaugeSink 的主循环在 StackdriverMetricsSink::run_inner 中实现管道依次为过滤filter_map只放行Counter与Gauge两种指标值其他类型会打印warn!(Unsupported metric type: ...)日志后被丢弃归一化通过normalized_with_default::StackdriverMetricsNormalize()将 counter/gauge 转为绝对值make_absolute避免增量值在 at-least-once 重试场景下重复累加造成失真批处理按字节大小配置分批次请求构建交给 StackdriverMetricsRequestBuilder 编码并封装为 HTTP 请求驱动发送into_driver(self.service).run()底层服务是带http_response_retry_logic的HttpService出站请求以POSTContent-Type: application/json发出并由GcpAuthenticator附加Authorization头见 StackdriverMetricsServiceRequestBuilder::build。编码逻辑指标如何映射为 Cloud Monitoring 的 TimeSeriesStackdriverMetricsEncoder::encode_input 将一批VecMetric编码为 Cloud Monitoring REST v3 的timeSeries创建请求体核心映射规则为指标类型名custom.googleapis.com/{namespace}/metrics/{metric_name}。这里的 namespace 优先取指标自身的 namespace否则回退到default_namespace配置值Countermetric_kind为Cumulative区间的start_time为 Sink 启动时刻startedend_time为指标时间戳缺省为当前时间Gaugemetric_kind为Gauge区间start_time为None只有end_time数值类型统一以int64_value上报value_type: Int64即浮点数值会被截断为 i64标签处理指标 tags 通过into_iter_single收集为 HashMap 作为metric.labels。这里有一个重要行为与文档how_it_works中Duplicate tag names一节一致多个同名 tag 无法发送到 GCPVector 只会发送每个 tag 名的最后一个值HashMap 的收集行为天然实现“后者覆盖前者”资源关联每条 timeSeries 都携带配置中的resourcetype labels。使用限制与注意事项该组件仅接受 metrics 输入且只有counter与gauge两类会被真正发送其余类型会被静默丢弃伴随警告日志数值以 int64 上报对小数精度敏感的场景需要留意默认批大小为 1 事件 / 1 秒超时高吞吐场景建议按目标服务容量调大batch.max_events/batch.timeout_secs默认每秒 1000 请求的速率上限通常足够但若调大request.concurrency时需注意该限制健康检查被禁用无法通过vector validate之外的运行时健康接口探测到该 Sink 的连通性IAM 上必须授予服务账号monitoring: timeSeries.create权限。参考路径汇总内容路径组件文档页gcp_stackdriver_metrics.md组件元数据CUEgcp_stackdriver_metrics.cue配置结构体与验证逻辑config.rs指标过滤与主循环sink.rs请求构建与编码器request_builder.rsGcpTypedResource 定义gcp/mod.rs【免费下载链接】vectorA high-performance observability data pipeline.项目地址: https://gitcode.com/GitHub_Trending/vect/vector创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考