将OpenTelemetry追踪导出至GCP指南
内容提要
本文介绍如何将FastAPI应用的OpenTelemetry追踪导出至GCP，主要有两种方法：使用`opentelemetry-exporter-gcp-trace`，需通过`resource_regex`参数复制资源标签到span；或使用GCP原生OTLP telemetry API，需设置`gcp.project_id`资源属性，并配置认证凭据。文中还提供了代码示例和常见错误解决方法。
延伸解读
两种导出方式的取舍
文章介绍了两种将OpenTelemetry追踪导出到GCP的方法：使用`opentelemetry-exporter-gcp-trace`和GCP原生OTLP telemetry API。前者封装了细节，但依赖Google专有API，不完全兼容OpenTelemetry，因此需要`resource_regex`参数来复制资源标签。后者是GCP从2026年2月开始原生支持OTLP，更标准，但需要手动设置`gcp.project_id`资源属性。选择时需权衡易用性与标准兼容性。
常见错误与解决
使用GCP telemetry API时，若未设置`gcp.project_id`，导出会报`INVALID_ARGUMENT`错误。解决方法是设置环境变量`OTEL_RESOURCE_ATTRIBUTES="gcp.project_id=my-demo-project"`或在代码中通过`Resource.create`添加该属性。此外，认证凭据需通过`google.auth.default()`获取，并配置gRPC通道。这些细节是成功导出的关键。
Q&A
如何将FastAPI应用的OpenTelemetry追踪导出到GCP？
主要有两种方法：一是使用`opentelemetry-exporter-gcp-trace`包，通过`CloudTraceSpanExporter`导出；二是使用GCP原生OTLP telemetry API，通过`OTLPSpanExporter`导出到`telemetry.googleapis.com`。
使用opentelemetry-exporter-gcp-trace时，为什么Trace Explorer中服务名为空？如何解决？
因为`CloudTraceSpanExporter`默认不会将资源标签复制到span，导致服务名缺失。需要通过`resource_regex`参数指定要复制的资源标签，例如`resource_regex=r"service\..*"`来复制以`service.`开头的标签。
使用GCP telemetry API导出追踪时，遇到INVALID_ARGUMENT错误怎么办？
该错误通常是因为未设置`gcp.project_id`资源属性。可以通过环境变量`OTEL_RESOURCE_ATTRIBUTES="gcp.project_id=my-demo-project"`或在代码中设置资源属性`"gcp.project_id": "my-demo-project"`来解决。
使用GCP telemetry API导出追踪时，如何配置认证凭据？
使用`google.auth.default()`获取默认凭据，然后通过`AuthMetadataPlugin`和`grpc.composite_channel_credentials`创建带认证的gRPC通道凭据，最后传给`OTLPSpanExporter`的`credentials`参数。
opentelemetry-exporter-gcp-trace和GCP telemetry API两种导出方式有何区别？
`opentelemetry-exporter-gcp-trace`使用Google专有的trace API，不完全兼容OpenTelemetry，因此需要`resource_regex`参数来复制资源标签；而GCP telemetry API原生支持OTLP，更标准，但需要设置`gcp.project_id`资源属性。
在代码中如何设置`gcp.project_id`资源属性？
在创建`Resource`时，在`attributes`字典中添加`"gcp.project_id": "my-demo-project"`，例如：`Resource.create(attributes={"service.name": "demo-service", "gcp.project_id": "my-demo-project"})`。
