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

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 side-car OpenTelemetry.

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

Objectifs

Écrire, créer et déployer un service sur Cloud Run avec le side-car OpenTelemetry
Générer des métriques personnalisées et les transmettre à Google Cloud Managed Service pour Prometheus.

Coûts

Dans ce document, vous utilisez les composants facturables suivants de Google Cloud :

Obtenez une estimation des coûts en fonction de votre utilisation prévue à l'aide du simulateur de coût. Les nouveaux utilisateurs de Google Cloud peuvent bénéficier d'un essai gratuit.

Avant de commencer

Connectez-vous à votre compte Google Cloud. Si vous débutez sur Google Cloud, créez un compte pour évaluer les performances de nos produits en conditions réelles. Les nouveaux clients bénéficient également de 300 $ de crédits gratuits pour exécuter, tester et déployer des charges de travail.

Dans Google Cloud Console, sur la page de sélection du projet, sélectionnez ou créez un projet Google Cloud.

Accéder au sélecteur de projet

Vérifiez que la facturation est activée pour votre projet Google Cloud.

Dans Google Cloud Console, sur la page de sélection du projet, sélectionnez ou créez un projet Google Cloud.

Accéder au sélecteur de projet

Vérifiez que la facturation est activée pour votre projet Google Cloud.

Activer les API Cloud Run, Cloud Monitoring, Artifact Registry, and Cloud Build .
Activer les API

Installez et initialisez gcloud CLI.
Mettez à jour Google Cloud CLI : gcloud components update

Rôles requis

Pour obtenir les autorisations nécessaires pour suivre le tutoriel, demandez à votre administrateur de vous accorder les rôles IAM suivants sur votre projet :

Éditeur Cloud Build (roles/cloudbuild.builds.editor)
Administrateur Cloud Run (roles/run.admin)
Créateur de comptes de service (roles/iam.serviceAccountCreator)
Administrateur de projet IAM (roles/resourcemanager.projectIamAdmin)
Rédacteur de métriques Monitoring (roles/monitoring.metricWriter)
Utilisateur du compte de service (roles/iam.serviceAccountUser)
Consommateur Service Usage (roles/serviceusage.serviceUsageConsumer)
Administrateur de l'espace de stockage (roles/storage.admin)

Pour en savoir plus sur l'attribution de rôles, consultez la section Gérer les accès.

Vous pouvez également obtenir les autorisations requises via des rôles personnalisés ou d'autres rôles prédéfinis.

Notez également que le compte de service Cloud Run doit disposer du rôle Rédacteur de métriques Monitoring (roles/monitoring.metricWriter). Le compte de service Compute Engine par défaut dispose par défaut de ce rôle, mais vous devrez peut-être l'ajouter si vous avez modifié les autorisations de ce compte ou si vous utilisez un autre compte de service.

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 :

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.
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 produits Google Cloud 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

asia-east1 (Taïwan)
asia-northeast1 (Tokyo)
asia-northeast2 (Osaka)
europe-north1 (Finlande) Faibles émissions de CO₂
europe-southwest1 (Madrid)
europe-west1 (Belgique) Faibles émissions de CO₂
europe-west4 (Pays-Bas)
europe-west8 (Milan)
europe-west9 (Paris) Faibles émissions de CO₂
me-west1 (Tel Aviv)
us-central1 (Iowa) Faibles émissions de CO₂
us-east1 (Caroline du Sud)
us-east4 (Virginie du Nord)
us-east5 (Columbus)
us-south1 (Dallas)
us-west1 (Oregon) Faibles émissions de CO₂

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-south1 (Mumbai, Inde)
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) Faibles émissions de CO₂
europe-west3 (Francfort, Allemagne) Faibles émissions de CO₂
europe-west6 (Zurich, Suisse) Faibles émissions de CO₂
me-central1 (Doha)
me-central2 (Dammam)
northamerica-northeast1 (Montréal) Faibles émissions de CO₂
northamerica-northeast2 (Toronto) Faibles émissions de CO₂
southamerica-east1 (São Paulo, Brésil) Faibles émissions de CO₂
southamerica-west1 (Santiago, Chili) Faibles émissions de CO₂
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 console Google 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 :

Clonez le dépôt de l'exemple d'application sur votre machine locale :
Go
```
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.
Accédez au répertoire contenant l'exemple de code Cloud Run :
Go
```
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.

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 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(
			semconv.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.21 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 OpenTelemetry personnalisé :

Fichier de configuration pour le collecteur OpenTelemetry.

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:

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 otel/opentelemetry-collector-contrib:0.75.0

COPY collector-config.yaml /etc/otelcol-contrib/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 :

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.
Créez votre 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.

Déployez votre application :

YAML

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

Remplacez les éléments suivants :
- CONTAINER_PORT par le port sur lequel écoute le conteneur d'entrée de votre service. Par défaut, il s'agit du port 8080.
- SERVICE-NAME par le nom que vous souhaitez donner à votre service, par exemple custom-metrics-sample-service.

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.

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{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

Effectuer un nettoyage

Si vous avez créé un projet pour ce tutoriel, supprimez-le. Si vous avez utilisé un projet existant et que vous souhaitez le conserver sans les modifications du présent tutoriel, supprimez les ressources créées pour ce tutoriel.

Supprimer le projet

Le moyen le plus simple d'empêcher la facturation est de supprimer le projet que vous avez créé pour ce tutoriel.

Pour supprimer le projet :

Attention : La suppression d'un projet aura les effets suivants :

Tout le contenu du projet est supprimé. Si vous avez utilisé un projet existant pour les tâches de ce document, lorsque vous le supprimez, vous supprimez également tout autre travail effectué dans le projet.
Les ID de projets personnalisés sont perdus. Lorsque vous avez créé ce projet, vous avez peut-être créé un ID de projet personnalisé que vous souhaitez utiliser à l'avenir. Pour conserver les URL qui utilisent l'ID de projet, telle qu'une URL appspot.com, supprimez les ressources sélectionnées dans le projet au lieu de supprimer l'ensemble du projet.

Si vous envisagez d'explorer plusieurs architectures, tutoriels et guides de démarrage rapide, réutiliser des projets peut vous aider à ne pas dépasser les limites de quotas des projets.

Dans la console Google Cloud, accédez à la page Gérer les ressources.
Accéder à la page Gérer les ressources
Dans la liste des projets, sélectionnez le projet que vous souhaitez supprimer, puis cliquez sur Supprimer.
Dans la boîte de dialogue, saisissez l'ID du projet, puis cliquez sur Arrêter pour supprimer le projet.

Supprimer les ressources du tutoriel

Supprimez le service Cloud Run que vous avez déployé dans ce tutoriel :
```
gcloud run services delete SERVICE-NAME
```
Où SERVICE-NAME est le nom de service que vous avez choisi.

Vous pouvez également supprimer des services Cloud Run à partir de Google Cloud Console.
Supprimez la configuration régionale gcloud par défaut que vous avez ajoutée lors de la configuration du tutoriel :
```
 gcloud config unset run/region
```
Supprimez la configuration du projet :
```
 gcloud config unset project
```
Supprimez les autres ressources Google Cloud créées dans ce tutoriel :
- Supprimer le dépôt Docker Artifact Registry

Étapes suivantes

D'autres exemples, y compris des exemples pour les traces et les journaux, sont disponibles sur GitHub.