Écrire des métriques OTLP à l'aide d'un side-car OpenTelemetry Collector

Ce tutoriel explique comment écrire, déployer et appeler un service Cloud Run qui transmet des métriques OLTP personnalisées à Google Cloud Managed Service pour Prometheus à l'aide du collecteur OpenTelemetry intégré à Google en tant que side-car. Pour en savoir plus sur le collecteur conçu par Google, consultez Présentation du collecteur OpenTelemetry conçu par Google.

Si vous disposez d'un service Cloud Run qui signale les métriques Prometheus, utilisez plutôt le side-car Prometheus pour Cloud Run.

Configurer les paramètres par défaut de gcloud

Pour configurer gcloud avec les valeurs par défaut pour votre service Cloud Run, procédez comme suit :

  1. Définissez le projet par défaut :

    gcloud config set project PROJECT_ID

    Remplacez PROJECT_ID par le nom du projet que vous avez créé pour ce tutoriel.

  2. Configurez gcloud pour la région choisie :

    gcloud config set run/region REGION

    Remplacez REGION par la région Cloud Run compatible de votre choix.

Emplacements Cloud Run

Cloud Run est régional, ce qui signifie que l'infrastructure qui exécute vos services Cloud Run est située dans une région spécifique et gérée par Google pour être disponible de manière redondante dans toutes les zones de cette région.

Lors de la sélection de la région dans laquelle exécuter vos services Cloud Run, vous devez tout d'abord considérer vos exigences en matière de latence, de disponibilité et de durabilité. Vous pouvez généralement sélectionner la région la plus proche de vos utilisateurs, mais vous devez tenir compte de l'emplacement des autres Google Cloudproduits utilisés par votre service Cloud Run. L'utilisation conjointe de produits Google Cloud dans plusieurs emplacements peut avoir une incidence sur la latence et le coût de votre service.

Cloud Run est disponible dans les régions suivantes :

Soumis aux tarifs de niveau 1

Soumis aux tarifs de niveau 2

  • africa-south1 (Johannesburg)
  • asia-east2 (Hong Kong)
  • asia-northeast3 (Séoul, Corée du Sud)
  • asia-southeast1 (Singapour)
  • asia-southeast2 (Jakarta)
  • asia-south2 (Delhi, Inde)
  • australia-southeast1 (Sydney)
  • australia-southeast2 (Melbourne)
  • europe-central2 (Varsovie, Pologne)
  • europe-west10 (Berlin)
  • europe-west12 (Turin)
  • europe-west2 (Londres, Royaume-Uni) icône feuille Faibles émissions de CO2
  • europe-west3 (Francfort, Allemagne)
  • europe-west6 (Zurich, Suisse) icône feuille Faibles émissions de CO2
  • me-central1 (Doha)
  • me-central2 (Dammam)
  • northamerica-northeast1 (Montréal) icône feuille Faibles émissions de CO2
  • northamerica-northeast2 (Toronto) icône feuille Faibles émissions de CO2
  • southamerica-east1 (São Paulo, Brésil) icône feuille Faibles émissions de CO2
  • southamerica-west1 (Santiago, Chili) icône feuille Faibles émissions de CO2
  • us-west2 (Los Angeles)
  • us-west3 (Salt Lake City)
  • us-west4 (Las Vegas)

Si vous avez déjà créé un service Cloud Run, vous pouvez afficher la région dans le tableau de bord Cloud Run de la consoleGoogle Cloud .

Créer un dépôt d'images Artifact Registry

Créez un dépôt Docker Artifact Registry pour héberger l'exemple d'image de service :

gcloud artifacts repositories create run-otel \
    --repository-format=docker \
    --location=REGION \
    --project=PROJECT_ID

Remplacez les éléments suivants :

  • PROJECT_ID par le nom du projet que vous avez créé pour ce tutoriel ;
  • REGION par la région Cloud Run compatible de votre choix.

Récupérer l'exemple de code

