Scrivere metriche OTLP utilizzando un file collaterale OpenTelemetry

---

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

Se hai un servizio Cloud Run che genera report sulle metriche Prometheus, utilizza invece il file collaterale Prometheus per Cloud Run.

Obiettivi

• Scrivi, crea ed esegui il deployment di un servizio su Cloud Run con il Sidecar di OpenTelemetry.
• Genera metriche personalizzate e registrale in Google Cloud Managed Service per Prometheus.

Costi

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

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

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.

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

Ruoli obbligatori

Per ottenere le autorizzazioni necessarie per completare il tutorial, chiedi all'amministratore di concederti i seguenti ruoli IAM nel progetto:

• Editor Cloud Build (roles/cloudbuild.builds.editor)
• Amministratore Cloud Run (roles/run.admin)
• Crea account di servizio (roles/iam.serviceAccountCreator)
• Amministratore IAM progetto (roles/resourcemanager.projectIamAdmin)
• Autore delle metriche di Monitoring (roles/monitoring.metricWriter)
• Utente account di servizio (roles/iam.serviceAccountUser)
• Consumatore di utilizzo del servizio (roles/serviceusage.serviceUsageConsumer)
• Amministratore archiviazione (roles/storage.admin)

Per saperne di più sulla concessione dei ruoli, consulta Gestire l'accesso a progetti, cartelle e organizzazioni.

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

Nota: IAM di base ruoli potrebbero anche contenere le autorizzazioni per completare il tutorial. Non devi concedere ruoli di base in una di produzione, ma puoi concederle in un ambiente di sviluppo o di test.

Tieni inoltre presente che l'identità del servizio Cloud Run deve disporre del ruolo Writer metriche di monitoraggio (roles/monitoring.metricWriter). La Account di servizio predefinito Compute Engine potrebbe avere questo ruolo per impostazione predefinita, ma potrebbe essere necessario aggiungerlo se hai modificato le relative autorizzazioni o che utilizzano un altro account di servizio.

Configurazione dei valori predefiniti di gcloud

Per configurare gcloud con i valori predefiniti 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 per cui hai creato questo tutorial.

2. Configura gcloud per la regione scelta:

   gcloud config set run/region REGION

   Sostituisci REGION con la regione di Cloud Run supportata che preferisci.

Località Cloud Run

Cloud Run è regionale, il che significa che l'infrastruttura dei tuoi servizi Cloud Run si trova in una regione specifica gestiti da Google affinché siano disponibili in modo ridondante tutte le zone all'interno di quella regione.

Soddisfare i requisiti di latenza, disponibilità o durabilità è fondamentale i fattori necessari per selezionare la regione in cui vengono eseguiti i servizi Cloud Run. Generalmente puoi selezionare la regione più vicina ai tuoi utenti, ma devi considerare la località dell'altro account Google Cloud prodotti utilizzati dal tuo 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 regioni seguenti:

Soggetto ai prezzi di Livello 1

• asia-east1 (Taiwan)
• asia-northeast1 (Tokyo)
• asia-northeast2 (Osaka)
• europe-north1 (Finlandia) Bassi livelli di CO₂
• europe-southwest1 (Madrid) Basso livello di CO₂
• europe-west1 (Belgio) A basse emissioni di CO₂
• europe-west4 (Paesi Bassi) Bassi livelli di CO₂
• europe-west8 (Milano)
• europe-west9 (Parigi) Bassi livelli di CO₂
• me-west1 (Tel Aviv)
• us-central1 (Iowa) A basse emissioni di CO₂
• us-east1 (Carolina del Sud)
• us-east4 (Virginia del Nord)
• us-east5 (Colombo)
• us-south1 (Dallas) Bassi livelli di CO₂
• us-west1 (Oregon) A basse emissioni di CO₂

Soggetto ai prezzi di Livello 2

