Google utilizza la tecnologia AI per tradurre i contenuti nella tua lingua preferita. Le traduzioni generate dall'AI potrebbero contenere errori.

Tutorial: risoluzione dei problemi locali di un servizio Cloud Run

Questo tutorial mostra come uno sviluppatore di servizi può risolvere i problemi di un servizio Cloud Run non funzionante utilizzando gli strumenti di Google Cloud Observability per il rilevamento e un flusso di lavoro di sviluppo locale per l'indagine.

Questo "case study" passo passo, che accompagna la guida alla risoluzione dei problemi, utilizza un progetto di esempio che genera errori di runtime durante il deployment, che puoi risolvere per trovare e correggere il problema.

Obiettivi

Scrivi, crea ed esegui il deployment di un servizio in Cloud Run
Utilizza Error Reporting e Cloud Logging per identificare un errore
Recuperare l'immagine container da Container Registry per un'analisi della causa principale
Correggere il servizio di "produzione", quindi migliorarlo per mitigare i problemi futuri

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 potrebbero avere diritto a una prova senza costi.

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 senza costi per l'esecuzione, il test e il deployment dei workload.

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

Roles required to select or create a project

Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
Create a project: To create a project, you need the Project Creator role (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

Go to project selector

Verify that billing is enabled for your Google Cloud project.

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

Roles required to select or create a project

Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
Create a project: To create a project, you need the Project Creator role (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

Go to project selector

Verify that billing is enabled for your Google Cloud project.

Abilita l'API Cloud Run Admin
Installa e inizializza gcloud CLI.
Aggiorna i componenti:
```
gcloud components update
```
Segui le istruzioni per installare Docker localmente

Ruoli obbligatori

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

Cloud Build Editor (roles/cloudbuild.builds.editor)
Cloud Run Admin (roles/run.admin)
Visualizzatore Error Reporting (roles/errorreporting.viewer)
Logs View Accessor (roles/logging.viewAccessor)
Project IAM Admin (roles/resourcemanager.projectIamAdmin)
Utente Service Account (roles/iam.serviceAccountUser)
Service Usage Consumer (roles/serviceusage.serviceUsageConsumer)
Storage Admin (roles/storage.admin)

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

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

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 la regione Cloud Run supportata che preferisci.

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.

La soddisfazione dei requisiti di latenza, disponibilità o durabilità è un fattore principale per la selezione della regione in cui vengono eseguiti i servizi Cloud Run. In genere puoi selezionare la regione più vicina ai tuoi utenti, ma devi considerare la posizione degli altri prodotti Google Cloud utilizzati dal tuo servizio Cloud Run. L'utilizzo di prodotti Google Cloud in sinergia in più località può influire sulla latenza del servizio e sui costi.

Cloud Run è disponibile nelle seguenti regioni:

Soggetto ai prezzi di Livello 1

asia-east1 (Taiwan)
asia-northeast1 (Tokyo)
asia-northeast2 (Osaka)
asia-south1 (Mumbai, India)
asia-southeast3 (Bangkok)
europe-north1 (Finlandia) Bassi livelli di CO₂
europe-north2 (Stoccolma) Bassi livelli di CO₂
europe-southwest1 (Madrid) Bassi livelli di CO₂
europe-west1 (Belgio) Bassi livelli di CO₂
europe-west4 (Paesi Bassi) Bassi livelli di CO₂
europe-west8 (Milano) Bassi livelli di CO₂
europe-west9 (Parigi) Bassi livelli di CO₂
me-west1 (Tel Aviv)
northamerica-south1 (Messico)
us-central1 (Iowa) Bassi livelli di CO₂
us-east1 (Carolina del Sud)
us-east4 (Virginia del Nord)
us-east5 (Columbus)
us-south1 (Dallas) Bassi livelli di CO₂
us-west1 (Oregon) Bassi livelli 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-south2 (Delhi, India)
australia-southeast1 (Sydney)
australia-southeast2 (Melbourne)
europe-central2 (Varsavia, Polonia) Bassi livelli di CO₂
europe-west10 (Berlino)
europe-west12 (Torino) Bassi livelli di CO₂
europe-west2 (Londra, Regno Unito) Bassi livelli di CO₂
europe-west3 (Francoforte, Germania)
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 consoleGoogle Cloud .

Assemblaggio del codice…

Crea un nuovo servizio di saluto Cloud Run passo dopo passo. Ti ricordiamo che questo servizio crea intenzionalmente un errore di runtime per l'esercizio di risoluzione dei problemi.

Crea un nuovo progetto:

Node.js

Crea un progetto Node.js definendo il pacchetto di servizi, le dipendenze iniziali e alcune operazioni comuni.

Crea una nuova directory hello-service:
```
mkdir hello-service
cd hello-service
```
Crea un nuovo progetto Node.js generando un file package.json:
```
npm init --yes
npm install express@4
```

Apri il nuovo file package.json nell'editor e configura uno script start per eseguire node index.js. Al termine, il file avrà il seguente aspetto:

{
  "name": "hello-broken",
  "description": "Broken Cloud Run service for troubleshooting practice",
  "version": "1.0.0",
  "private": true,
  "main": "index.js",
  "scripts": {
    "start": "node index.js",
    "test": "echo \"Error: no test specified\" && exit 0",
    "system-test": "NAME=Cloud c8 mocha -p -j 2 test/system.test.js --timeout=360000 --exit"
  },
  "engines": {
    "node": ">=20.0.0"
  },
  "author": "Google LLC",
  "license": "Apache-2.0",
  "dependencies": {
    "express": "^5.0.0"
  },
  "devDependencies": {
    "c8": "^12.0.0",
    "google-auth-library": "^9.0.0",
    "got": "^11.5.0",
    "mocha": "^10.0.0"
  }
}

Se continui a sviluppare questo servizio oltre il tutorial immediato, valuta la possibilità di compilare la descrizione, l'autore e valutare la licenza. Per maggiori dettagli, consulta la documentazione di package.json.

Python

Crea una nuova directory hello-service:
```
mkdir hello-service
cd hello-service
```

Crea un file requirements.txt e copia le dipendenze al suo interno:

pytest==9.0.3; python_version >= "3.10"
Flask==3.1.3; python_version >= '3.9'
gunicorn==23.0.0
Werkzeug==3.1.9; python_version >= '3.10'

Vai

Crea una nuova directory hello-service:
```
mkdir hello-service
cd hello-service
```
Crea un progetto Go inizializzando un nuovo modulo Go:
```
go mod init example.com/hello-service
```

Puoi aggiornare il nome specifico come preferisci: devi aggiornare il nome se il codice viene pubblicato in un repository di codice accessibile dal web.

Java

Crea un nuovo progetto Maven:

mvn archetype:generate \
  -DgroupId=com.example.cloudrun \
  -DartifactId=hello-service \
  -DarchetypeArtifactId=maven-archetype-quickstart \
  -DinteractiveMode=false

Copia le dipendenze nell'elenco delle dipendenze pom.xml (tra gli elementi <dependencies>):

<dependency>
  <groupId>com.sparkjava</groupId>
  <artifactId>spark-core</artifactId>
  <version>2.9.4</version>
</dependency>
<dependency>
  <groupId>org.slf4j</groupId>
  <artifactId>slf4j-api</artifactId>
  <version>2.0.12</version>
</dependency>
<dependency>
  <groupId>org.slf4j</groupId>
  <artifactId>slf4j-simple</artifactId>
  <version>2.0.12</version>
</dependency>

Copia l'impostazione di build nel file pom.xml (sotto gli elementi <dependencies>):

<build>
  <plugins>
    <plugin>
      <groupId>com.google.cloud.tools</groupId>
      <artifactId>jib-maven-plugin</artifactId>
      <version>3.4.0</version>
      <configuration>
        <to>
          <image>gcr.io/PROJECT_ID/hello-service</image>
        </to>
      </configuration>
    </plugin>
  </plugins>
</build>

Crea un servizio HTTP per gestire le richieste in entrata:

Node.js

const express = require('express');
const app = express();

app.get('/', (req, res) => {
  console.log('hello: received request.');

  const {NAME} = process.env;
  if (!NAME) {
    // Plain error logs do not appear in Stackdriver Error Reporting.
    console.error('Environment validation failed.');
    console.error(new Error('Missing required server parameter'));
    return res.status(500).send('Internal Server Error');
  }
  res.send(`Hello ${NAME}!`);
});
const port = parseInt(process.env.PORT) || 8080;
app.listen(port, () => {
  console.log(`hello: listening on port ${port}`);
});

Python

import json
import os

from flask import Flask


app = Flask(__name__)


@app.route("/", methods=["GET"])
def index():
    """Example route for testing local troubleshooting.

    This route may raise an HTTP 5XX error due to missing environment variable.
    """
    print("hello: received request.")

    NAME = os.getenv("NAME")

    if not NAME:
        print("Environment validation failed.")
        raise Exception("Missing required service parameter.")

    return f"Hello {NAME}"


if __name__ == "__main__":
    PORT = int(os.getenv("PORT")) if os.getenv("PORT") else 8080

    # This is used when running locally. Gunicorn is used to run the
    # application on Cloud Run. See entrypoint in Dockerfile.
    app.run(host="127.0.0.1", port=PORT, debug=True)

Go


// Sample hello demonstrates a difficult to troubleshoot service.
package main

import (
	"fmt"
	"log"
	"net/http"
	"os"
)

func main() {
	log.Print("hello: service started")

	http.HandleFunc("/", helloHandler)


	port := os.Getenv("PORT")
	if port == "" {
		port = "8080"
		log.Printf("Defaulting to port %s", port)
	}

	log.Printf("Listening on port %s", port)
	log.Fatal(http.ListenAndServe(fmt.Sprintf(":%s", port), nil))
}

func helloHandler(w http.ResponseWriter, r *http.Request) {
	log.Print("hello: received request")

	name := os.Getenv("NAME")
	if name == "" {
		log.Printf("Missing required server parameter")
		// The panic stack trace appears in Cloud Error Reporting.
		panic("Missing required server parameter")
	}

	fmt.Fprintf(w, "Hello %s!\n", name)
}

Java

import static spark.Spark.get;
import static spark.Spark.port;

import org.slf4j.Logger;
import org.slf4j.LoggerFactory;

public class App {

  private static final Logger logger = LoggerFactory.getLogger(App.class);

  public static void main(String[] args) {
    int port = Integer.parseInt(System.getenv().getOrDefault("PORT", "8080"));
    port(port);

    get(
        "/",
        (req, res) -> {
          logger.info("Hello: received request.");
          String name = System.getenv("NAME");
          if (name == null) {
            // Standard error logs do not appear in Stackdriver Error Reporting.
            System.err.println("Environment validation failed.");
            String msg = "Missing required server parameter";
            logger.error(msg, new Exception(msg));
            res.status(500);
            return "Internal Server Error";
          }
          res.status(200);
          return String.format("Hello %s!", name);
        });
  }
}

Crea un Dockerfile per definire l'immagine container utilizzata per eseguire il deployment del servizio:

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 copying both package.json AND package-lock.json (when available).
# Copying this first 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.14

# 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.
# Timeout is set to 0 to disable the timeouts of the workers to allow Cloud Run to handle instance scaling.
CMD exec gunicorn --bind :$PORT --workers 1 --threads 8 --timeout 0 main:app

Go


# 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.25-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

Questo esempio utilizza Jib per creare immagini Docker utilizzando strumenti Java comuni. Jib ottimizza le build dei container senza la necessità di un Dockerfile o di avere Docker installato. Scopri di più sulla creazione di container Java con Jib.

<plugin>
  <groupId>com.google.cloud.tools</groupId>
  <artifactId>jib-maven-plugin</artifactId>
  <version>3.4.0</version>
  <configuration>
    <to>
      <image>gcr.io/PROJECT_ID/hello-service</image>
    </to>
  </configuration>
</plugin>

Spedizione del codice

La distribuzione del codice prevede tre passaggi: la creazione di un'immagine container con Cloud Build, il caricamento dell'immagine container in Container Registry e il deployment dell'immagine container in Cloud Run.

Per spedire il codice:

Crea il container e pubblicalo in Container Registry:
Node.js
```
gcloud builds submit --tag gcr.io/PROJECT_ID/hello-service
```
Dove PROJECT_ID è l'ID del tuo progetto Google Cloud. Puoi controllare l'ID progetto corrente con gcloud config get-value project.

In caso di esito positivo, dovresti visualizzare un messaggio SUCCESS contenente l'ID, l'ora di creazione e il nome dell'immagine. L'immagine è archiviata in Container Registry e, se lo desideri, può essere riutilizzata.
Python
```
gcloud builds submit --tag gcr.io/PROJECT_ID/hello-service
```
Dove PROJECT_ID è l'ID del tuo progetto Google Cloud. Puoi controllare l'ID progetto corrente con gcloud config get-value project.

In caso di esito positivo, dovresti visualizzare un messaggio SUCCESS contenente l'ID, l'ora di creazione e il nome dell'immagine. L'immagine è archiviata in Container Registry e, se lo desideri, può essere riutilizzata.
Vai
```
gcloud builds submit --tag gcr.io/PROJECT_ID/hello-service
```
Dove PROJECT_ID è l'ID del tuo progetto Google Cloud. Puoi controllare l'ID progetto corrente con gcloud config get-value project.

In caso di esito positivo, dovresti visualizzare un messaggio SUCCESS contenente l'ID, l'ora di creazione e il nome dell'immagine. L'immagine è archiviata in Container Registry e, se lo desideri, può essere riutilizzata.
Java
1. Utilizza l'helper per le credenziali gcloud per autorizzare Docker a eseguire il push in Container Registry.
  gcloud auth configure-docker
2. Utilizza il plug-in Jib Maven per creare il container ed eseguirne il push su Container Registry.
  mvn compile jib:build -Dimage=gcr.io/PROJECT_ID/hello-service
Dove PROJECT_ID è l'ID del tuo progetto Google Cloud. Puoi controllare l'ID progetto corrente con gcloud config get-value project.

Se l'operazione va a buon fine, dovresti visualizzare un messaggio BUILD SUCCESS. L'immagine è archiviata in Container Registry e, se lo desideri, può essere riutilizzata.
Esegui questo comando per eseguire il deployment della tua app:
```
gcloud run deploy hello-service --image gcr.io/PROJECT_ID/hello-service
```
Sostituisci PROJECT_ID con l'ID progetto Google Cloud. hello-service è sia il nome dell'immagine container sia il nome del servizio Cloud Run. Tieni presente che il deployment dell'immagine container viene eseguito nel servizio e nella regione che hai configurato in precedenza in Configurazione di gcloud.

Rispondi y, "Yes", alla richiesta allow unauthenticated. Per ulteriori dettagli sull'autenticazione basata su IAM, consulta Gestione dell'accesso.

Attendi il completamento del deployment: l'operazione può richiedere circa 30 secondi. Se l'operazione riesce, la riga di comando visualizza l'URL del servizio.

Provalo

Prova il servizio per verificare di averne eseguito il deployment correttamente. Le richieste dovrebbero non riuscire con un errore HTTP 500 o 503 (membri della classe Errori del server 5xx). Il tutorial illustra la risoluzione dei problemi relativi a questa risposta di errore.

Al servizio viene assegnato automaticamente un URL navigabile.

Vai a questo URL con il tuo browser web:
1. Apri un browser web
2. Trova l'URL del servizio restituito dal comando di deployment precedente.
  
  Se il comando di deployment non ha fornito un URL, significa che si è verificato un problema. Esamina il messaggio di errore e agisci di conseguenza: se non sono presenti indicazioni utili, consulta la guida alla risoluzione dei problemi ed eventualmente riprova a eseguire il comando di deployment.
3. Vai a questo URL copiandolo nella barra degli indirizzi del browser e premendo INVIO.
Visualizza l'errore HTTP 500 o HTTP 503.

Se ricevi un errore HTTP 403, potresti aver rifiutato allow unauthenticated invocations al prompt di deployment. Per risolvere il problema, concedi l'accesso pubblico al servizio:
```
gcloud run services add-iam-policy-binding hello-service \
  --member="allUsers" \
  --role="roles/run.invoker"
```

Per saperne di più, consulta Consentire l'accesso pubblico (non autenticato).

Esaminare il problema

Immagina che l'errore HTTP 5xx riscontrato in precedenza in Prova sia stato riscontrato come errore di runtime di produzione. Questo tutorial illustra una procedura formale per gestirlo. Sebbene i processi di risoluzione degli errori di produzione varino ampiamente, questo tutorial presenta una particolare sequenza di passaggi per mostrare l'applicazione di strumenti e tecniche utili.

Per esaminare questo problema, seguirai queste fasi:

Raccogli maggiori dettagli sull'errore segnalato per supportare ulteriori indagini e definire una strategia di mitigazione.
Riduci l'impatto sugli utenti decidendo di procedere con una correzione o di eseguire il rollback a una versione nota e funzionante.
Riproduci l'errore per verificare che siano stati raccolti i dettagli corretti e che l'errore non sia un problema isolato.
Esegui un'analisi delle cause principali del bug per trovare il codice, la configurazione o il processo che ha generato l'errore

All'inizio dell'indagine hai un URL, un timestamp e il messaggio "Errore interno del server".

Raccolta di ulteriori dettagli in corso…

Raccogli maggiori informazioni sul problema per capire cosa è successo e determinare i passaggi successivi.

Utilizza gli strumenti di Google Cloud Observability disponibili per raccogliere ulteriori dettagli:

Utilizza la console di Error Reporting, che fornisce una dashboard con dettagli e monitoraggio delle ricorrenze per gli errori con un'analisi dello stack riconosciuta.

Vai alla console di Error Reporting

Elenco degli errori registrati. Gli errori vengono raggruppati per messaggio tra revisioni, servizi e piattaforme.
Fai clic sull'errore per visualizzare i dettagli dell'analisi dello stack, prendendo nota delle chiamate di funzione effettuate appena prima dell'errore.

L'esempio di analisi dello stack nella pagina dei dettagli dell'errore mostra una singola istanza dell'errore. Puoi esaminare ogni singola istanza.
Utilizza Cloud Logging per esaminare la sequenza di operazioni che hanno portato al problema, inclusi i messaggi di errore non inclusi nella console di Error Reporting a causa della mancanza di un'analisi dello stack degli errori riconosciuta:

Vai alla console Cloud Logging

Seleziona Revisione Cloud Run > hello-service dalla prima casella a discesa. In questo modo, le voci di log verranno filtrate in base a quelle generate dal tuo servizio.

Scopri di più sulla visualizzazione dei log in Cloud Run

Rollback a una versione integra

Se si tratta di un servizio consolidato, noto per funzionare, sarà presente una revisione precedente del servizio su Cloud Run. Questo tutorial utilizza un nuovo servizio senza versioni precedenti, quindi non puoi eseguire un rollback.

Tuttavia, se hai un servizio con versioni precedenti a cui puoi eseguire il rollback, segui Visualizzazione dei dettagli della revisione per estrarre il nome del container e i dettagli di configurazione necessari per creare un nuovo deployment funzionante del servizio.

Riproduzione dell'errore

Utilizzando i dettagli ottenuti in precedenza, verifica che il problema si verifichi costantemente in condizioni di test.

Invia la stessa richiesta HTTP provandola di nuovo e verifica se vengono segnalati lo stesso errore e gli stessi dettagli. La visualizzazione dei dettagli dell'errore potrebbe richiedere un po' di tempo.

Poiché il servizio di esempio in questo tutorial è di sola lettura e non attiva effetti collaterali complessi, la riproduzione degli errori in produzione è sicura. Tuttavia, per molti servizi reali, non sarà così: potresti dover riprodurre gli errori in un ambiente di test o limitare questo passaggio all'indagine locale.

La riproduzione dell'errore stabilisce il contesto per ulteriori interventi. Ad esempio, se gli sviluppatori non riescono a riprodurre l'errore, ulteriori indagini potrebbero richiedere una strumentazione aggiuntiva del servizio.

Esecuzione di un'analisi delle cause principali

L'analisi delle cause principali è un passaggio importante per una risoluzione dei problemi efficace, per assicurarti di risolvere il problema anziché un sintomo.

In precedenza in questo tutorial, hai riprodotto il problema su Cloud Run, il che conferma che il problema è attivo quando il servizio è ospitato su Cloud Run. Ora riproduci il problema localmente per determinare se è isolato nel codice o se si verifica solo nell'hosting di produzione.

Se non hai utilizzato Docker CLI localmente con Container Registry, autenticalo con gcloud:
```
gcloud auth configure-docker
```
Per approcci alternativi, consulta Metodi di autenticazione di Container Registry.
Se il nome dell'immagine container utilizzata più di recente non è disponibile, la descrizione del servizio contiene le informazioni sull'immagine container di cui è stato eseguito il deployment più di recente:
```
gcloud run services describe hello-service
```
Trova il nome dell'immagine container all'interno dell'oggetto spec. Un comando più mirato può recuperarlo direttamente:
```
gcloud run services describe hello-service \
   --format="value(spec.template.spec.containers.image)"
```
Questo comando mostra un nome dell'immagine container, ad esempio gcr.io/PROJECT_ID/hello-service.
Esegui il pull dell'immagine container da Container Registry nel tuo ambiente. Questo passaggio potrebbe richiedere diversi minuti, poiché l'immagine container viene scaricata:
```
docker pull gcr.io/PROJECT_ID/hello-service
```
Gli aggiornamenti successivi dell'immagine container che riutilizzano questo nome possono essere recuperati con lo stesso comando. Se salti questo passaggio, il comando docker run riportato di seguito esegue il pull di un'immagine container se non è presente sulla macchina locale.
Esegui il servizio localmente per verificare che il problema non sia specifico di Cloud Run:
```
PORT=8080 && docker run --rm -e PORT=$PORT -p 9000:$PORT \
   gcr.io/PROJECT_ID/hello-service
```
Analizzando gli elementi del comando precedente:
- La variabile di ambiente PORT viene utilizzata dal servizio per determinare la porta su cui ascoltare all'interno del container.
- Il comando run avvia il container, utilizzando per impostazione predefinita il comando entrypoint definito nel Dockerfile o in un'immagine container principale.
- Il flag --rm elimina l'istanza del container all'uscita.
- Il flag -e assegna un valore a una variabile di ambiente. -e PORT=$PORT propaga la variabile PORT dal sistema locale al container con lo stesso nome della variabile.
- Il flag -p pubblica il container come servizio disponibile su localhost alla porta 9000. Le richieste a localhost:9000 verranno indirizzate al container sulla porta 8080. Ciò significa che l'output del servizio relativo al numero di porta in uso non corrisponderà alla modalità di accesso al servizio.
- L'argomento finale gcr.io/PROJECT_ID/hello-service è un'immagine container tag, un'etichetta leggibile per l'identificatore hash sha256 di un'immagine container. Se non è disponibile localmente, Docker tenta di recuperare l'immagine da un registry remoto.
Nel browser, apri http://localhost:9000. Controlla l'output del terminale per verificare se sono presenti messaggi di errore corrispondenti a quelli su {ops_name}}.

Se il problema non è riproducibile localmente, potrebbe essere specifico dell'ambiente Cloud Run. Consulta la guida alla risoluzione dei problemi di Cloud Run per aree specifiche da esaminare.

In questo caso l'errore viene riprodotto localmente.

Ora che l'errore è stato confermato due volte come persistente e causato dal codice del servizio anziché dalla piattaforma di hosting, è il momento di esaminare il codice più da vicino.

Ai fini di questo tutorial, è sicuro presumere che il codice all'interno del container e il codice nel sistema locale siano identici.

Rivedi l'analisi dello stack del report sugli errori e fai un controllo incrociato con il codice per trovare le righe specifiche che hanno causato l'errore.

Node.js

Individua l'origine del messaggio di errore nel file index.js intorno al numero di riga indicato nell'analisi dello stack mostrata nei log:

const {NAME} = process.env;
if (!NAME) {
  // Plain error logs do not appear in Stackdriver Error Reporting.
  console.error('Environment validation failed.');
  console.error(new Error('Missing required server parameter'));
  return res.status(500).send('Internal Server Error');
}

Python

Individua l'origine del messaggio di errore nel file main.py intorno al numero di riga indicato nell'analisi dello stack mostrata nei log:

NAME = os.getenv("NAME")

if not NAME:
    print("Environment validation failed.")
    raise Exception("Missing required service parameter.")

Vai

Individua l'origine del messaggio di errore nel file main.go intorno al numero di riga indicato nell'analisi dello stack mostrata nei log:

name := os.Getenv("NAME")
if name == "" {
	log.Printf("Missing required server parameter")
	// The panic stack trace appears in Cloud Error Reporting.
	panic("Missing required server parameter")
}

Java

Trova l'origine del messaggio di errore nel file App.java intorno al numero di riga indicato nell'analisi dello stack mostrata nei log:

String name = System.getenv("NAME");
if (name == null) {
  // Standard error logs do not appear in Stackdriver Error Reporting.
  System.err.println("Environment validation failed.");
  String msg = "Missing required server parameter";
  logger.error(msg, new Exception(msg));
  res.status(500);
  return "Internal Server Error";
}

Esaminando questo codice, vengono eseguite le seguenti azioni quando la variabile di ambiente NAME non è impostata:

Un errore viene registrato in Google Cloud Observability
Viene inviata una risposta di errore HTTP

Il problema è causato da una variabile mancante, ma la causa principale è più specifica: la modifica del codice che aggiunge la dipendenza rigida da una variabile di ambiente non includeva le modifiche correlate agli script di deployment e alla documentazione dei requisiti di runtime.

Risolvere la causa principale

Ora che abbiamo raccolto il codice e identificato la potenziale causa principale, possiamo adottare le misure necessarie per risolvere il problema.

Controlla se il servizio funziona localmente con l'ambiente NAME disponibile:
1. Esegui il container in locale con la variabile di ambiente aggiunta:
```
PORT=8080 && docker run --rm -e PORT=$PORT -p 9000:$PORT \
 -e NAME="Local World!" \
 gcr.io/PROJECT_ID/hello-service
```
2. Vai all'indirizzo http://localhost:9000 nel browser.
3. Visualizza "Hello Local World!" sulla pagina
Modifica l'ambiente del servizio Cloud Run in esecuzione per includere questa variabile:
1. Esegui il comando services update per aggiungere una variabile di ambiente:
```
gcloud run services update hello-service \
  --set-env-vars NAME=Override
```
2. Attendi qualche secondo mentre Cloud Run crea una nuova revisione basata sulla revisione precedente con la nuova variabile di ambiente aggiunta.
Verifica che il servizio sia stato corretto:
1. Vai all'URL del servizio Cloud Run nel browser.
2. Nella pagina viene visualizzato il messaggio "Hello Override!".
3. Verifica che in Cloud Logging o Error Reporting non vengano visualizzati messaggi o errori imprevisti.

Migliorare la velocità di risoluzione dei problemi futuri

In questo esempio di problema di produzione, l'errore era correlato alla configurazione operativa. Sono state apportate modifiche al codice che ridurranno al minimo l'impatto di questo problema in futuro.

Migliorare il log degli errori per includere dettagli più specifici.
Anziché restituire un errore, fai in modo che il servizio utilizzi un valore predefinito sicuro. Se l'utilizzo di un valore predefinito rappresenta una modifica alla funzionalità normale, utilizza un messaggio di avviso per scopi di monitoraggio.

Vediamo come rimuovere la variabile di ambiente NAME come dipendenza fissa.

Rimuovi il codice di gestione di NAME esistente:

Node.js

const {NAME} = process.env;
if (!NAME) {
  // Plain error logs do not appear in Stackdriver Error Reporting.
  console.error('Environment validation failed.');
  console.error(new Error('Missing required server parameter'));
  return res.status(500).send('Internal Server Error');
}

Python

NAME = os.getenv("NAME")

if not NAME:
    print("Environment validation failed.")
    raise Exception("Missing required service parameter.")

Go

name := os.Getenv("NAME")
if name == "" {
	log.Printf("Missing required server parameter")
	// The panic stack trace appears in Cloud Error Reporting.
	panic("Missing required server parameter")
}

Java

String name = System.getenv("NAME");
if (name == null) {
  // Standard error logs do not appear in Stackdriver Error Reporting.
  System.err.println("Environment validation failed.");
  String msg = "Missing required server parameter";
  logger.error(msg, new Exception(msg));
  res.status(500);
  return "Internal Server Error";
}

Aggiungi un nuovo codice che imposta un valore di riserva:

Node.js

const NAME = process.env.NAME || 'World';
if (!process.env.NAME) {
  console.log(
    JSON.stringify({
      severity: 'WARNING',
      message: `NAME not set, default to '${NAME}'`,
    })
  );
}

Python

NAME = os.getenv("NAME")

if not NAME:
    NAME = "World"
    error_message = {
        "severity": "WARNING",
        "message": f"NAME not set, default to {NAME}",
    }
    print(json.dumps(error_message))

Go

name := os.Getenv("NAME")
if name == "" {
	name = "World"
	log.Printf("warning: NAME not set, default to %s", name)
}

Java

String name = System.getenv().getOrDefault("NAME", "World");
if (System.getenv("NAME") == null) {
  logger.warn(String.format("NAME not set, default to %s", name));
}

Esegui un test in locale ricreando ed eseguendo il container nei casi di configurazione interessati:

Node.js

docker build --tag gcr.io/PROJECT_ID/hello-service .

Python

docker build --tag gcr.io/PROJECT_ID/hello-service .

Go

docker build --tag gcr.io/PROJECT_ID/hello-service .

Java

mvn compile jib:build

Verifica che la variabile di ambiente NAME funzioni ancora:

PORT=8080 && docker run --rm -e PORT=$PORT -p 9000:$PORT \
 -e NAME="Robust World" \
 gcr.io/PROJECT_ID/hello-service

Verifica che il servizio funzioni senza la variabile NAME:

PORT=8080 && docker run --rm -e PORT=$PORT -p 9000:$PORT \
 gcr.io/PROJECT_ID/hello-service

Se il servizio non restituisce un risultato, verifica che la rimozione del codice nel primo passaggio non abbia rimosso righe aggiuntive, ad esempio quelle utilizzate per scrivere la risposta.

Esegui il deployment di questo codice rivisitando la sezione Esegui il deployment del codice.

Ogni deployment in un servizio crea una nuova revisione e inizia automaticamente a gestire il traffico quando è pronto.

Per cancellare le variabili di ambiente impostate in precedenza:

gcloud run services update hello-service --clear-env-vars

Aggiungi la nuova funzionalità per il valore predefinito alla copertura dei test automatici per il servizio.

Individuazione di altri problemi nei log

Potresti visualizzare altri problemi nel visualizzatore log per questo servizio. Ad esempio, una chiamata di sistema non supportata verrà visualizzata nei log come "Limitazione della sandbox del container".

Ad esempio, i servizi Node.js a volte generano questo messaggio di log:

Container Sandbox Limitation: Unsupported syscall statx(0xffffff9c,0x3e1ba8e86d88,0x0,0xfff,0x3e1ba8e86970,0x3e1ba8e86a90). Please, refer to https://gvisor.dev/c/linux/amd64/statx for more information.

In questo caso, la mancanza di supporto non influisce sul servizio di esempio hello-service.

Risoluzione dei problemi di Terraform

Per domande o problemi relativi a Terraform, consulta Risoluzione dei problemi di convalida delle policy di Terraform o contatta l'assistenza di Terraform.

Esegui la pulizia

Per evitare che al tuo account Google Cloud vengano addebitati costi aggiuntivi, elimina tutte le risorse di cui hai eseguito il deployment con questo tutorial.

Elimina il progetto

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.

Il modo più semplice per eliminare la fatturazione è eliminare il progetto 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, eliminerai anche tutto il lavoro che hai 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 progetto, quindi fai clic su Chiudi per eliminare il progetto.

Elimina le risorse del tutorial

Elimina il servizio Cloud Run di cui hai eseguito il deployment in questo tutorial. I servizi Cloud Run non comportano costi finché non ricevono richieste.

Per eliminare il servizio Cloud Run, esegui questo comando:
```
gcloud run services delete SERVICE-NAME
```
Sostituisci SERVICE-NAME con il nome del servizio.

Puoi eliminare i servizi Cloud Run anche dalla consoleGoogle Cloud .
Rimuovi la configurazione della regione predefinita gcloud che hai aggiunto 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 l'immagine container denominata gcr.io/<var>PROJECT_ID</var>/hello-service da Container Registry.

Passaggi successivi

Scopri di più su come utilizzare Cloud Logging ed Error Reporting per ottenere insight sul comportamento di produzione.
Per saperne di più sulla risoluzione dei problemi di Cloud Run, consulta la guida alla risoluzione dei problemi.
Esplora architetture, diagrammi e best practice di riferimento su Google Cloud. Consulta il nostro Cloud Architecture Center.

Tutorial: risoluzione dei problemi locali di un servizio Cloud Run Mantieni tutto organizzato con le raccolte Salva e classifica i contenuti in base alle tue preferenze.

Obiettivi

Costi

Prima di iniziare

Ruoli obbligatori

Configurazione delle impostazioni predefinite di gcloud

Località di Cloud Run

Soggetto ai prezzi di Livello 1

Soggetto ai prezzi di Livello 2

Assemblaggio del codice…

Node.js

Python

Vai

Java

Node.js

Python

Go

Java

Node.js

Python

Go

Java

Spedizione del codice

Node.js

Python

Vai

Java

Provalo

Esaminare il problema

Raccolta di ulteriori dettagli in corso…

Rollback a una versione integra

Riproduzione dell'errore

Esecuzione di un'analisi delle cause principali

Node.js

Python

Vai

Java

Risolvere la causa principale

Migliorare la velocità di risoluzione dei problemi futuri

Node.js

Python

Go

Java

Node.js

Python

Go

Java

Node.js

Python

Go

Java

Individuazione di altri problemi nei log

Risoluzione dei problemi di Terraform

Esegui la pulizia

Elimina il progetto

Elimina le risorse del tutorial

Passaggi successivi

Tutorial: risoluzione dei problemi locali di un servizio Cloud Run