Benutzerdefinierte Messwerte mit einem Sidecar-Agent schreiben

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

Lernziele

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:

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.

Hinweis

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.

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

Go to project selector

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

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

Go to project selector

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

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

Installieren und initialisieren Sie die gcloud CLI.
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.

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:

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.
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) Niedriger CO₂-Ausstoß
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

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-west12 (Turin)
europe-west2 (London, Vereinigtes Königreich)
europe-west3 (Frankfurt, Deutschland)
europe-west6 (Zürich, Schweiz) Niedriger CO₂-Ausstoß
me-central1 (Doha)
northamerica-northeast1 (Montreal) Niedriger CO₂-Ausstoß
northamerica-northeast2 (Toronto) Niedriger CO₂-Ausstoß
southamerica-east1 (Sao Paulo, Brasilien) Niedriger CO₂-Ausstoß
southamerica-west1 (Santiago, Chile)
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.

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:

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.
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 sample_sidecar_counter generiert.

run/custom-metrics/main.go

Auf GitHub ansehen Feedback

package main

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

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

var counter instrument.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: %s", err)
	}

	exporter, err := otlpmetricgrpc.New(ctx,
		otlpmetricgrpc.WithInsecure(),
	)
	if err != nil {
		log.Fatalf("Error creating exporter: %s", err)
	}
	provider := metric.NewMeterProvider(
		metric.WithReader(metric.NewPeriodicReader(exporter)),
		metric.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.

run/custom-metrics/Dockerfile

Auf GitHub ansehen Feedback

FROM golang:1.20 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.

run/custom-metrics/collector/collector-config.yaml

Auf GitHub ansehen Feedback

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.

run/custom-metrics/collector/Dockerfile

Auf GitHub ansehen Feedback
```
FROM otel/opentelemetry-collector-contrib:0.75.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 die Container Registry hochladen und in Cloud Run bereitstellen.

So versenden Sie den Code:

Erstellen Sie Ihren Beispieldienst-Container und veröffentlichen Sie ihn in Container 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.
Erstellen Sie einen Container und veröffentlichen Sie ihn in Container 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.

Stellen Sie Ihre Anwendung bereit:

YAML

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

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.

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.

Benutzerdefinierter Messwert, der in der Metrics Explorer-UI angezeigt wird

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:

Von PromQL abgefragter benutzerdefinierter Messwert

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.

In the Google Cloud console, go to the Manage resources page.
Go to Manage resources
In the project list, select the project that you want to delete, and then click Delete.
In the dialog, type the project ID, and then click Shut down to delete the project.

Anleitungsressourcen löschen

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.
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
```
Entfernen Sie die Projektkonfiguration:
```
 gcloud config unset project
```
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.