Questa pagina è stata tradotta dall'API Cloud Translation.

Scrivere metriche OTLP utilizzando un file collaterale OpenTelemetry

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

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

Obiettivi

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

Costi

In questo documento vengono utilizzati i seguenti componenti fatturabili di Google Cloud:

Per generare una stima dei costi in base all'utilizzo previsto, utilizza il Calcolatore prezzi. I nuovi utenti di Google Cloud possono essere idonei a una prova senza costi aggiuntivi.

Prima di iniziare

Accedi al tuo account Google Cloud. Se non conosci Google Cloud, crea un account per valutare le prestazioni dei nostri prodotti in scenari reali. I nuovi clienti ricevono anche 300 $di crediti gratuiti per l'esecuzione, il test e il deployment dei carichi di lavoro.

Nella pagina del selettore di progetti della console Google Cloud, seleziona o crea un progetto Google Cloud.

Vai al selettore progetti

Assicurati che la fatturazione sia attivata per il tuo progetto Google Cloud.

Nella pagina del selettore di progetti della console Google Cloud, seleziona o crea un progetto Google Cloud.

Vai al selettore progetti

Assicurati che la fatturazione sia attivata per il tuo progetto Google Cloud.

Abilita le API Cloud Run, Cloud Monitoring, Artifact Registry, and Cloud Build .
Abilita le API

Installa e inizializza gcloud CLI.
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 sul tuo 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)
Monitoring Metric Writer (roles/monitoring.metricWriter)
Utente account di servizio (roles/iam.serviceAccountUser)
Service Usage Consumer (roles/serviceusage.serviceUsageConsumer)
Amministratore Storage (roles/storage.admin)

Per saperne di più sulla concessione dei ruoli, consulta Gestire l'accesso.

Potresti anche essere in grado di ottenere le autorizzazioni richieste tramite i ruoli personalizzati o altri ruoli predefiniti.

Inoltre, tieni presente che l'account di servizio Cloud Run richiede il ruolo Writer metriche di Monitoring (roles/monitoring.metricWriter). L'account di servizio predefinito di Compute Engine ha questo ruolo per impostazione predefinita, ma potrebbe essere necessario aggiungerlo se hai modificato le sue autorizzazioni o utilizzi un account di servizio diverso.

Configurazione delle impostazioni predefinite di gcloud

Per configurare gcloud con i valori predefiniti per il tuo servizio Cloud Run:

Imposta il progetto predefinito:
```
gcloud config set project PROJECT_ID
```
Sostituisci PROJECT_ID con il nome del progetto che hai creato per questo tutorial.
Configura gcloud per la regione scelta:
```
gcloud config set run/region REGION
```
Sostituisci REGION con un'area geografica Cloud Run supportata a tua scelta.

Località di Cloud Run

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

Soddisfare i requisiti di latenza, disponibilità o durabilità sono fattori principali per selezionare la regione in cui vengono eseguiti i servizi Cloud Run. In genere, puoi selezionare la regione più vicina ai tuoi utenti, ma ti consigliamo di considerare la località degli altri prodotti Google Cloud utilizzati dal tuo servizio Cloud Run. L'utilizzo combinato di prodotti Google Cloud in più località può influire sulla latenza e sui costi del tuo 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) A basse emissioni di CO₂
europe-southwest1 (Madrid)
europe-west1 (Belgio) A basse emissioni di CO₂
europe-west4 (Paesi Bassi)
europe-west8 (Milano)
europe-west9 (Parigi) A basse emissioni 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)
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)
europe-west12 (Torino)
europe-west2 (Londra, Regno Unito) A basse emissioni di CO₂
europe-west3 (Francoforte, Germania) A basse emissioni di CO₂
europe-west6 (Zurigo, Svizzera) A basse emissioni di CO₂
me-central1 (Doha)
me-central2 (Dammam)
northamerica-northeast1 (Montreal) A basse emissioni di CO₂
northamerica-northeast2 (Toronto) A basse emissioni di CO₂
southamerica-east1 (San Paolo, Brasile) A basse emissioni di CO₂
southamerica-west1 (Santiago, Cile) A basse emissioni 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.