Pour récupérer l’exemple de code à utiliser, procédez comme suit :

  1. Clonez le dépôt de l'exemple d'application sur votre machine locale :

    Accéder

    git clone https://github.com/GoogleCloudPlatform/golang-samples.git

    Vous pouvez également télécharger l'exemple en tant que fichier ZIP et l'extraire.

  2. Accédez au répertoire contenant l'exemple de code Cloud Run :

    Accéder

    cd golang-samples/run/custom-metrics/

Comprendre le code

Le code de ce tutoriel comprend les éléments suivants :

  • Un serveur qui gère les requêtes entrantes et génère une métrique nommée sidecar_sample_counter_total.
package main

import (
	"context"
	"fmt"
	"log"
	"net/http"
	"os"

	"go.opentelemetry.io/otel/exporters/otlp/otlpmetric/otlpmetricgrpc"
	"go.opentelemetry.io/otel/metric"
	sdkmetric "go.opentelemetry.io/otel/sdk/metric"
	"go.opentelemetry.io/otel/sdk/resource"
	semconv "go.opentelemetry.io/otel/semconv/v1.24.0"
)

var counter metric.Int64Counter

func main() {
	ctx := context.Background()
	shutdown := setupCounter(ctx)
	defer shutdown(ctx)

	port := os.Getenv("PORT")
	if port == "" {
		port = "8080"
		log.Printf("defaulting to port %s", port)
	}

	http.HandleFunc("/", handler)
	log.Fatal(http.ListenAndServe(":"+port, nil))
}

func handler(w http.ResponseWriter, r *http.Request) {
	counter.Add(context.Background(), 100)
	fmt.Fprintln(w, "Incremented sidecar_sample_counter_total metric!")
}

func setupCounter(ctx context.Context) func(context.Context) error {
	serviceName := os.Getenv("K_SERVICE")
	if serviceName == "" {
		serviceName = "sample-cloud-run-app"
	}
	r, err := resource.Merge(
		resource.Default(),
		resource.NewWithAttributes(
			resource.Default().SchemaURL(),
			semconv.ServiceName(serviceName),
		),
	)
	if err != nil {
		log.Fatalf("Error creating resource: %v", err)
	}

	exporter, err := otlpmetricgrpc.New(ctx,
		otlpmetricgrpc.WithInsecure(),
	)
	if err != nil {
		log.Fatalf("Error creating exporter: %s", err)
	}
	provider := sdkmetric.NewMeterProvider(
		sdkmetric.WithReader(sdkmetric.NewPeriodicReader(exporter)),
		sdkmetric.WithResource(r),
	)

	meter := provider.Meter("example.com/metrics")
	counter, err = meter.Int64Counter("sidecar-sample-counter")
	if err != nil {
		log.Fatalf("Error creating counter: %s", err)
	}
	return provider.Shutdown
}
  • Un fichier Dockerfile qui définit l'environnement d'exploitation du service.
FROM golang:1.24 as builder
WORKDIR /app
COPY . .
RUN CGO_ENABLED=0 GOOS=linux go build -o sample-app

FROM alpine:3
RUN apk add --no-cache ca-certificates
COPY --from=builder /app/sample-app /sample-app
CMD ["/sample-app"]

L'exemple inclut également des fichiers stockés dans le sous-répertoire collector permettant de créer un collecteur personnalisé :

  • Fichier de configuration pour le collecteur.

    receivers:
      otlp:
        protocols:
          grpc:
          http:
    
    processors:
      batch:
        # batch metrics before sending to reduce API usage
        send_batch_max_size: 200
        send_batch_size: 200
        timeout: 5s
    
      memory_limiter:
        # drop metrics if memory usage gets too high
        check_interval: 1s
        limit_percentage: 65
        spike_limit_percentage: 20
    
      # automatically detect Cloud Run resource metadata                                                                                                                                               
      resourcedetection:
        detectors: [env, gcp]
        timeout: 2s
        override: false
    
      resource:
        attributes:
        # add instance_id as a resource attribute
        - key: service.instance.id
          from_attribute: faas.id
          action: upsert
          # parse service name from K_SERVICE Cloud Run variable                                                                                                                                       
        - key: service.name
          value: ${env:K_SERVICE}
          action: insert
    
    exporters:
      googlemanagedprometheus: # Note: this is intentionally left blank   
    
    extensions:
      health_check:
        endpoint: 0.0.0.0:13133
    service:
      extensions: [health_check]
      pipelines:
        metrics:
          receivers: [otlp]
          processors: [batch, memory_limiter, resourcedetection, resource]
          exporters: [googlemanagedprometheus]
  • Un fichier Dockerfile qui regroupe la configuration fournie dans une image de collecteur en amont.

    FROM us-docker.pkg.dev/cloud-ops-agents-artifacts/google-cloud-opentelemetry-collector/otelcol-google:0.121.0
    
    COPY collector-config.yaml /etc/otelcol-google/config.yaml