• africa-south1 (Johannesburg)
• 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-west10 (Berlino) Bassi livelli di CO₂
• europe-west12 (Torino)
• europe-west2 (Londra, Regno Unito) Bassi livelli di CO₂
• europe-west3 (Francoforte, Germania) Bassi livelli di CO₂
• europe-west6 (Zurigo, Svizzera) A basse emissioni di CO₂
• me-central1 (Doha)
• me-central2 (Dammam)
• northamerica-northeast1 (Montreal) Bassi livelli di CO₂
• northamerica-northeast2 (Toronto) Bassi livelli di CO₂
• southamerica-east1 (San Paolo, Brasile) Bassi livelli di CO₂
• southamerica-west1 (Santiago, Cile) Bassi livelli di CO₂
• us-west2 (Los Angeles)
• us-west3 (Salt Lake City)
• 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.

Ok

Creazione di un repository di immagini Artifact Registry

Crea un repository Docker in 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 che preferisci.

Recupero dell'esempio di codice in corso

Per recuperare l'esempio di codice da utilizzare:

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

   Vai

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

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

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

   Vai

   cd golang-samples/run/custom-metrics/

Revisione del codice

Il codice di questo tutorial è costituito da quanto segue:

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

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'esempio include anche i file nella sottodirectory collector per la creazione di un raccoltore OpenTelemetry personalizzato:

• Un file di configurazione per 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]

• Un Dockerfile che raggruppa la configurazione fornita in un raccoglitore a monte dell'immagine.

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

Spedizione del codice

Il codice di spedizione è composto da tre passaggi: creazione di un'immagine container con Cloud Build, caricamento dell'immagine container in Artifact Registry ed esecuzione del deployment dell'immagine container in Cloud Run.

Per spedire il codice:

1. Crea il contenitore del servizio di esempio e pubblicalo su Artifact Registry:

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

   Se l'operazione riesce, dovresti visualizzare il messaggio SUCCESS contenente l'ID: data di creazione e nome immagine. L'immagine viene archiviata in Artifact Registry possono essere riutilizzati, se necessario.

2. Crea il contenitore del Collector e pubblicalo su Artifact Registry:

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

   Se l'operazione riesce, dovresti visualizzare il messaggio SUCCESS contenente l'ID: data di creazione e nome immagine. L'immagine è archiviata in Artifact Registry e, se lo desideri, può essere riutilizzata.

3. Esegui il deployment dell'applicazione:

   YAML

   1. Crea un nuovo file denominato service.yaml con quanto segue:

      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:
      • CONTAINER_PORT con la porta su cui il container di ingresso del servizio è in ascolto. Per impostazione predefinita, questo valore è 8080.
      • SERVICE-NAME con un nome qualsiasi per il servizio, ad esempio custom-metrics-sample-service.

4. Crea il nuovo servizio con il comando seguente:

   gcloud run services replace service.yaml

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

Prova

Utilizzando l'URL dal comando gcloud run in Spedizione del codice, connettersi al servizio per generare alcune metriche di esempio (puoi eseguire questo 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 servizio.

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

Puoi anche eseguire query sulle metriche con PromQL. Ad esempio, la query riportata di seguito 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 dell'istanza o dal server metadati).

Questa query genera un grafico come quello riportato di seguito:

Esegui la pulizia

Se hai creato un nuovo progetto per questo tutorial, eliminalo. Se hai utilizzato un progetto esistente e vuoi conservarlo 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:

Attenzione: l'eliminazione di un progetto ha i seguenti effetti:

• L'intero contenuto del progetto viene eliminato. Se hai utilizzato un progetto esistente per le attività descritte in questo documento, quando lo elimini elimini anche tutto il lavoro svolto nel progetto.
• Gli ID progetto personalizzati non sono più disponibili. Quando hai creato questo progetto, potresti aver creato un ID progetto personalizzato che vuoi utilizzare in futuro. Per conservare gli URL che utilizzano l'ID progetto, ad esempio un appspot.com URL, elimina le risorse selezionate all'interno del progetto anziché eliminare l'intero progetto.

Se intendi esplorare più architetture, tutorial o guide rapide, il riuso dei progetti può aiutarti a non superare i limiti di quota.

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 in corso...

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 scelto.

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

2. Rimuovi la configurazione predefinita della regione gcloud che hai aggiunto durante il tutorial configurazione:

    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:

   • Eliminare il repository Docker di Artifact Registry

Passaggi successivi

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