Best practice per le richieste di assistenza di Apigee per Google Cloud

Stai visualizzando la documentazione di Apigee e Apigee hybrid.
Visualizza la documentazione di Apigee Edge.

Fornire informazioni dettagliate e richieste nella richiesta di assistenza consente al team di Assistenza Google Cloud di risponderti in modo più rapido ed efficiente. Quando nella tua richiesta di assistenza mancano dettagli critici, dobbiamo chiederti ulteriori informazioni, il che potrebbe comportare un passaggio continuo più volte. Questa operazione richiede più tempo e può comportare ritardi nella risoluzione dei problemi. Questa guida alle best practice fornisce informazioni utili per risolvere più rapidamente la tua richiesta di assistenza tecnica.

Descrizione del problema

Un problema deve contenere informazioni che spiegano i dettagli di ciò che è accaduto rispetto a quello previsto, nonché di quando e come è successo. Una richiesta di assistenza valida deve contenere le seguenti informazioni chiave per ciascuno dei prodotti Apigee:

Informazioni chiave Descrizione Apigee su Google Cloud Apigee hybrid
Prodotto Prodotto Apigee specifico in cui si verifica il problema, incluse informazioni sulla versione, ove applicabili.
  • Versione ibrida
Dettagli del problema Descrizione chiara e dettagliata del problema che lo chiarisce, incluso l'eventuale messaggio di errore completo.
  • Messaggio di errore
  • Output strumento di debug
  • Passaggi per riprodurre il problema
  • Comando/richiesta API completa
  • Messaggio di errore
  • Output strumento di debug
  • Passaggi per riprodurre il problema
  • Comando/richiesta API completa
  • Log diagnostici dei componenti
  • Metriche di Cloud Monitoring
Tempo Il timestamp specifico del momento in cui si è verificato il problema e della sua durata.
  • Data, ora e fuso orario in cui si è verificato il problema
  • Durata del problema
  • Data, ora e fuso orario in cui si è verificato il problema
  • Durata del problema
Configurazione Informazioni dettagliate su dove si verifica il problema.
  • Nome organizzazione
  • Nome busta
  • Nome proxy API
  • Revisione

Nelle sezioni seguenti vengono descritti questi concetti in modo più dettagliato.

Prodotto

Esistono diversi prodotti Apigee, Apigee su Google Cloud e Apigee su Google Cloud, quindi abbiamo bisogno di informazioni specifiche riguardo a quale prodotto specifico presenta il problema.

La seguente tabella fornisce alcuni esempi che mostrano informazioni complete nella colonna Cose da fare e informazioni incomplete nella colonna Cose da fare:

Cosa fare Cosa non fare
Il deployment del proxy API OAuth2 non è riuscito sulla nostra organizzazione Apigee su Google Cloud ...

Deployment del proxy API non riuscito

(Dobbiamo sapere il prodotto Apigee in cui riscontri il problema).

Stiamo ricevendo il seguente errore durante l'accesso a Cassandra utilizzando cqlsh su Apigee hybrid versione 1.3 ...

Impossibile accedere a Cassandra utilizzando cqlsh.

(Informazioni sulla versione ibrida mancanti)

Dettagli del problema

Fornisci informazioni precise sul problema osservato, inclusi il messaggio di errore (se presente) e il comportamento previsto ed effettivo osservato.

La seguente tabella fornisce alcuni esempi che mostrano informazioni complete nella colonna Cose da fare e informazioni incomplete nella colonna Cose da fare:

Cosa fare Cosa non fare

Il nuovo proxy edgemicro edgemicro_auth non funziona con il seguente errore:

{"error":"missing_authorization","error_description":"Missing Authorization header"}

Nuovo proxy edgemicro creato oggi non funzionante

Il nome del proxy è sconosciuto. Non è chiaro se il proxy restituisca un errore o una risposta imprevista.)

I nostri client ricevono errori 500 con il seguente messaggio di errore durante l'invio di richieste al proxy API:

{"fault":{"faultstring":"Execution of JSReadResponse failed with error: Javascript runtime error: \"TypeError: Cannot read property \"content\" from undefined. (JSReadResponse.js:23)","detail":{"errorcode":"steps.javascript.ScriptExecutionFailed"}}}