Transmettre le code

La transmission du code se déroule en trois étapes : création d'une image de conteneur avec Cloud Build, importation de l'image de conteneur dans Artifact Registry, puis déploiement de cette image dans Cloud Run.

Pour transmettre votre code, procédez comme suit :

  1. Créez votre exemple de conteneur de service et publiez-le dans Artifact Registry :

    gcloud builds submit --tag REGION-docker.pkg.dev/PROJECT_ID/run-otel/sample-metrics-app

    En cas de réussite, vous devriez voir un message SUCCESS contenant l'ID, l'heure de création et le nom de l'image. Celle-ci est stockée dans Artifact Registry et peut être réutilisée au besoin.

  2. Créez votre conteneur collecteur et publiez-le dans Artifact Registry :

    gcloud builds submit collector --tag REGION-docker.pkg.dev/PROJECT_ID/run-otel/otel-collector-metrics

    En cas de réussite, vous devriez voir un message SUCCESS contenant l'ID, l'heure de création et le nom de l'image. Celle-ci est stockée dans Artifact Registry et peut être réutilisée au besoin.

  3. Déployez votre application :

    YAML

    1. Créez un fichier nommé service.yaml contenant les éléments suivants :

      apiVersion: serving.knative.dev/v1
      kind: Service
      metadata:
        name: SERVICE-NAME
        annotations:
          run.googleapis.com/launch-stage: BETA
      spec:
        template:
          metadata:
            annotations:
              run.googleapis.com/container-dependencies: "{app:[collector]}"
          spec:
            containers:
            - image: REGION-docker.pkg.dev/PROJECT_ID/run-otel/sample-metrics-app
              name: app
              ports:
              - containerPort: CONTAINER_PORT
              env:
              - name: "OTEL_EXPORTER_OTLP_ENDPOINT"
                value: "http://localhost:4317"
            - image: REGION-docker.pkg.dev/PROJECT_ID/run-otel/otel-collector-metrics
              name: collector
              startupProbe:
                httpGet:
                  path: /
                  port: 13133
      
    2. Remplacez les éléments suivants :
  4. Créez le service à l'aide de la commande suivante :

    gcloud run services replace service.yaml

    Cette commande renvoie une URL de service. Utilisez cette URL pour tester l'exemple d'application dans la section Tester le service.

Tester le service

À l'aide de l'URL obtenue de la commande gcloud run dans la section Transmettre le code, connectez-vous au service pour générer des exemples de métriques (vous pouvez exécuter cette commande à plusieurs reprises pour générer des données plus intéressantes) :

curl -H \
"Authorization: Bearer $(gcloud auth print-identity-token)" \
SERVICE_URL

Remplacez SERVICE_URL par l'URL de votre service.

Accédez ensuite à l'explorateur de métriques dans la section Cloud Monitoring de la console Google Cloud , puis sélectionnez la métrique sidecar_sample_counter_total.

Métrique personnalisée affichée dans l'interface utilisateur de l'explorateur de métriques

Vous pouvez également interroger les métriques à l'aide de PromQL. Par exemple, la requête ci-dessous filtrera les métriques selon l'ID d'instance Cloud Run :

sidecar_sample_counter_total{instance="INSTANCE_ID"}

Remplacez INSTANCE_ID par l'ID de n'importe quelle instance de votre service (disponible dans les journaux d'instance ou à partir du serveur de métadonnées).

Cette requête génère un graphique semblable à celui-ci :

Métrique personnalisée interrogée à l'aide de PromQL