OTLP-Messwerte mit einem OpenTelemetry-Sidecar schreiben

---

In dieser Anleitung erfahren Sie, wie Sie einen Cloud Run-Dienst schreiben, bereitstellen und aufrufen, der benutzerdefinierte OTLP-Messwerte an Google Cloud Managed Service for Prometheus mithilfe des OpenTelemetry-Sidecars meldet.

Wenn Sie einen Cloud Run-Dienst haben, der Prometheus-Messwerte meldet, verwenden Sie stattdessen die Prometheus-Sidecar-Datei für Cloud Run.

Ziele

• Einen Dienst mit dem OpenTelemetry-Sidecar in Cloud Run schreiben, erstellen und bereitstellen.
• Benutzerdefinierte Messwerte generieren und an Google Cloud Managed Service for Prometheus melden.

Kosten

In diesem Dokument verwenden Sie die folgenden kostenpflichtigen Komponenten von Google Cloud:

• Cloud Build
• Artifact Registry
• Google Cloud Managed Service For Prometheus
• Cloud Run

Mit dem Preisrechner können Sie eine Kostenschätzung für Ihre voraussichtliche Nutzung vornehmen. Neuen Google Cloud-Nutzern steht möglicherweise eine kostenlose Testversion zur Verfügung.

Hinweise

1. Sign in to your Google Cloud account. If you're new to Google Cloud, create an account to evaluate how our products perform in real-world scenarios. New customers also get $300 in free credits to run, test, and deploy workloads.

2. In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

   Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

   Go to project selector

3. Make sure that billing is enabled for your Google Cloud project.

4. In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

   Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

   Go to project selector

5. Make sure that billing is enabled for your Google Cloud project.

6. Enable the Cloud Run, Cloud Monitoring, Artifact Registry, and Cloud Build APIs.

   Enable the APIs

7. Installieren und initialisieren Sie die gcloud CLI.
8. Aktualisieren Sie die Google Cloud CLI: gcloud components update

Erforderliche Rollen

Bitten Sie Ihren Administrator, Ihnen die folgenden IAM-Rollen für Ihr Projekt zuzuweisen, um die Berechtigungen zu erhalten, die Sie zum Ausführen der Anleitung benötigen:

• Cloud Build-Bearbeiter (roles/cloudbuild.builds.editor)
• Cloud Run-Administrator (roles/run.admin)
• Create Service Accounts (roles/iam.serviceAccountCreator)
• Projekt-IAM-Administrator (roles/resourcemanager.projectIamAdmin)
• Monitoring-Messwert-Autor (roles/monitoring.metricWriter)
• Service Account User (roles/iam.serviceAccountUser)
• Service Usage Consumer (roles/serviceusage.serviceUsageConsumer)
• Storage-Administrator (roles/storage.admin)

Weitere Informationen zum Zuweisen von Rollen finden Sie unter Zugriff verwalten.

Sie können die erforderlichen Berechtigungen auch über benutzerdefinierte Rollen oder andere vordefinierte Rollen erhalten.

Hinweis: Einfache IAM-Rollen können auch Berechtigungen zum Ausführen der Anleitung enthalten. In einer Produktionsumgebung sollten Sie keine einfachen Rollen zuweisen, Sie können sie aber in einer Entwicklungs- oder Testumgebung gewähren.

Beachten Sie außerdem, dass das Cloud Run-Dienstkonto die Rolle Monitoring-Messwert-Autor (roles/monitoring.metricWriter) benötigt. Das Compute Engine-Standarddienstkonto hat diese Rolle standardmäßig. Sie müssen sie jedoch möglicherweise hinzufügen, wenn Sie ihre Berechtigungen geändert haben oder ein anderes Dienstkonto verwenden.

gcloud-Standardeinstellungen einrichten

So konfigurieren Sie gcloud mit Standardeinstellungen für den Cloud Run-Dienst:

1. Legen Sie ein Standardprojekt fest:

   gcloud config set project PROJECT_ID

   Ersetzen Sie PROJECT_ID durch den Namen des Projekts, das Sie für diese Anleitung erstellt haben.

2. Konfigurieren Sie gcloud für die von Ihnen ausgewählte Region:

   gcloud config set run/region REGION

   Ersetzen Sie REGION durch die unterstützte Cloud Run-Region Ihrer Wahl.

Cloud Run-Standorte

Cloud Run ist regional. Die Infrastruktur, in der die Cloud Run-Dienste ausgeführt werden, befindet sich demnach in einer bestimmten Region. Aufgrund der Verwaltung durch Google sind die Anwendungen in allen Zonen innerhalb dieser Region redundant verfügbar.

