python-micrometer-gcp-cloud-monitoring

What this skill does

# Micrometer GCP Cloud Monitoring Integration

## Quick Start

Export metrics to Cloud Monitoring in 3 steps:

**1. Add dependencies:**
```xml
<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>
```

**2. Configure export:**
```yaml
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}
```

**3. Grant IAM permission:**
```bash
gcloud projects add-iam-policy-binding PROJECT_ID \
  --member="serviceAccount:SERVICE_ACCOUNT@PROJECT_ID.iam.gserviceaccount.com" \
  --role="roles/monitoring.metricWriter"
```

See [references/workload-identity-setup.md](references/workload-identity-setup.md) for complete Workload Identity setup.

## Table of Contents

1. [When to Use](#when-to-use)
2. [Configuration](#configuration)
3. [Testing](#testing)
4. [Supporting Files](#supporting-files)
5. [Requirements](#requirements)
6. [Anti-Patterns](#anti-patterns)

## When to Use

Use this skill when you need to:

- Export metrics to GCP Cloud Monitoring for GKE deployments
- Configure Workload Identity for secure pod authentication
- Set resource labels for filtering in Cloud Console
- Correlate metrics with GKE, Pub/Sub, Cloud SQL services
- Create dashboards and alerts in Cloud Monitoring

**When NOT to use:**
- Prometheus-only environments (use Prometheus registry)
- Before basic Micrometer setup (use `python-micrometer-metrics-setup`)
- Local development (use Prometheus locally)
- Without Workload Identity (requires GKE 1.12+)

## Configuration

### Basic Configuration

```yaml
# 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 Environment Variables

```yaml
# 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"
```

### Custom Metric Configuration

```java
@Configuration
public class CloudMonitoringConfig {

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

## Testing

### Verify Export in Logs

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

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

### Query Metrics via CLI

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

### View in Cloud Console

1. Open GCP Console → Cloud Monitoring → Metrics Explorer
2. Select resource: "Kubernetes Container"
3. Filter by cluster
4. View metric: custom.googleapis.com/...

## Supporting Files

| File | Purpose |
|------|---------|
| [references/workload-identity-setup.md](references/workload-identity-setup.md) | Complete Workload Identity configuration guide |
| [references/dashboards-and-alerting.md](references/dashboards-and-alerting.md) | Create dashboards and alert policies with Terraform |

## Requirements

- Spring Boot 2.1+ with Actuator
- `micrometer-registry-stackdriver` dependency
- GCP Project with Cloud Monitoring API enabled
- GKE cluster with Workload Identity enabled
- IAM role: `roles/monitoring.metricWriter`
- Java 11+

## Anti-Patterns

```yaml
# ❌ 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
```

## See Also

- [python-micrometer-cardinality-control](../python-micrometer-cardinality-control/SKILL.md) - Manage metric cardinality
- [python-micrometer-business-metrics](../python-micrometer-business-metrics/SKILL.md) - Create business metrics
- [python-micrometer-metrics-setup](../python-micrometer-metrics-setup/SKILL.md) - Initial Micrometer setup