Tutorial: eseguire il debug del routing degli eventi in Cloud Run

Crea un repository standard Artifact Registry

Crea un repository standard di Artifact Registry per archiviare l'immagine container:

gcloud artifacts repositories create REPOSITORY \
    --repository-format=docker \
    --location=$REGION

Sostituisci REPOSITORY con un nome univoco per il repository.

Crea un bucket Cloud Storage

Crea un bucket Cloud Storage in ciascuna delle due regioni come origine evento per il servizio Cloud Run:

1. Crea un bucket in us-east1:

   export BUCKET1="troubleshoot-bucket1-PROJECT_ID"
   gcloud storage buckets create gs://${BUCKET1} --location=us-east1

2. Crea un bucket in us-west1:

   export BUCKET2="troubleshoot-bucket2-PROJECT_ID"
   gcloud storage buckets create gs://${BUCKET2} --location=us-west1

Dopo aver creato l'origine evento, esegui il deployment del servizio di ricezione di eventi su Cloud Run.

Esegui il deployment del ricevitore di eventi

Esegui il deployment di un servizio Cloud Run che riceve e registra gli eventi.

1. Recupera il esempio di codice clonando il repository GitHub:

   Vai

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

   Java

   git clone https://github.com/GoogleCloudPlatform/java-docs-samples.git
   cd java-docs-samples/eventarc/audit-storage
   

   .NET

   git clone https://github.com/GoogleCloudPlatform/dotnet-docs-samples.git
   cd dotnet-docs-samples/eventarc/audit-storage
   

   Node.js

   git clone https://github.com/GoogleCloudPlatform/nodejs-docs-samples.git
   cd nodejs-docs-samples/eventarc/audit-storage
   

   Python

   git clone https://github.com/GoogleCloudPlatform/python-docs-samples.git
   cd python-docs-samples/eventarc/audit-storage
   