I nostri client ricevono errori 500 durante l'invio delle richieste al proxy API.

(La semplice comunicazione di 500 errori non ci fornisce informazioni adeguate per consentirci di effettuare accertamenti in merito al problema. Abbiamo bisogno di conoscere il messaggio e il codice di errore effettivi che vengono osservati.)

Tempo

Il tempo è un'informazione molto importante. È importante che il tecnico dell'assistenza sappia quando hai notato il problema per la prima volta, quanto è durato e se il problema persiste.

L'esperto di assistenza che risolve il problema potrebbe non trovarsi nel tuo fuso orario, quindi dichiarazioni relative al tempo rendono più difficile la diagnosi del problema. Di conseguenza, ti consigliamo di utilizzare il formato ISO 8601 per la data e il timestamp, in modo da fornire informazioni sull'ora esatta in cui è stato rilevato il problema.

La seguente tabella fornisce alcuni esempi che mostrano l'ora e la durata precise per cui si è verificato il problema nella colonna Cose da fare e informazioni ambigue o non chiare relative al momento in cui si è verificato il problema nella colonna Cosa non fare:

Cosa fare Cosa non fare
Un numero enorme di 503s è stato osservato ieri tra il 6/11/2020 alle 17:30 PDT e il 6/11/2020 alle 17:35 PDT...

Un numero enorme di 503s è stato osservato ieri alle 17:30 per 5 minuti.

(Siamo costretti a utilizzare la data implicita e non è chiaro nemmeno il fuso orario in cui è stato riscontrato il problema.)

Sono state osservate latenze elevate sui seguenti proxy API dal 9/11/2020 15:30 IST al 09/11/2020 18:10 ...

La scorsa settimana sono state osservate latenze elevate su alcuni proxy API.