Creazione di un repository di immagini Artifact Registry

Crea un repository Docker di Artifact Registry per ospitare l'immagine del 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 a tua scelta.

Recupero dell'esempio di codice

Per recuperare l'esempio di codice da utilizzare:

Clona il repository dell'app di esempio sulla tua macchina locale:
Go
```
git clone https://github.com/GoogleCloudPlatform/golang-samples.git
```
In alternativa, puoi scaricare l'esempio come file ZIP ed estrarlo.
Passa alla directory che contiene il codice di esempio di Cloud Run:
Go
```
cd golang-samples/run/custom-metrics/
```

Revisione del codice

Il codice di questo tutorial è costituito dai seguenti elementi:

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 per il 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 OpenTelemetry Collector 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 elemento Dockerfile che raggruppa la configurazione fornita in un'immagine raccoglitore upstream.

FROM otel/opentelemetry-collector-contrib:0.75.0

COPY collector-config.yaml /etc/otelcol-contrib/config.yaml

Spedisci il codice

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

Per spedire il tuo codice:

Crea il tuo container di servizi 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 va a buon fine, dovresti visualizzare un messaggio SUCCESSIVO contenente l'ID, l'ora di creazione e il nome dell'immagine. L'immagine è archiviata in Artifact Registry e, se lo desideri, può essere riutilizzata.
Crea il tuo container raccoglitore e pubblicalo su Artifact Registry:
```
gcloud builds submit collector --tag REGION-docker.pkg.dev/PROJECT_ID/run-otel/otel-collector-metrics
```
Se l'operazione va a buon fine, dovresti visualizzare un messaggio SUCCESSIVO contenente l'ID, l'ora di creazione e il nome dell'immagine. L'immagine è archiviata in Artifact Registry e, se lo desideri, può essere riutilizzata.

Esegui il deployment dell'applicazione:

YAML

Crea un nuovo file denominato service.yaml con il seguente codice:

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

Sostituisci quanto segue:
- CONTAINER_PORT con la porta del container in entrata del servizio in ascolto. Per impostazione predefinita, è 8080.
- SERVICE-NAME con qualsiasi nome per il servizio, ad esempio custom-metrics-sample-service.

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.

Provalo

Utilizzando l'URL del comando gcloud run in Spedizione del codice, collegati 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 filtrerà le metriche in base all'ID istanza Cloud Run:

sidecar_sample_counter{instance="INSTANCE_ID"}

Sostituisci INSTANCE_ID con l'ID di un'istanza del tuo servizio (disponibile nei log delle istanze o nel server di metadati).

Questa query produce un grafico come il seguente:

Metrica personalizzata sottoposta a query 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 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à in questo documento, quando lo elimini elimini anche qualsiasi altro 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 URL appspot.com, elimina le risorse selezionate all'interno del progetto anziché eliminare l'intero progetto.

Se intendi esplorare più architetture, tutorial o guide rapide, puoi riutilizzare i progetti ed evitare così di superare i limiti di quota.

Nella console Google Cloud, vai alla pagina Gestisci risorse.
Vai a Gestisci risorse
Nell'elenco dei progetti, seleziona il progetto che vuoi eliminare, quindi fai clic su Elimina.
Nella finestra di dialogo, digita l'ID del progetto e fai clic su Chiudi per eliminare il progetto.

Eliminazione delle risorse del tutorial

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.
Rimuovi la configurazione della regione predefinita di gcloud aggiunta durante la configurazione del tutorial:
```
 gcloud config unset run/region
```
Rimuovi la configurazione del progetto:
```
 gcloud config unset project
```
Elimina le altre risorse Google Cloud create in questo tutorial:
- Elimina il repository Docker di Artifact Registry

Passaggi successivi

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