Scrivere metriche OTLP utilizzando un file collaterale OpenTelemetry

Questo tutorial mostra come scrivere, eseguire il deployment e chiamare un Cloud Run che genera report Metriche OTLP a Google Cloud Managed Service per Prometheus utilizzando il file collaterale OpenTelemetry.

Se hai un servizio Cloud Run che genera report Metriche di Prometheus, quindi utilizza il file collaterale di 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 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 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. 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.

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

    Go to project selector

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

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

    Go to project selector

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

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

    Abilita le API

  7. Installa e inizializza gcloud CLI.
  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 sul tuo progetto:

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

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

Tieni inoltre presente che l'identità del servizio Cloud Run richiede Ruolo Autore delle metriche Monitoring (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 proprie autorizzazioni o 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 il Cloud Run supportato regione di tua scelta.

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 nonché la latenza del tuo servizio.

Cloud Run è disponibile nelle regioni seguenti:

Soggetto ai prezzi di Livello 1

Soggetto ai prezzi di Livello 2

Se hai già creato un servizio Cloud Run, puoi visualizzare nella dashboard di Cloud Run all'interno Console Google Cloud.

Creazione di un repository di immagini Artifact Registry

Crea un repository Docker 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 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 l'esempio di Cloud Run codice:

    Vai 

    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 elemento 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 creare un'immagine personalizzata OpenTelemetry Collector:

  • 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 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 prevede tre passaggi: la creazione di un'immagine container con Cloud Build, caricando l'immagine container in Artifact Registry e il deployment dell'immagine container in Cloud Run.

Per spedire il codice:

  1. Crea il tuo container di 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 tuo container di raccolta 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 viene archiviata in Artifact Registry possono essere riutilizzati, se necessario.

  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:

  4. Crea il nuovo servizio con il comando seguente:

    gcloud run services replace service.yaml

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

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 Esplora metriche. nella sezione Cloud Monitoring della console Google Cloud e seleziona sidecar_sample_counter.

Metrica personalizzata mostrata nell'interfaccia utente di Esplora metriche

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

sidecar_sample_counter{instance="INSTANCE_ID"}

Sostituisci INSTANCE_ID con l'ID di qualsiasi istanza del tuo servizio (disponibile nei log dell'istanza o nel server dei metadati).

Questa query produce un grafico come quello seguente:

Metrica personalizzata richiesta 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 l'aggiunta delle modifiche In questo tutorial, elimina le risorse create per il tutorial.

Elimina il progetto

Il modo più semplice per eliminare la fatturazione creato per il tutorial.

Per eliminare il progetto:

  1. Nella console Google Cloud, vai alla pagina Gestisci risorse.

    Vai a Gestisci risorse

  2. Nell'elenco dei progetti, seleziona il progetto che vuoi eliminare, quindi fai clic su Elimina.
  3. Nella finestra di dialogo, digita l'ID del progetto e fai clic su Chiudi per eliminare il progetto.

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

    I servizi Cloud Run possono essere eliminati anche 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:

Passaggi successivi

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