Bei der Auswahl der Region, in der Ihre Cloud Run-Dienste ausgeführt werden, ist vorrangig, dass die Anforderungen hinsichtlich Latenz, Verfügbarkeit oder Langlebigkeit erfüllt werden. Sie können im Allgemeinen die Region auswählen, die Ihren Nutzern am nächsten liegt, aber Sie sollten den Standort der anderen Google Cloud-Produkte berücksichtigen, die von Ihrem Cloud Run-Dienst verwendet werden. Die gemeinsame Nutzung von Google Cloud-Produkten an mehreren Standorten kann sich auf die Latenz und die Kosten des Dienstes auswirken.

Cloud Run ist in diesen Regionen verfügbar:

Unterliegt Preisstufe 1

• asia-east1 (Taiwan)
• asia-northeast1 (Tokio)
• asia-northeast2 (Osaka)
• europe-north1 (Finnland) Niedriger CO₂-Wert
• europe-southwest1 (Madrid)
• europe-west1 (Belgien) Niedriger CO₂-Ausstoß
• europe-west4 (Niederlande)
• europe-west8 (Mailand)
• europe-west9 (Paris) Niedriger CO₂-Ausstoß
• me-west1 (Tel Aviv)
• us-central1 (Iowa) Niedriger CO₂-Ausstoß
• us-east1 (South Carolina)
• us-east4 (Northern Virginia)
• us-east5 (Columbus)
• us-south1 (Dallas)
• us-west1 (Oregon) Niedriger CO₂-Ausstoß

Unterliegt Preisstufe 2

• africa-south1 (Johannesburg)
• asia-east2 (Hongkong)
• asia-northeast3 (Seoul, Südkorea)
• asia-southeast1 (Singapur)
• asia-southeast2 (Jakarta)
• asia-south1 (Mumbai, Indien)
• asia-south2 (Delhi, Indien)
• australia-southeast1 (Sydney)
• australia-southeast2 (Melbourne)
• europe-central2 (Warschau, Polen)
• europe-west10 (Berlin)
• europe-west12 (Turin)
• europe-west2 (London, Vereinigtes Königreich) Niedriger CO₂-Ausstoß
• europe-west3 (Frankfurt, Deutschland) Niedriger CO₂-Wert
• europe-west6 (Zürich, Schweiz) Niedriger CO₂-Ausstoß
• me-central1 (Doha)
• me-central2 (Dammam)
• northamerica-northeast1 (Montreal) Niedriger CO₂-Ausstoß
• northamerica-northeast2 (Toronto) Niedriger CO₂-Ausstoß
• southamerica-east1 (Sao Paulo, Brasilien) Niedriger CO₂-Ausstoß
• southamerica-west1 (Santiago, Chile) Niedriger CO₂-Ausstoß
• us-west2 (Los Angeles)
• us-west3 (Salt Lake City)
• us-west4 (Las Vegas)

Wenn Sie bereits einen Cloud Run-Dienst erstellt haben, können Sie dessen Region im Cloud Run-Dashboard der Google Cloud Console aufrufen.

OK

Artifact Registry-Image-Repository erstellen

Erstellen Sie ein Artifact Registry-Docker-Repository zum Hosten des Beispieldienst-Images:

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

Dabei gilt:

• PROJECT_ID: Der Name des Projekts, das Sie für diese Anleitung erstellt haben.
• REGION: Unterstützte Cloud Run-Region Ihrer Wahl.

Codebeispiel abrufen

So rufen Sie das gewünschte Codebeispiel ab:

1. Klonen Sie das Repository der Beispiel-App auf Ihren lokalen Computer:

   Go

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

   Sie können auch das Beispiel als ZIP-Datei herunterladen und extrahieren.

2. Wechseln Sie in das Verzeichnis, das den Cloud Run-Beispielcode enthält:

   Go

   cd golang-samples/run/custom-metrics/

Code prüfen

Der Code dieser Anleitung besteht aus folgenden Elementen:

• Ein Server, der eingehende Anfragen verarbeitet und einen Messwert mit dem Namen sidecar_sample_counter generiert.

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
}

• Einem Dockerfile, das die Betriebsumgebung für den Dienst definiert.

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"]

Das Beispiel enthält auch Dateien im Unterverzeichnis collector zum Erstellen eines benutzerdefinierten OpenTelemetry Collector:

• Eine Konfigurationsdatei für den OpenTelemetry Collector.

  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]

• Ein Dockerfile, das die bereitgestellte Konfiguration in einem vorgelagerten Collector-Image bündelt.

  FROM otel/opentelemetry-collector-contrib:0.101.0
  
  COPY collector-config.yaml /etc/otelcol-contrib/config.yaml

Code versenden

Das Versenden von Code erfolgt in drei Schritten: ein Container-Image mit Cloud Build erstellen, in Artifact Registry hochladen und in Cloud Run bereitstellen.

So versenden Sie den Code:

1. Erstellen Sie Ihren Beispieldienst-Container und veröffentlichen Sie ihn in Artifact Registry.

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

   Bei Erfolg sollte eine Bestätigungsmeldung mit der ID, der Erstellungszeit und dem Image-Namen angezeigt werden. Das Image wird in Container Registry gespeichert und kann bei Bedarf wiederverwendet werden.

