Scrivi metriche personalizzate mediante un agente collaterale


Questo tutorial mostra come scrivere, eseguire il deployment e chiamare un servizio Cloud Run che segnala metriche personalizzate a Google Cloud Managed Service per Prometheus utilizzando il sidecar OpenTelemetry.

Obiettivi

  • Scrivi, crea ed esegui il deployment di un servizio su Cloud Run con la sidecar OpenTelemetry.
  • Genera metriche personalizzate e segnalale a Google Cloud Managed Service per Prometheus.

Costi

In questo documento utilizzi i seguenti componenti fatturabili di Google Cloud:

Per generare una stima dei costi basata sull'utilizzo previsto, utilizza il Calcolatore prezzi. I nuovi utenti di Google Cloud potrebbero essere idonei per una prova gratuita.

Prima di iniziare

  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.

    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.

    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. Installa e inizializza l'interfaccia a riga di comando gcloud.
  8. Aggiornamento di Google Cloud CLI: gcloud components update

Ruoli obbligatori

Per ottenere le autorizzazioni necessarie per completare il tutorial, chiedi al tuo amministratore di concederti i seguenti ruoli IAM sul tuo progetto:

Per maggiori informazioni sulla concessione dei ruoli, vedi Gestire l'accesso.

Potresti anche ottenere le autorizzazioni richieste tramite ruoli personalizzati o altri ruoli predefiniti.

Inoltre, tieni presente che l'account di servizio di Cloud Run necessita del ruolo Writer metriche Monitoring (roles/monitoring.metricWriter). L'account di servizio predefinito di Compute Engine ha questo ruolo per impostazione predefinita, ma potresti doverlo aggiungere se hai modificato le sue autorizzazioni o se utilizzi un account di servizio diverso.

Configurazione dei valori predefiniti gcloud

Per configurare gcloud con le impostazioni predefinite per il tuo servizio Cloud Run:

  1. Imposta il progetto predefinito:

    gcloud config set project PROJECT_ID

    Sostituisci PROJECT_ID con il nome del progetto che hai creato per questo tutorial.

  2. Configura gcloud per la regione scelta:

    gcloud config set run/region REGION

    Sostituisci REGION con l'area geografica supportata di Cloud Run.

Località di Cloud Run

Cloud Run è a livello di regione, il che significa che l'infrastruttura che esegue i tuoi servizi Cloud Run si trova in una regione specifica ed è gestita da Google in modo che sia disponibile in modo ridondante in tutte le zone all'interno di quella regione.

Soddisfare i requisiti di latenza, disponibilità o durabilità sono i fattori principali per selezionare la regione in cui vengono eseguiti i servizi Cloud Run. In genere, puoi selezionare l'area geografica più vicina ai tuoi utenti, ma dovresti prendere in considerazione la località degli altri prodotti Google Cloud utilizzati dal servizio Cloud Run. L'utilizzo combinato dei prodotti Google Cloud in più località può influire sulla latenza e sul costo del servizio.

Cloud Run è disponibile nelle seguenti regioni:

Soggetto ai prezzi di Livello 1

  • asia-east1 (Taiwan)
  • asia-northeast1 (Tokyo)
  • asia-northeast2 (Osaka)
  • europe-north1 (Finlandia) icona Fogliolina Bassi livelli di CO2
  • europe-southwest1 (Madrid) icona foglia CO basso2
  • europe-west1 (Belgio) icona foglia CO basso2
  • europe-west4 (Paesi Bassi)
  • europe-west8 (Milano)
  • europe-west9 (Parigi) icona foglia CO basso2
  • me-west1 (Tel Aviv)
  • us-central1 (Iowa) icona foglia CO basso2
  • us-east1 (Carolina del Sud)
  • us-east4 (Virginia del Nord)
  • us-east5 (Columbus)
  • us-south1 (Dallas)
  • us-west1 (Oregon) icona foglia Bassi livelli di CO2

Soggetto ai prezzi di Livello 2

  • asia-east2 (Hong Kong)
  • asia-northeast3 (Seul, Corea del Sud)
  • asia-southeast1 (Singapore)
  • asia-southeast2 (Giacarta)
  • asia-south1 (Mumbai, India)
  • asia-south2 (Delhi, India)
  • australia-southeast1 (Sydney)
  • australia-southeast2 (Melbourne)
  • europe-central2 (Varsavia, Polonia)
  • europe-west12 (Torino)
  • europe-west2 (Londra, Regno Unito)
  • europe-west3 (Francoforte, Germania)
  • europe-west6 (Zurigo, Svizzera) icona foglia CO basso2
  • me-central1 (Doha)
  • northamerica-northeast1 (Montreal) icona foglia CO basso2
  • northamerica-northeast2 (Toronto) icona foglia CO basso2
  • southamerica-east1 (San Paolo, Brasile) icona foglia CO bassa2
  • southamerica-west1 (Santiago, Cile)
  • us-west2 (Los Angeles)
  • us-west3 (Salina, città del lago)
  • us-west4 (Las Vegas)

