python-micrometer-gcp-cloud-monitoring

用途

本技能用于将 Micrometer 指标导出到 GCP Cloud Monitoring（Stackdriver），适用于 GKE 部署环境。当需要在 Kubernetes 环境中设置指标导出、为 Pod 配置 Workload Identity 安全认证、设置资源标签以便在 Cloud Console 中过滤、将指标与 GKE、Pub/Sub、Cloud SQL 服务关联，或在 Cloud Monitoring 中创建仪表盘与告警时使用。

不适用场景：仅使用 Prometheus 的环境（应使用 Prometheus registry）；尚未完成基础 Micrometer 设置之前（应使用 python-micrometer-metrics-setup）；本地开发（本地应使用 Prometheus）；未启用 Workload Identity 的环境（需要 GKE 1.12+）。

快速开始

三步导出指标到 Cloud Monitoring。

添加依赖：

<dependency>
    <groupId>io.micrometer</groupId>
    <artifactId>micrometer-registry-stackdriver</artifactId>
</dependency>
<dependency>
    <groupId>com.google.cloud</groupId>
    <artifactId>spring-cloud-gcp-starter-metrics</artifactId>
</dependency>

配置导出：

management:
  metrics:
    export:
      stackdriver:
        enabled: true
        project-id: ${GCP_PROJECT_ID}
        resource-type: k8s_container
        step: 1m
        resource-labels:
          cluster_name: ${GKE_CLUSTER_NAME}
          namespace_name: ${NAMESPACE}
          pod_name: ${POD_NAME}

授予 IAM 权限：

gcloud projects add-iam-policy-binding PROJECT_ID \
  --member="serviceAccount:SERVICE_ACCOUNT@PROJECT_ID.iam.gserviceaccount.com" \
  --role="roles/monitoring.metricWriter"

完整的 Workload Identity 设置见 references/workload-identity-setup.md。

配置

基础配置

# application.yml
management:
  metrics:
    export:
      stackdriver:
        enabled: ${STACKDRIVER_ENABLED:true}
        project-id: ${GCP_PROJECT_ID}
        step: 1m  # Export frequency
        resource-type: k8s_container  # GKE resource type

        # Resource labels (appear on every metric)
        resource-labels:
          cluster_name: ${GKE_CLUSTER_NAME}
          namespace_name: ${NAMESPACE}
          pod_name: ${POD_NAME}
          container_name: ${CONTAINER_NAME:app}
          environment: ${ENVIRONMENT:production}
          region: ${GCP_REGION:europe-west2}

    # Common tags (filterable in queries)
    tags:
      application: ${spring.application.name}
      version: ${BUILD_VERSION:unknown}

    # Histogram buckets for latency metrics
    distribution:
      percentiles-histogram:
        http.server.requests: true
      slo:
        http.server.requests: 10ms,50ms,100ms,200ms,500ms,1s,2s,5s

Kubernetes 部署环境变量

# deployment.yaml
env:
  - name: GCP_PROJECT_ID
    value: "my-project"
  - name: GKE_CLUSTER_NAME
    value: "my-cluster"
  - name: NAMESPACE
    valueFrom:
      fieldRef:
        fieldPath: metadata.namespace
  - name: POD_NAME
    valueFrom:
      fieldRef:
        fieldPath: metadata.name
  - name: CONTAINER_NAME
    value: "app"

自定义指标配置

@Configuration
public class CloudMonitoringConfig {

    @Bean
    public MeterRegistryCustomizer<MeterRegistry> commonTags() {
        return registry -> registry.config().commonTags(
            "service", "my-api",
            "component", "backend"
        );
    }
}

测试

通过日志验证导出

# Check pod logs for metric export success
kubectl logs -f deployment/my-api -n my-namespace

# Look for: "Successfully published X metrics to Stackdriver"

通过 CLI 查询指标

# List exported metrics
gcloud monitoring metrics-descriptors list \
  --filter="metric.type:custom.googleapis.com"

在 Cloud Console 中查看

打开 GCP Console → Cloud Monitoring → Metrics Explorer；选择资源 "Kubernetes Container"；按 cluster 过滤；查看指标 custom.googleapis.com/...。

支持文件

文件	用途
references/workload-identity-setup.md	完整的 Workload Identity 配置指南
references/dashboards-and-alerting.md	使用 Terraform 创建仪表盘和告警策略

要求

Spring Boot 2.1+ 且启用 Actuator
micrometer-registry-stackdriver 依赖
已启用 Cloud Monitoring API 的 GCP 项目
已启用 Workload Identity 的 GKE 集群
IAM 角色：roles/monitoring.metricWriter
Java 11+

反模式

# ❌ Missing resource labels (hard to filter)
resource-labels:
  environment: production

# ✅ Complete resource labels
resource-labels:
  cluster_name: my-cluster
  namespace_name: my-namespace
  pod_name: ${POD_NAME}

# ❌ High cardinality resource labels (memory issues)
resource-labels:
  pod_ip: ${POD_IP}       # Changes constantly
  user_id: ${USER_ID}     # Unbounded

# ✅ Stable, bounded labels
resource-labels:
  cluster_name: my-cluster
  environment: production

参见

python-micrometer-cardinality-control - 管理指标基数
python-micrometer-business-metrics - 创建业务指标
python-micrometer-metrics-setup - Micrometer 初始设置