2. Erstellen Sie einen Container und veröffentlichen Sie ihn in Artifact Registry.

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

   Bei Erfolg sollte eine Bestätigungsmeldung mit der ID, der Erstellungszeit und dem Image-Namen angezeigt werden. Das Image wird in Container Registry gespeichert und kann bei Bedarf wiederverwendet werden.

3. Stellen Sie Ihre Anwendung bereit:

   YAML

   1. Erstellen Sie eine neue Datei mit dem Namen service.yaml und folgendermaßen:

      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. Dabei gilt:
      • CONTAINER_PORT: Der Port des Ingress-Containers Ihres Dienstes. Der Standardwert ist 8080.
      • SERVICE-NAME: Ein beliebiger Name für den Dienst, z. B. custom-metrics-sample-service.

4. Erstellen Sie den Dienst mit dem folgenden Befehl:

   gcloud run services replace service.yaml

   Dieser Befehl gibt eine Dienst-URL zurück. Mit dieser URL können Sie die Beispielanwendung unter Testen ausprobieren.

Testen

Stellen Sie über die URL aus dem Befehl gcloud run unter Code senden eine Verbindung zum Dienst her, um Beispielmesswerte zu generieren. Sie können diesen Befehl mehrmals ausführen, um interessantere Daten zu generieren:

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

Ersetzen Sie SERVICE_URL durch die URL Ihres Dienstes.

Rufen Sie als Nächstes im Cloud Monitoring-Bereich der Google Cloud Console den Metrics Explorer auf und wählen Sie den Messwert sidecar_sample_counter aus.

Sie können die Messwerte auch mit PromQL abfragen. Die folgende Abfrage filtert beispielsweise Messwerte anhand der Cloud Run-Instanz-ID:

sidecar_sample_counter{instance="INSTANCE_ID"}

Ersetzen Sie INSTANCE_ID durch die ID einer beliebigen Instanz für Ihren Dienst (verfügbar in den Instanzlogs oder vom Metadatenserver).

Mit dieser Abfrage wird ein Diagramm wie das folgende erstellt:

Bereinigen

Wenn Sie ein neues Projekt für diese Anleitung erstellt haben, löschen Sie das Projekt. Wenn Sie ein vorhandenes Projekt verwendet haben und es beibehalten möchten, ohne die Änderungen in dieser Anleitung hinzuzufügen, löschen Sie die für die Anleitung erstellten Ressourcen.

Projekt löschen

Am einfachsten vermeiden Sie weitere Kosten, wenn Sie das zum Ausführen der Anleitung erstellte Projekt löschen.

So löschen Sie das Projekt:

Achtung: Das Löschen von Projekten hat folgende Auswirkungen:

• Alle Inhalte des Projekts werden gelöscht. Wenn Sie für die Aufgaben in diesem Dokument ein bereits bestehendes Projekt verwendet haben und dieses löschen, werden auch alle anderen im Rahmen des Projekts erstellten Daten gelöscht.
• Benutzerdefinierte Projekt-IDs gehen verloren. Beim Erstellen dieses Projekts haben Sie möglicherweise eine benutzerdefinierte Projekt-ID erstellt, die Sie weiterhin verwenden möchten. Damit die URLs, die die Projekt-ID nutzen, z. B. eine appspot.com-URL, erhalten bleiben, sollten Sie ausgewählte Ressourcen innerhalb des Projekts löschen, statt das gesamte Projekt.

Wenn Sie mehrere Architekturen, Anleitungen und Kurzanleitungen durcharbeiten möchten, können Sie die Überschreitung von Projektkontingenten verhindern, indem Sie Projekte wiederverwenden.

1. In the Google Cloud console, go to the Manage resources page.

   Go to Manage resources

2. In the project list, select the project that you want to delete, and then click Delete.
3. In the dialog, type the project ID, and then click Shut down to delete the project.

Anleitungsressourcen löschen

1. Löschen Sie den Cloud Run-Dienst, den Sie in dieser Anleitung bereitgestellt haben:

   gcloud run services delete SERVICE-NAME

   Dabei ist SERVICE-NAME der von Ihnen ausgewählte Dienstname.

   Sie können Cloud Run-Dienste auch über die Google Cloud Console löschen.

2. Entfernen Sie die Konfiguration der Standardregion gcloud, die Sie während der Einrichtung für die Anleitung hinzugefügt haben:

    gcloud config unset run/region
   

3. Entfernen Sie die Projektkonfiguration:

    gcloud config unset project
   

4. Löschen Sie sonstige Google Cloud-Ressourcen, die in dieser Anleitung erstellt wurden:

   • Artifact Registry-Docker-Repository löschen

Nächste Schritte

Weitere Beispiele, einschließlich Beispiele für Traces und Logs, sind auf GitHub verfügbar.