Se hai già creato un servizio Cloud Run, puoi visualizzare la regione nella dashboard di Cloud Run nella console Google Cloud.

Creazione di un repository di immagini Artifact Registry

Crea un repository Docker di Artifact Registry per ospitare l'immagine di servizio di esempio:

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

Sostituisci quanto segue:

  • PROJECT_ID con il nome del progetto che hai creato per questo tutorial.
  • REGION REGIONE con la regione Cloud Run supportata di tua scelta.

Recupero dell'esempio di codice

Per recuperare l'esempio di codice da utilizzare:

  1. Clona il repository dell'app di esempio nella macchina locale:

    Go

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

    In alternativa, puoi scaricare l'esempio come file ZIP ed estrarlo.

  2. Passa alla directory che contiene il codice campione di Cloud Run:

    Go

    cd golang-samples/run/custom-metrics/

Esaminare il codice

Il codice di questo tutorial è costituito dai seguenti elementi:

  • Un server che gestisce le richieste in entrata e genera una metrica denominata sample_sidecar_counter.
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
}
  • Un Dockerfile che definisce l'ambiente operativo per il servizio.
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"]

L'esempio include anche i file nella sottodirectory collector per la creazione di un raccoglitore OpenTelemetry personalizzato:

  • Un file di configurazione per il raccoglitore 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 oggetto Dockerfile che raggruppa la configurazione fornita in un'immagine raccoglitore a monte.

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

Spedizione del codice

Il codice di spedizione prevede tre passaggi: creazione di un'immagine container con Cloud Build, caricamento dell'immagine container in Container Registry e deployment di Cloud Run in Cloud Run.

Per spedire il codice:

  1. Crea il tuo container di servizio di esempio e pubblicalo su Container Registry.

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

    In caso di esito positivo, dovresti vedere un messaggio di operazione riuscita contenente l'ID, l'ora di creazione e il nome dell'immagine. L'immagine è archiviata in Artifact Registry e, se vuoi, può essere riutilizzata.

  2. Crea il tuo container Collector e pubblicalo su Container Registry:

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

    In caso di esito positivo, dovresti vedere un messaggio di operazione riuscita contenente l'ID, l'ora di creazione e il nome dell'immagine. L'immagine è archiviata in Artifact Registry e, se vuoi, può essere riutilizzata.

  3. Esegui il deployment dell'applicazione:

    YAML

    1. Crea un nuovo file denominato service.yaml con i seguenti elementi:

      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. Sostituisci quanto segue:
  4. Crea il nuovo servizio con il comando seguente:

    gcloud run services replace service.yaml

    Questo comando restituisce un URL di servizio. Utilizza questo URL per provare l'applicazione di esempio in Prova.

Prova in corso

Utilizzando l'URL del comando gcloud run in Spedizione del codice, connettiti al servizio per generare alcune metriche di esempio (puoi eseguire questo comando più volte per generare dati più interessanti):

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

Sostituisci SERVICE_URL con l'URL del tuo servizio.

Quindi, vai a Metrics Explorer nella sezione Cloud Monitoring della console Google Cloud e seleziona la metrica sidecar_sample_counter.

Metrica personalizzata mostrata nell'interfaccia utente di Metrics Explorer

Puoi anche eseguire query sulle metriche con PromQL. Ad esempio, la query seguente filtra le metriche in base all'ID istanza Cloud Run:

sidecar_sample_counter{instance="INSTANCE_ID"}

Sostituisci INSTANCE_ID con l'ID di qualsiasi istanza per il tuo servizio (disponibile nei log delle istanze o dal server di metadati).

Questa query produce un grafico simile a quello mostrato di seguito:

Metrica personalizzata interrogata da PromQL

Esegui la pulizia

Se hai creato un nuovo progetto per questo tutorial, elimina il progetto. Se hai utilizzato un progetto esistente e vuoi mantenerlo senza le modifiche aggiunte in questo tutorial, elimina le risorse create per il tutorial.

Elimina il progetto

Il modo più semplice per eliminare la fatturazione è eliminare il progetto che hai creato per il tutorial.

Per eliminare il progetto:

  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.

Eliminazione delle risorse del tutorial

  1. Elimina il servizio Cloud Run di cui hai eseguito il deployment in questo tutorial:

    gcloud run services delete SERVICE-NAME

    Dove SERVICE-NAME è il nome del servizio che hai scelto.

    Puoi anche eliminare i servizi Cloud Run dalla console Google Cloud.

  2. Rimuovi la configurazione della regione predefinita di gcloud aggiunta durante la configurazione del tutorial:

     gcloud config unset run/region
    
  3. Rimuovi la configurazione del progetto:

     gcloud config unset project
    
  4. Elimina altre risorse Google Cloud create in questo tutorial:

Passaggi successivi

Altri esempi, inclusi esempi di tracce e log, sono disponibili su GitHub.