(Non è chiaro il giorno e la durata in cui il problema è stato riscontrato nell'ultima settimana).

Configurazione

Abbiamo bisogno di conoscere i dettagli relativi al punto esatto in cui riscontri il problema. A seconda del prodotto che utilizzi, abbiamo bisogno delle seguenti informazioni:

  • Se utilizzi Apigee su Google Cloud, potresti avere più di un'organizzazione, quindi dobbiamo conoscere l'organizzazione specifica e altri dettagli in cui stai riscontrando il problema:
    • Nomi di organizzazioni e ambienti
    • Nome del proxy API e numeri di revisione (per errori di richieste API)
  • Se utilizzi ibrid, è possibile che tu stia utilizzando una delle tante piattaforme ibride e delle topologie di installazione supportate. Quindi dobbiamo sapere quale piattaforma e topologia ibrida stai utilizzando, inclusi i dettagli come il numero di data center e nodi.

La seguente tabella fornisce alcuni esempi che mostrano informazioni complete nella colonna Cose da fare e informazioni incomplete nella colonna Cose da fare:

Cosa fare Cosa non fare

401 Gli errori sono aumentati su Apigee su Google Cloud dal 6/11/2020 alle 09:30 CST.

Dettagli di configurazione Apigee:

I dettagli dell'API in errore sono i seguenti:
Nomi delle organizzazioni: myorg
Nomi degli ambienti: test
Nomi dei proxy API: myproxy
Numeri di revisione: 3

Errore:

{"fault":{"faultstring":"Failed to resolve API Key variable request.header.X-APP-API_KEY","detail":{"errorcode":"steps.oauth.v2.FailedToResolveAPIKey"}}}

401 errori sono aumentati.

Non sono fornite informazioni sul prodotto in uso, dal momento che il problema viene osservato o eventuali dettagli di configurazione.

Il debug non funziona con il seguente errore nella versione ibrida Apigee 1.3

Errore:

Error while Creating trace session for corp-apigwy-discovery, revision 3, environment dev.

Failed to create DebugSession {apigee-hybrid-123456 dev corp-apigwy-discovery 3 ca37384e-d3f4-4971-9adb-dcc36c392bb1}

Dettagli sulla configurazione ibrida di Apigee:

  • Piattaforma ibrida Apigee:
    Anthos GKE On-Prem versione 1.4.0
  • Progetto Google Cloud, organizzazione e ambiente ibridi
    ID progetto Google Cloud: apigee-hybrid-123456
    organizzazione ibrida Apigee: apigee-hybrid-123456
    ambiente ibrido Apigee: dev
  • Dettagli del nome del cluster Kubernetes
    k8sCluster:
    nome: user-cluster-1
    regione: us-east1
  • Topologia di rete
    File allegato network-topology.png.
Il debug non funziona su Apigee ibrido.

Artefatti utili

Fornendoci elementi relativi al problema velocizza la risoluzione, aiutandoci a comprendere il comportamento esatto che stai osservando e a ottenere maggiori informazioni al riguardo.

Questa sezione descrive alcuni artefatti utili per tutti i prodotti Apigee:

Artefatti comuni per tutti i prodotti Apigee

I seguenti artefatti sono utili per tutti i prodotti Apigee: Apigee su Google Cloud e Apigee hybrid:

Artefatto Descrizione
Output dello strumento di debug L'output dello strumento di debug contiene informazioni dettagliate sulle richieste API che passano attraverso i prodotti Apigee. Questo è utile per eventuali errori di runtime come 4XX, 5XX e problemi di latenza.
Screenshot Gli screenshot aiutano a descrivere il contesto del comportamento o dell'errore effettivamente osservato. È utile per eventuali errori o problemi osservati, ad esempio nell'interfaccia utente o in Analytics.
HAR (ARchive HTTP) HAR è un file acquisito dagli strumenti di sessione HTTP per eseguire il debug di eventuali problemi relativi all'interfaccia utente. Questi dati possono essere acquisiti utilizzando browser come Chrome, Firefox o Internet Explorer.
tcpdumps Lo strumento tcpdump acquisisce i pacchetti TCP/IP trasferiti o ricevuti sulla rete. Questo è utile per qualsiasi problema relativo alla rete come errori di handshake TLS, errori 502, problemi di latenza e così via.

Artefatti aggiuntivi per gli ambienti ibridi

Per il modello ibrido, potremmo aver bisogno di altri artefatti per diagnosticare più rapidamente i problemi.

Artefatto Descrizione
Piattaforma ibrida Apigee Specifica una delle seguenti piattaforme ibride supportate che vengono utilizzate:
  • GKE
  • GKE On-Prem
  • AKS (servizio Kubernetes di Azure)
  • Amazon EKS
  • GKE su AWS
Versioni ibride e dei componenti dipendenti Apigee
  • Versione dell'interfaccia a riga di comando ibrida Apigee: versione
    apigeectl
  • Versione dell'agente Apigee Connect:
    kubectl -n=apigee get pods -l app=apigee-connect-agent -o=json | jq '.items[].spec.containers[].image'
  • Versione Apigee MART:
    kubectl -n=apigee get pods -l app=apigee-mart -o=json | jq '.items[].spec.containers[].image'
  • Versione del sincronizzatore Apigee:
    kubectl -n=apigee get pods -l app=apigee-synchronizer -o=json | jq '.items[].spec.containers[].image'
  • Versione Apigee Cassandra:
    kubectl -n=apigee get pods -l app=apigee-cassandra -o=json | jq '.items[].spec.containers[].image'
  • Versione del runtime Apigee:
    kubectl -n=apigee get pods -l app=apigee-runtime -o=json | jq '.items[].spec.containers[].image'
  • Versioni dell'interfaccia a riga di comando e del server di Kubernetes: versione
    kubectl
  • L'interfaccia a riga di comando e le versioni server di Istio: versione
    istioctl
Topologia di rete Il diagramma della topologia di installazione di Apigee che descrive la tua configurazione ibrida, inclusi tutti i data center, i cluster, gli spazi dei nomi e i pod Kubernetes.
Esegue l'override del file YAML Il file overrides.yaml utilizzato in ogni data center per l'installazione del piano di runtime ibrido Apigee.
Stato del deployment ibrido Apigee

L'output dei comandi seguenti in ogni data center/cluster Kubernetes:

kubectl get pods -A
kubectl get services -A
Log dei componenti ibridi Apigee

Fornisci link ai log di StackDriver per i componenti ibridi OPPURE

Puoi recuperare i log dei componenti ibridi di Apigee utilizzando i seguenti comandi in ogni data center/cluster Kubernetes e condividerli con noi:

kubectl -n {namespace} get pods
kubectl -n {namespace} logs {pod-name}

  • Log dell'agente Apigee Connect:
    kubectl -n {namespace} get pods
    kubectl -n {namespace} logs {apigee-connect-agent-pod-name}
  • Log MART:
    kubectl -n {namespace} get pods
    kubectl -n {namespace} logs {apigee-mart-pod-name}
  • Log del sincronizzatore:
    kubectl -n {namespace} get pods
    kubectl -n {namespace} logs {synchronizer-pod-name}
  • Log di Apigee Cassandra:
    kubectl -n {namespace} get pods
    kubectl -n {namespace} logs {apigee-cassandra-pod-name}
  • Log di runtime MP/Apigee (di tutti i pod apigee-runtime):
    kubectl -n {namespace} get pods
    kubectl -n {namespace} logs {apigee-runtime-pod-name}
Descrivi i log

Informazioni dettagliate sul pod.

Questo è utile, soprattutto se stai riscontrando problemi come un pod che si blocca nello stato CrashLoopBackoff.

kubectl -n apigee describe pod {pod-name}
Cloud Monitoring
  • Link alla dashboard delle metriche
  • Snapshot di qualsiasi dashboard relativa alle metriche di Cloud Monitoring.

Modelli e richieste di esempio

Questa sezione fornisce modelli di richieste e casi di esempio per prodotti diversi in base alle best practice descritte in questo documento:

Apigee Cloud

Modello

Questa sezione fornisce un modello di esempio per Apigee su Google Cloud.

Problema:

<Fornisci una descrizione dettagliata del problema o del comportamento osservato da parte tua. Se possibile, includi il nome e la versione del prodotto.>

Messaggio di errore:

<Includi il messaggio di errore completo osservato (se presente)>

Ora di inizio del problema (formato ISO 8601):

Ora di fine del problema (formato ISO 8601):

Dettagli di configurazione Apigee:
Nomi organizzazioni:
Nomi di ambiente:
Nomi proxy API:
Numeri di revisione:

Passaggi per la riproduzione:

<Fornisci i passaggi per riprodurre il problema, ove possibile>

Informazioni diagnostiche:

<Elenco dei file allegati>

Caso di esempio

Questa sezione fornisce un caso di esempio per Apigee su Google Cloud.

Problema:

Stiamo riscontrando un numero elevato di errori di servizio 503 non disponibile nella nostra organizzazione cloud pubblico. Puoi esaminare il problema e risolverlo o darci indicazioni su come risolverlo?

Messaggio di errore:

{"fault":{"faultstring":"The Service is temporarily available", "detail":{"errorcode":"messaging.adaptors.http.flow.ServiceUnavailable"}}}

Ora di inizio del problema (formato ISO 8601): 04-10-2020 06:30 IST

Ora di fine del problema (formato ISO 8601): il problema persiste.

Dettagli di configurazione di Apigee Cloud:
Nomi delle organizzazioni: myorg
Nomi degli ambienti: dev
Nomi dei proxy API: myproxy
Numeri di revisione: 3

Passaggi per la riproduzione:

Esegui questo comando curl per riprodurre il problema:

curl -X GET 'https://myorg-dev.apigee.net/v1/myproxy'

Informazioni diagnostiche:

Output strumento di debug (trace-503.xml)

Ibrido

Modello

Questa sezione fornisce un modello di esempio per Apigee hybrid.

Problema:

<Fornisci una descrizione dettagliata del problema o del comportamento osservato da parte tua. Se possibile, includi il nome e la versione del prodotto.>

Messaggio di errore:

<Includi il messaggio di errore completo osservato (se presente)>

Ora di inizio del problema (formato ISO 8601):

Ora di fine del problema (formato ISO 8601):

Dettagli sulla configurazione ibrida di Apigee:

  • Piattaforma ibrida Apigee:

    <Fornisci le informazioni sulla piattaforma in cui hai installato l'ambiente ibrido e la relativa versione.>

  • Progetto Google Cloud, organizzazione e ambiente ibridi:
    ID progetto Google Cloud:
    <Se utilizzi Google Kubernetes Engine (GKE), assicurati di fornire l'ID progetto nella posizione in cui si trovano i cluster. Se utilizzi GKE on-prem, Azure Kubernetes Service o Amazon EKS, fornisci l'ID progetto a cui invii i log.>
    Organizzazione ibrida Apigee:
    ambiente ibrido Apigee:
  • Versioni dell'interfaccia a riga di comando ibrida Apigee e altre versioni dell'interfaccia a riga di comando:
    versione dell'interfaccia a riga di comando ibrida Apigee (apigeectl):
    versione Kubectl:
  • Dettagli del nome del cluster Kubernetes:
    k8sCluster:
    nome:
    regione:
  • Topologia di rete:
    <Collega la topologia di rete che descrive la configurazione del tuo ibrido Apigee, inclusi data center, cluster Kubernetes, spazi dei nomi e pod.>
  • Override del file YAML:
    <Allega il file YAML di override.>

Passaggi per la riproduzione

<Fornisci i passaggi per riprodurre il problema, ove possibile>

Informazioni diagnostiche:

<Elenco dei file allegati>

Caso di esempio

Questa sezione fornisce un caso di esempio per Apigee hybrid.

Problema:

Riceviamo errori durante l'esecuzione delle API di gestione su Apigee ibrido versione 1.3.

Messaggio di errore:

[ERROR] 400 Bad Request
{
"error": {
"code": 400,
"message": "Error processing MART request: INTERNAL_ERROR",
"errors": [
{
"message": "Error processing MART request: INTERNAL_ERROR",
"domain": "global",
"reason": "failedPrecondition"
}
],
"status": "FAILED_PRECONDITION"
}
}

Ora di inizio del problema (formato ISO 8601): dalle 24/10/2020 alle 10:30 PDT

Ora di fine del problema (formato ISO 8601): si continuano a osservare il problema.

Dettagli sulla configurazione ibrida di Apigee:

  • Piattaforma ibrida Apigee
    GKE versione 1.15.1
  • Progetto Google Cloud, organizzazione e ambiente ibridi
    ID progetto Google Cloud: apigee-hybrid-123456
      Nota:questo è l'ID progetto in cui si trovano i cluster.
    Organizzazione ibrida Apigee: apigee-hybrid-123456
    ambiente ibrido Apigee: dev
  • Versioni dell'interfaccia a riga di comando ibrida Apigee e altre versioni dell'interfaccia a riga di comando:
    Versione dell'interfaccia a riga di comando ibrida Apigee (apigeectl):
    Versione: 1.2.0
    Commit: ac09109
    ID build: 214
    Tempo di creazione: 2020-03-30T20:23:36Z
    Versione Go: go1.12

    Versione client:
    Versione client: 
    version.Info{Major:"1", Minor:"15", GitVersion:"v1.15.0", GitCommit:"e8462b5b5dc2584fdcd18e6bcfe9f1e4d970a529", GitTreeState:"clean", BuildDate:"2019-06-19T16:40:16Z", GoVersion:"go1.12.5", Compiler:"gc", Platform:"darwin/amd64"}

    version.Info{Major:"1", Minor:"14+", GitVersion:"v1.14.10-gke.36", GitCommit:"34a615f32e9a0c9e97cdb9f749adb392758349a6", GitTreeState:"clean",
  • Dettagli del nome del cluster Kubernetes:
    k8sCluster:
    nome: user-cluster-1
    regione: us-east1
  • Topologia di rete
    File allegato network-topology.png
  • Esegui l'override del file YAML
    È allegato il file overrides.yaml

Passaggi per la riproduzione:

Esegui la seguente API di gestione per osservare l'errore:

curl -X GET --header "Authorization: Bearer <TOKEN>" "https://apigee.googleapis.com/v1/organizations/apigee-hybrid-123456/environments/dev/keyvaluemaps"

Informazioni diagnostiche:

Abbiamo allegato i seguenti file:

  • network-topology.png
  • overrides.yaml file
  • Log di MART
  • Log del sincronizzatore