2. Esamina il codice di questo tutorial, che consiste in quanto segue:

   • Un gestore di eventi che riceve l'evento in entrata come CloudEvent all'interno della richiesta HTTP POST:

     Vai

     
     // Processes CloudEvents containing Cloud Audit Logs for Cloud Storage
     package main
     
     import (
     	"fmt"
     	"log"
     	"net/http"
     	"os"
     
     	cloudevent "github.com/cloudevents/sdk-go/v2"
     )
     
     // HelloEventsStorage receives and processes a Cloud Audit Log event with Cloud Storage data.
     func HelloEventsStorage(w http.ResponseWriter, r *http.Request) {
     	if r.Method != http.MethodPost {
     		http.Error(w, "Expected HTTP POST request with CloudEvent payload", http.StatusMethodNotAllowed)
     		return
     	}
     
     	event, err := cloudevent.NewEventFromHTTPRequest(r)
     	if err != nil {
     		log.Printf("cloudevent.NewEventFromHTTPRequest: %v", err)
     		http.Error(w, "Failed to create CloudEvent from request.", http.StatusBadRequest)
     		return
     	}
     	s := fmt.Sprintf("Detected change in Cloud Storage bucket: %s", event.Subject())
     	fmt.Fprintln(w, s)
     }
     

     Java

     import io.cloudevents.CloudEvent;
     import io.cloudevents.rw.CloudEventRWException;
     import io.cloudevents.spring.http.CloudEventHttpUtils;
     import org.springframework.http.HttpHeaders;
     import org.springframework.http.HttpStatus;
     import org.springframework.http.ResponseEntity;
     import org.springframework.web.bind.annotation.RequestBody;
     import org.springframework.web.bind.annotation.RequestHeader;
     import org.springframework.web.bind.annotation.RequestMapping;
     import org.springframework.web.bind.annotation.RequestMethod;
     import org.springframework.web.bind.annotation.RestController;
     
     @RestController
     public class EventController {
     
       @RequestMapping(value = "/", method = RequestMethod.POST, consumes = "application/json")
       public ResponseEntity<String> receiveMessage(
           @RequestBody String body, @RequestHeader HttpHeaders headers) {
         CloudEvent event;
         try {
           event =
               CloudEventHttpUtils.fromHttp(headers)
                   .withData(headers.getContentType().toString(), body.getBytes())
                   .build();
         } catch (CloudEventRWException e) {
           return new ResponseEntity<>(e.getMessage(), HttpStatus.BAD_REQUEST);
         }
     
         String ceSubject = event.getSubject();
         String msg = "Detected change in Cloud Storage bucket: " + ceSubject;
         System.out.println(msg);
         return new ResponseEntity<>(msg, HttpStatus.OK);
       }
     }

     .NET

     
     using Microsoft.AspNetCore.Builder;
     using Microsoft.AspNetCore.Hosting;
     using Microsoft.AspNetCore.Http;
     using Microsoft.Extensions.DependencyInjection;
     using Microsoft.Extensions.Hosting;
     using Microsoft.Extensions.Logging;
     
     public class Startup
     {
         public void ConfigureServices(IServiceCollection services)
         {
         }
     
         public void Configure(IApplicationBuilder app, IWebHostEnvironment env, ILogger<Startup> logger)
         {
             if (env.IsDevelopment())
             {
                 app.UseDeveloperExceptionPage();
             }
     
             logger.LogInformation("Service is starting...");
     
             app.UseRouting();
     
             app.UseEndpoints(endpoints =>
             {
                 endpoints.MapPost("/", async context =>
                 {
                     logger.LogInformation("Handling HTTP POST");
     
                     var ceSubject = context.Request.Headers["ce-subject"];
                     logger.LogInformation($"ce-subject: {ceSubject}");
     
                     if (string.IsNullOrEmpty(ceSubject))
                     {
                         context.Response.StatusCode = 400;
                         await context.Response.WriteAsync("Bad Request: expected header Ce-Subject");
                         return;
                     }
     
                     await context.Response.WriteAsync($"GCS CloudEvent type: {ceSubject}");
                 });
             });
         }
     }
     

     Node.js

     const express = require('express');
     const app = express();
     
     app.use(express.json());
     app.post('/', (req, res) => {
       if (!req.header('ce-subject')) {
         return res
           .status(400)
           .send('Bad Request: missing required header: ce-subject');
       }
     
       console.log(
         `Detected change in Cloud Storage bucket: ${req.header('ce-subject')}`
       );
       return res
         .status(200)
         .send(
           `Detected change in Cloud Storage bucket: ${req.header('ce-subject')}`
         );
     });
     
     module.exports = app;

     Python

     @app.route("/", methods=["POST"])
     def index():
         # Create a CloudEvent object from the incoming request
         event = from_http(request.headers, request.data)
         # Gets the GCS bucket name from the CloudEvent
         # Example: "storage.googleapis.com/projects/_/buckets/my-bucket"
         bucket = event.get("subject")
     
         print(f"Detected change in Cloud Storage bucket: {bucket}")
         return (f"Detected change in Cloud Storage bucket: {bucket}", 200)
     
     

   • Un server che utilizza il gestore di eventi:

     Vai

     
     func main() {
     	http.HandleFunc("/", HelloEventsStorage)
     	// Determine port for HTTP service.
     	port := os.Getenv("PORT")
     	if port == "" {
     		port = "8080"
     	}
     	// Start HTTP server.
     	log.Printf("Listening on port %s", port)
     	if err := http.ListenAndServe(":"+port, nil); err != nil {
     		log.Fatal(err)
     	}
     }
     

     Java

     
     import org.springframework.boot.SpringApplication;
     import org.springframework.boot.autoconfigure.SpringBootApplication;
     
     @SpringBootApplication
     public class Application {
       public static void main(String[] args) {
         SpringApplication.run(Application.class, args);
       }
     }

     .NET

         public static void Main(string[] args)
         {
             CreateHostBuilder(args).Build().Run();
         }
         public static IHostBuilder CreateHostBuilder(string[] args)
         {
             var port = Environment.GetEnvironmentVariable("PORT") ?? "8080";
             var url = $"http://0.0.0.0:{port}";
     
             return Host.CreateDefaultBuilder(args)
                 .ConfigureWebHostDefaults(webBuilder =>
                 {
                     webBuilder.UseStartup<Startup>().UseUrls(url);
                 });
         }
     

     Node.js

     const app = require('./app.js');
     const PORT = parseInt(process.env.PORT) || 8080;
     
     app.listen(PORT, () =>
       console.log(`nodejs-events-storage listening on port ${PORT}`)
     );

     Python

     import os
     
     from cloudevents.http import from_http
     
     from flask import Flask, request
     
     app = Flask(__name__)
     if __name__ == "__main__":
         app.run(debug=True, host="0.0.0.0", port=int(os.environ.get("PORT", 8080)))

   • Un Dockerfile che definisce l'ambiente operativo per il servizio. I contenuti del Dockerfile variano in base alla lingua:

     Vai

     
     # Use the official Go image to create a binary.
     # This is based on Debian and sets the GOPATH to /go.
     # https://hub.docker.com/_/golang
     FROM golang:1.23-bookworm as builder
     
     # Create and change to the app directory.
     WORKDIR /app
     
     # Retrieve application dependencies.
     # This allows the container build to reuse cached dependencies.
     # Expecting to copy go.mod and if present go.sum.
     COPY go.* ./
     RUN go mod download
     
     # Copy local code to the container image.
     COPY . ./
     
     # Build the binary.
     RUN go build -v -o server
     
     # Use the official Debian slim image for a lean production container.
     # https://hub.docker.com/_/debian
     # https://docs.docker.com/develop/develop-images/multistage-build/#use-multi-stage-builds
     FROM debian:bookworm-slim
     RUN set -x && apt-get update && DEBIAN_FRONTEND=noninteractive apt-get install -y \
         ca-certificates && \
         rm -rf /var/lib/apt/lists/*
     
     # Copy the binary to the production image from the builder stage.
     COPY --from=builder /app/server /server
     
     # Run the web service on container startup.
     CMD ["/server"]
     

     Java

     
     # Use the official maven image to create a build artifact.
     # https://hub.docker.com/_/maven
     FROM maven:3-eclipse-temurin-17-alpine as builder
     
     # Copy local code to the container image.
     WORKDIR /app
     COPY pom.xml .
     COPY src ./src
     
     # Build a release artifact.
     RUN mvn package -DskipTests
     
     # Use Eclipse Temurin for base image.
     # https://docs.docker.com/develop/develop-images/multistage-build/#use-multi-stage-builds
     FROM eclipse-temurin:17.0.15_6-jre-alpine
     
     # Copy the jar to the production image from the builder stage.
     COPY --from=builder /app/target/audit-storage-*.jar /audit-storage.jar
     
     # Run the web service on container startup.
     CMD ["java", "-Djava.security.egd=file:/dev/./urandom", "-jar", "/audit-storage.jar"]
     

     .NET

     
     # Use Microsoft's official build .NET image.
     # https://hub.docker.com/_/microsoft-dotnet-core-sdk/
     FROM mcr.microsoft.com/dotnet/sdk:8.0-alpine AS build
     WORKDIR /app
     
     # Install production dependencies.
     # Copy csproj and restore as distinct layers.
     COPY *.csproj ./
     RUN dotnet restore
     
     # Copy local code to the container image.
     COPY . ./
     WORKDIR /app
     
     # Build a release artifact.
     RUN dotnet publish -c Release -o out
     
     
     # Use Microsoft's official runtime .NET image.
     # https://hub.docker.com/_/microsoft-dotnet-core-aspnet/
     FROM mcr.microsoft.com/dotnet/aspnet:8.0-alpine AS runtime
     WORKDIR /app
     COPY --from=build /app/out ./
     
     # Run the web service on container startup.
     ENTRYPOINT ["dotnet", "AuditStorage.dll"]

     Node.js

     
     # Use the official lightweight Node.js image.
     # https://hub.docker.com/_/node
     FROM node:20-slim
     # Create and change to the app directory.
     WORKDIR /usr/src/app
     
     # Copy application dependency manifests to the container image.
     # A wildcard is used to ensure both package.json AND package-lock.json are copied.
     # Copying this separately prevents re-running npm install on every code change.
     COPY package*.json ./
     
     # Install dependencies.
     # if you need a deterministic and repeatable build create a 
     # package-lock.json file and use npm ci:
     # RUN npm ci --omit=dev
     # if you need to include development dependencies during development
     # of your application, use:
     # RUN npm install --dev
     
     RUN npm install --omit=dev
     
     # Copy local code to the container image.
     COPY . .
     
     # Run the web service on container startup.
     CMD [ "npm", "start" ]
     

     Python

     
     # Use the official Python image.
     # https://hub.docker.com/_/python
     FROM python:3.11-slim
     
     # Allow statements and log messages to immediately appear in the Cloud Run logs
     ENV PYTHONUNBUFFERED True
     
     # Copy application dependency manifests to the container image.
     # Copying this separately prevents re-running pip install on every code change.
     COPY requirements.txt ./
     
     # Install production dependencies.
     RUN pip install -r requirements.txt
     
     # Copy local code to the container image.
     ENV APP_HOME /app
     WORKDIR $APP_HOME
     COPY . ./
     
     # Run the web service on container startup. 
     # Use gunicorn webserver with one worker process and 8 threads.
     # For environments with multiple CPU cores, increase the number of workers
     # to be equal to the cores available.
     CMD exec gunicorn --bind :$PORT --workers 1 --threads 8 --timeout 0 main:app

3. Crea l'immagine container con Cloud Build e caricala in Artifact Registry:

   export PROJECT_ID=$(gcloud config get-value project)
   export SERVICE_NAME=troubleshoot-service
   gcloud builds submit --tag $REGION-docker.pkg.dev/${PROJECT_ID}/REPOSITORY/${SERVICE_NAME}:v1

4. Esegui il deployment dell'immagine container su Cloud Run:

   gcloud run deploy ${SERVICE_NAME} \
       --image $REGION-docker.pkg.dev/${PROJECT_ID}/REPOSITORY/${SERVICE_NAME}:v1 \
       --allow-unauthenticated

   Se il deployment ha esito positivo, la riga di comando visualizza l'URL del servizio.

Crea un trigger

Dopo aver eseguito il deployment di un servizio Cloud Run, configura un trigger per rilevare gli eventi di Cloud Storage tramite i log di controllo.

1. Crea un trigger Eventarc per rimanere in ascolto degli eventi di Cloud Storage instradati utilizzando Cloud Audit Logs:

   gcloud eventarc triggers create troubleshoot-trigger \
       --destination-run-service=troubleshoot-service \
       --event-filters="type=google.cloud.audit.log.v1.written" \
       --event-filters="serviceName=storage.googleapis.com" \
       --event-filters="methodName=storage.objects.create" \
       --service-account=${PROJECT_NUMBER}-compute@developer.gserviceaccount.com
   

   Viene creato un trigger denominato troubleshoot-trigger.

2. Per confermare la creazione di troubleshoot-trigger, esegui:

   gcloud eventarc triggers list
   

   L'output dovrebbe essere simile al seguente:

   NAME: troubleshoot-trigger
   TYPE: google.cloud.audit.log.v1.written
   DESTINATION: Cloud Run service: troubleshoot-service
   ACTIVE: By 20:03:37
   LOCATION: us-central1
   

Generare e visualizzare un evento

Verifica di aver eseguito correttamente il deployment del servizio e di poter ricevere eventi da Cloud Storage.

1. Crea e carica un file nel bucket di archiviazione BUCKET1:

    echo "Hello World" > random.txt
    gcloud storage cp random.txt gs://${BUCKET1}/random.txt
   

2. Monitora i log per verificare se il servizio ha ricevuto un evento. Per visualizzare la voce di log:

   1. Filtra le voci di log e restituisci l'output in formato JSON:

      gcloud logging read "resource.labels.service_name=troubleshoot-service \
          AND textPayload:random.txt" \
          --format=json

   2. Cerca una voce di log simile a:

      "textPayload": "Detected change in Cloud Storage bucket: ..."
      

Tieni presente che inizialmente non viene restituita alcuna voce di log. Ciò indica che si è verificato un problema nella configurazione che devi esaminare.

Esaminare il problema

Segui la procedura per capire perché il servizio non riceve eventi.

Tempo di inizializzazione

Sebbene l'attivatore venga creato immediatamente, la propagazione e il filtraggio degli eventi possono richiedere fino a due minuti. Esegui questo comando per verificare che un trigger sia attivo:

gcloud eventarc triggers list

L'output indica lo stato del trigger. Nel seguente esempio, troubleshoot-trigger sarà attivo entro le ore 14:16:56:

NAME                  TYPE                               DESTINATION_RUN_SERVICE  ACTIVE
troubleshoot-trigger  google.cloud.audit.log.v1.written  troubleshoot-service     By 14:16:56

Una volta attivato il trigger, carica di nuovo un file nel bucket di archiviazione. Gli eventi vengono scritti nei log del servizio Cloud Run. Se il servizio non riceve eventi, il problema potrebbe essere correlato alle dimensioni degli eventi.

Audit log

In questo tutorial, gli eventi Cloud Storage vengono instradati utilizzando Cloud Audit Logs e inviati a Cloud Run. Verifica che gli audit log siano abilitati per Cloud Storage.

1. Nella console Google Cloud , vai alla pagina Audit log.

   Vai agli audit log

2. Seleziona la casella di controllo Google Cloud Storage.
3. Assicurati che siano selezionati i tipi di log Lettura amministratore, Lettura dati e Scrittura dati.

Dopo aver abilitato Cloud Audit Logs, carica di nuovo il file nel bucket di archiviazione e controlla i log. Se il servizio continua a non ricevere eventi, il problema potrebbe essere correlato alla località del trigger.

Posizione del trigger

Potrebbero esserci più risorse in località diverse e devi filtrare gli eventi provenienti da origini che si trovano nella stessa regione della destinazione Cloud Run. Per ulteriori informazioni, consulta le località supportate da Eventarc e Informazioni sulle località Eventarc.

In questo tutorial hai eseguito il deployment del servizio Cloud Run su us-central1. Poiché hai impostato eventarc/location su us-central1, hai anche creato un trigger nella stessa posizione.

Tuttavia, hai creato due bucket Cloud Storage nelle località us-east1 e us-west1. Per ricevere eventi da queste località, devi creare trigger Eventarc in queste località.

Crea un trigger Eventarc che si trova in us-east1:

1. Conferma la posizione del trigger esistente:

   gcloud eventarc triggers describe troubleshoot-trigger
   

2. Imposta la località e la regione su us-east1:

   gcloud config set eventarc/location us-east1
   gcloud config set run/region us-east1
   

3. Esegui nuovamente il deployment del ricevitore di eventi creando ed eseguendo il deployment dell'immagine container in Cloud Run.

4. Crea un nuovo trigger che si trova in us-east1:

   gcloud eventarc triggers create troubleshoot-trigger-new \
     --destination-run-service=troubleshoot-service \
     --event-filters="type=google.cloud.audit.log.v1.written" \
     --event-filters="serviceName=storage.googleapis.com" \
     --event-filters="methodName=storage.objects.create" \
     --service-account=${PROJECT_NUMBER}-compute@developer.gserviceaccount.com
   

5. Verifica che il trigger sia stato creato:

   gcloud eventarc triggers list
   

   L'inizializzazione di un trigger può richiedere fino a due minuti prima che inizi a instradare gli eventi.

6. Per verificare che il trigger sia ora implementato correttamente, genera e visualizza un evento.

Altri problemi che potresti riscontrare

Potresti riscontrare altri problemi durante l'utilizzo di Eventarc.

Dimensione dell'evento

Gli eventi che invii non devono superare i limiti di dimensione dell'evento.

Un trigger che in precedenza forniva eventi ha smesso di funzionare

1. Verifica che l'origine stia generando eventi. Controlla Cloud Audit Logs e assicurati che il servizio monitorato emetta log. Se i log vengono registrati, ma gli eventi non vengono distribuiti, contatta l'assistenza.

2. Verifica che esista un argomento Pub/Sub con lo stesso nome del trigger. Eventarc utilizza Pub/Sub come livello di trasporto e utilizzerà un argomento Pub/Sub esistente o creerà e gestirà automaticamente un argomento per te.

   1. Per elencare i trigger, vedi gcloud eventarc triggers list.

   2. Per elencare gli argomenti Pub/Sub, esegui:

      gcloud pubsub topics list
      

   3. Verifica che il nome dell'argomento Pub/Sub includa il nome del trigger creato. Ad esempio:

      name: projects/PROJECT_ID/topics/eventarc-us-east1-troubleshoot-trigger-new-123

   Se l'argomento Pub/Sub non è presente, crea di nuovo il trigger per un fornitore, un tipo di evento e una destinazione Cloud Run specifici.

3. Verifica che il trigger sia stato configurato per il servizio.

   1. Nella console Google Cloud , vai alla pagina Servizi.

      Vai a Servizi

   2. Fai clic sul nome del servizio per aprire la pagina Dettagli servizio.

   3. Fai clic sulla scheda Attivatori.

      Il trigger Eventarc associato al servizio dovrebbe essere elencato.

4. Verifica l'integrità dell'argomento e della sottoscrizione Pub/Sub utilizzando i tipi di metriche Pub/Sub.

   • Puoi monitorare i messaggi inoltrati non recapitabili utilizzando la metrica subscription/dead_letter_message_count. Questa metrica mostra il numero di messaggi non recapitabili che Pub/Sub inoltra da una sottoscrizione.

     Se i messaggi non vengono pubblicati nell'argomento, controlla Cloud Audit Logs e assicurati che il servizio monitorato emetta log. Se i log vengono registrati, ma gli eventi non vengono recapitati, contatta l'assistenza.

   • Puoi monitorare le iscrizioni push utilizzando la metrica subscription/push_request_count e raggruppandola per response_code e subcription_id.

     Se vengono segnalati errori push, controlla i log del servizio Cloud Run. Se l'endpoint di ricezione restituisce un codice di stato diverso da OK, significa che il codice Cloud Run non funziona come previsto e devi contattare l'assistenza.

   Per saperne di più, consulta Creare criteri di avviso basati su soglie delle metriche.