Observabilité avec les applications gRPC sans proxy

Les outils d'observabilité des microservices vous permettent d'instrumenter vos applications pour collecter et présenter des données de télémétrie dans Cloud Monitoring, Cloud Logging et Cloud Trace à partir de charges de travail gRPC déployées sur Google Cloud, y compris les charges de travail gRPC dans Traffic Director.

Les clients et serveurs gRPC sont intégrés à OpenCensus pour exporter les métriques et les traces vers différents backends, y compris Trace et Monitoring. Pour ce faire, utilisez les langages gRPC suivants:

  • C++
  • Go
  • Java

Lisez la présentation de l'observabilité des microservices, puis utilisez les instructions de la section Configurer l'observabilité des microservices pour instrumenter vos charges de travail gRPC pour les opérations suivantes:

Suivez les instructions de ce document pour effectuer les tâches suivantes:

Afficher les traces sur Trace

Une fois le processus de configuration terminé, les clients et serveurs gRPC instrumentés envoient des traces à Trace. La page Présentation des traces de la console Google Cloud affiche la liste des traces récentes. Vous pouvez sélectionner une trace individuelle pour afficher une répartition de votre trafic, conformément à ce qui est décrit dans la section suivante.

Compatibilité de Trace avec le proxy Envoy

L'exportation de traces vers Trace avec Traffic Director et le proxy Envoy, comme décrit dans la section Observabilité avec Envoy, utilise la configuration du traceur OpenCensus d'Envoy, ce qui permet aux traces exportées à partir d'applications gRPC sans proxy et de proxys Envoy d'être totalement compatibles au sein d'un maillage de services. Pour assurer la compatibilité avec gRPC sans proxy, l'amorçage d'Envoy doit configurer le contexte de trace afin d'inclure le format de trace GRPC_TRACE_BIN dans son fichier OpenCensusConfig. Exemple :

tracing:
  http:
      name: envoy.tracers.opencensus
      typed_config:
        "@type": type.googleapis.com/envoy.config.trace.v2.OpenCensusConfig
        stackdriver_exporter_enabled: "true"
        stackdriver_project_id: "PROJECT_ID"
        incoming_trace_context: ["CLOUD_TRACE_CONTEXT", "GRPC_TRACE_BIN"]
        outgoing_trace_context: ["CLOUD_TRACE_CONTEXT", "GRPC_TRACE_BIN"]

Exposer l'interface d'administration

Parfois, les métriques et les données de traçage ne sont pas suffisantes pour résoudre un problème. Vous devrez peut-être examiner la configuration ou l'état d'exécution de la bibliothèque gRPC dans votre application. Ces informations incluent les informations sur le résolveur, l'état de la connectivité aux pairs, les statistiques RPC sur un canal et la configuration reçue de Traffic Director.

Pour obtenir ces informations, les applications gRPC peuvent exposer l'interface d'administration sur un port particulier. Vous pouvez ensuite interroger l'application pour comprendre la configuration des services et leur exécution. Dans cette section, vous trouverez des instructions sur la configuration de l'interface d'administration pour les applications écrites dans chacun des langages compatibles.

Dans votre application, nous vous recommandons de créer un serveur gRPC distinct qui écoute sur un port réservé à cette fin. Cela vous permet d'accéder à vos applications gRPC même lorsque les ports de données sont inaccessibles en raison d'un problème de configuration ou de problèmes de réseau. Nous vous recommandons d'exposer l'interface d'administration uniquement sur localhost ou sur un socket de domaine Unix.

Les extraits de code suivants montrent comment créer une interface d'administration.

C++

En C++, utilisez le code suivant pour créer une interface d'administration :

#include <grpcpp/ext/admin_services.h>

grpc::ServerBuilder builder;
grpc::AddAdminServices(&builder);
builder.AddListeningPort(":50051", grpc::ServerCredentials(...));
std::unique_ptr<grpc::Server> server(builder.BuildAndStart());

Go

En Go, utilisez le code suivant pour créer une interface d'administration :

import "google.golang.org/grpc/admin"

lis, err := net.Listen("tcp", ":50051")
if err != nil {
        log.Fatalf("failed to listen: %v", err)
}
defer lis.Close()
grpcServer := grpc.NewServer(...opts)
cleanup, err := admin.Register(grpcServer)
if err != nil {
        log.Fatalf("failed to register admin services: %v", err)
}
defer cleanup()

if err := grpcServer.Serve(lis); err != nil {
        log.Fatalf("failed to serve: %v", err)
}

Java

En Java, utilisez le code suivant pour créer une interface d'administration :

import io.grpc.services.AdminInterface;

server = ServerBuilder.forPort(50051)
        .useTransportSecurity(certChainFile, privateKeyFile)
        .addServices(AdminInterface.getStandardServices())
        .build()
        .start();
server.awaitTermination();

Python

En Python, utilisez le code suivant pour créer une interface d'administration :

import grpc_admin

server = grpc.server(futures.ThreadPoolExecutor())
grpc_admin.add_admin_servicers(server)
server.add_insecure_port('[::]:50051')
server.start()
server.wait_for_termination()

Se connecter à une VM via SSH

L'exemple de portefeuille gRPC active déjà l'interface d'administration. Vous pouvez modifier le port de l'interface d'administration en fournissant l'option :

 --admin-port=PORT

Le port d'administration par défaut est localhost:28881.

Pour déboguer votre application gRPC, vous pouvez utiliser SSH pour vous connecter à l'une des VM qui diffuse le wallet-service. Vous pouvez ainsi accéder à localhost.

# List the Wallet VMs
$ gcloud compute instances list --filter="zone:(us-central1-a)" --filter="name~'grpcwallet-wallet-v2'"
NAME                                       ZONE            MACHINE_TYPE   PREEMPTIBLE  INTERNAL_IP    EXTERNAL_IP     STATUS
grpcwallet-wallet-v2-mig-us-central1-ccl1  us-central1-a   n1-standard-1               10.240.0.38    35.223.42.98    RUNNING
grpcwallet-wallet-v2-mig-us-central1-k623  us-central1-a   n1-standard-1               10.240.0.112   35.188.133.75   RUNNING
# Pick one of the Wallet VMs to debug
$ gcloud compute ssh grpcwallet-wallet-v2-mig-us-central1-ccl1 --zone=us-central1-a

Installez l'outil grpcdebug

Pour accéder à l'interface d'administration, vous avez besoin d'un client gRPC capable de communiquer avec les services d'administration de l'application gRPC. Dans les exemples suivants, vous utilisez un outil nommé grpcdebug, que vous pouvez télécharger et installer sur la VM ou sur le pod exécutant votre application gRPC. Le dépôt de grpcdebug se trouve à l'emplacement grpc-ecosystem/grpcdebug.

La version minimale compatible de Golang est la version 1.12. Le guide d'installation officiel de Golang est disponible sur le site de Golang. Si vous suivez le guide de création d'une VM Linux pour wallet-service, vous pouvez installer Golang 1.16 à l'aide des commandes suivantes :

sudo apt update && sudo apt install -y wget
wget https://golang.org/dl/go1.16.3.linux-amd64.tar.gz
sudo rm -rf /usr/local/go
sudo tar -C /usr/local -xzf go1.16.3.linux-amd64.tar.gz
export PATH=$PATH:/usr/local/go/bin
sudo ln -sf /usr/local/go/bin/go /usr/bin/go
go version
# go version go1.16.3 linux/amd64

Pour installer l'outil grpcdebug, exécutez les commandes suivantes :

go install -v github.com/grpc-ecosystem/grpcdebug@latest
export PATH=$PATH:$(go env GOPATH)/bin

Vous avez maintenant accès à l'interface de ligne de commande grpcdebug. L'aide contient des informations sur les commandes compatibles :

$ grpcdebug -h
grpcdebug is a gRPC service admin command-line interface

Usage:
  grpcdebug <target address> [flags]  <command>

Available Commands:
  channelz    Display gRPC states in human readable way.
  health      Check health status of the target service (default "").
  help        Help about any command
  xds         Fetch xDS related information.

Flags:
      --credential_file string        Sets the path of the credential file; used in [tls] mode
  -h, --help                          Help for grpcdebug
      --security string               Defines the type of credentials to use [tls, google-default, insecure] (default "insecure")
      --server_name_override string   Overrides the peer server name if non empty; used in [tls] mode
  -t, --timestamp                     Print timestamp as RFC 3339 instead of human readable strings
  -v, --verbose                       Print verbose information for debugging

Pour obtenir plus d'informations sur une commande particulière, utilisez la commande suivante :

 grpcdebug <target address> [command] --help

Utiliser l'outil grpcdebug pour déboguer vos applications

Vous pouvez utiliser l'outil grpcdebug pour déboguer vos applications. L'outil grpcdebug fournit une configuration de type ssh_config compatible avec l'utilisation d'alias, la réécriture du nom d'hôte et le réglage de la sécurité des connexions (non sécurisé/TLS). Pour en savoir plus sur cette fonctionnalité avancée, consultez la section grpcdebug/Connect&Security.

Les sections suivantes décrivent les services exposés par l'interface d'administration et expliquent comment y accéder.

Utiliser Channelz

Le service Channelz permet d'accéder à des informations d'exécution sur les connexions à différents niveaux de la bibliothèque gRPC de votre application. Vous pouvez l'utiliser pour une analyse en direct des applications présentant des problèmes liés à la configuration ou au réseau. Les exemples suivants supposent que vous avez déployé l'exemple de portefeuille gRPC en suivant les instructions de la section Configurer la gestion avancée du trafic avec des services gRPC sans proxy et en utilisant l'option suivante :

 --admin-port=PORT

Une fois que vous avez envoyé quelques RPC à partir d'un client de test, comme indiqué dans la section Vérifier la configuration, utilisez les commandes suivantes pour accéder aux données Channelz pour les services gRPC :

  1. Utilisez SSH pour vous connecter à une VM qui exécute wallet-service.
  2. Configurez grpcdebug pour vous connecter à l'application gRPC en cours d'exécution.

La sortie par défaut de grpcdebug est dans un format de table compatible avec la console. Si vous spécifiez l'option --json, le résultat est encodé au format JSON.

La commande grpcdebug channelz permet de récupérer et de présenter les informations de débogage provenant du service Channelz. La commande fonctionne à la fois pour les clients gRPC et les serveurs gRPC.

Pour les clients gRPC, la commande grpcdebug channelz channels fournit une liste des canaux existants ainsi que des informations de base :

$ grpcdebug localhost:28881 channelz channels
Channel ID   Target                               State     Calls(Started/Succeeded/Failed)   Created Time
1            xds:///account.grpcwallet.io:10080   READY     0/0/0                             59 seconds ago
2            trafficdirector.googleapis.com:443   READY     2/0/0                             59 seconds ago
4            xds:///stats.grpcwallet.io:10080     READY     0/0/0                             59 seconds ago

Si vous avez besoin d'informations supplémentaires concernant un canal particulier, vous pouvez utiliser grpcdebug channelz channel [CHANNEL_ID] pour inspecter les informations détaillées relatives à ce canal. L'identifiant de canal peut être l'ID de canal ou l'adresse cible, s'il n'existe qu'une seule adresse cible. Un canal gRPC peut contenir plusieurs sous-canaux, ce qui représente l'abstraction de gRPC par-dessus une connexion TCP.

$ grpcdebug localhost:28881 channelz channel 2
Channel ID:        2
Target:            trafficdirector.googleapis.com:443
State:             READY
Calls Started:     2
Calls Succeeded:   0
Calls Failed:      0
Created Time:      10 minutes ago
---
Subchannel ID   Target                               State     Calls(Started/Succeeded/Failed)   CreatedTime
3               trafficdirector.googleapis.com:443   READY     2/0/0                             10 minutes ago
---
Severity   Time             Child Ref                      Description
CT_INFO    10 minutes ago                                  Channel Created
CT_INFO    10 minutes ago                                  parsed scheme: ""
CT_INFO    10 minutes ago                                  scheme "" not registered, fallback to default scheme
CT_INFO    10 minutes ago                                  ccResolverWrapper: sending update to cc: {[{trafficdirector.googleapis.com:443  <nil> 0 <nil>}] <nil> <nil>}
CT_INFO    10 minutes ago                                  Resolver state updated: {Addresses:[{Addr:trafficdirector.googleapis.com:443 ServerName: Attributes:<nil> Type:0 Metadata:<nil>}] ServiceConfig:<nil> Attributes:<nil>} (resolver returned new addresses)
CT_INFO    10 minutes ago                                  ClientConn switching balancer to "pick_first"
CT_INFO    10 minutes ago                                  Channel switches to new LB policy "pick_first"
CT_INFO    10 minutes ago   subchannel(subchannel_id:3 )   Subchannel(id:3) created
CT_INFO    10 minutes ago                                  Channel Connectivity change to CONNECTING
CT_INFO    10 minutes ago                                  Channel Connectivity change to READY

Vous pouvez également consulter les informations détaillées d'un sous-canal :

$ grpcdebug localhost:28881 channelz subchannel 3
Subchannel ID:     3
Target:            trafficdirector.googleapis.com:443
State:             READY
Calls Started:     2
Calls Succeeded:   0
Calls Failed:      0
Created Time:      12 minutes ago
---
Socket ID   Local->Remote                           Streams(Started/Succeeded/Failed)   Messages(Sent/Received)
9           10.240.0.38:60338->142.250.125.95:443   2/0/0                               214/132

Vous pouvez récupérer des informations sur les sockets TCP :

$ grpcdebug localhost:28881 channelz socket 9
Socket ID:                       9
Address:                         10.240.0.38:60338->142.250.125.95:443
Streams Started:                 2
Streams Succeeded:               0
Streams Failed:                  0
Messages Sent:                   226
Messages Received:               141
Keep Alives Sent:                0
Last Local Stream Created:       12 minutes ago
Last Remote Stream Created:      a long while ago
Last Message Sent Created:       8 seconds ago
Last Message Received Created:   8 seconds ago
Local Flow Control Window:       65535
Remote Flow Control Window:      966515
---
Socket Options Name   Value
SO_LINGER             [type.googleapis.com/grpc.channelz.v1.SocketOptionLinger]:{duration:{}}
SO_RCVTIMEO           [type.googleapis.com/grpc.channelz.v1.SocketOptionTimeout]:{duration:{}}
SO_SNDTIMEO           [type.googleapis.com/grpc.channelz.v1.SocketOptionTimeout]:{duration:{}}
TCP_INFO              [type.googleapis.com/grpc.channelz.v1.SocketOptionTcpInfo]:{tcpi_state:1  tcpi_options:7  tcpi_rto:204000  tcpi_ato:40000  tcpi_snd_mss:1408  tcpi_rcv_mss:1408  tcpi_last_data_sent:8212  tcpi_last_data_recv:8212  tcpi_last_ack_recv:8212  tcpi_pmtu:1460  tcpi_rcv_ssthresh:88288  tcpi_rtt:2400  tcpi_rttvar:3012  tcpi_snd_ssthresh:2147483647  tcpi_snd_cwnd:10  tcpi_advmss:1408  tcpi_reordering:3}
---
Security Model:   TLS
Standard Name:    TLS_AES_128_GCM_SHA256

Du côté serveur, vous pouvez utiliser Channelz pour inspecter l'état de votre application serveur. Par exemple, vous pouvez obtenir la liste des serveurs à l'aide de la commande grpcdebug channelz servers :

$ grpcdebug localhost:28881 channelz servers
Server ID   Listen Addresses    Calls(Started/Succeeded/Failed)   Last Call Started
5           [127.0.0.1:28881]   9/8/0                             now
6           [[::]:50051]        159/159/0                         4 seconds ago

Pour obtenir plus d'informations sur un serveur spécifique, utilisez la commande grpcdebug channelz server. Vous pouvez inspecter les sockets serveur de la même manière que vous inspectez les sockets client.

$ grpcdebug localhost:28881 channelz server 6
Server Id:           6
Listen Addresses:    [[::]:50051]
Calls Started:       174
Calls Succeeded:     174
Calls Failed:        0
Last Call Started:   now
---
Socket ID   Local->Remote                            Streams(Started/Succeeded/Failed)   Messages(Sent/Received)
25          10.240.0.38:50051->130.211.1.39:44904    68/68/0                             68/68
26          10.240.0.38:50051->130.211.0.167:32768   54/54/0                             54/54
27          10.240.0.38:50051->130.211.0.22:32768    52/52/0                             52/52

Utiliser le Client Status Discovery Service

L'API Client Status Discovery Service (CSDS) fait partie des API xDS. Dans une application gRPC, le service CSDS fournit l'accès à la configuration (également appelée configuration xDS) qu'il reçoit de Traffic Director. Cela vous permet d'identifier et de résoudre les problèmes liés à la configuration de votre maillage.

Dans les exemples suivants, nous partons du principe que vous avez déployé l'exemple de portefeuille gRPC en suivant les instructions de la section Configurer la gestion avancée du trafic avec des services gRPC sans proxy.

Pour examiner la configuration à l'aide de CSDS, procédez comme suit :

  1. Utilisez SSH pour vous connecter à une VM qui exécute wallet-service. Suivez les instructions de la section Se connecter à une VM via SSH.
  2. Exécutez le client grpcdebug.

Pour obtenir une vue d'ensemble de l'état de la configuration, exécutez la commande suivante :

grpcdebug localhost:28881 xds status

Un résultat semblable aux lignes suivantes doit s'afficher :

Name                                                                    Status    Version               Type                                                                 LastUpdated
account.grpcwallet.io:10080                                             ACKED     1618529574783547920   type.googleapis.com/envoy.config.listener.v3.Listener                3 seconds ago
stats.grpcwallet.io:10080                                               ACKED     1618529574783547920   type.googleapis.com/envoy.config.listener.v3.Listener                3 seconds ago
URL_MAP/830293263384_grpcwallet-url-map_0_account.grpcwallet.io:10080   ACKED     1618529574783547920   type.googleapis.com/envoy.config.route.v3.RouteConfiguration         3 seconds ago
URL_MAP/830293263384_grpcwallet-url-map_1_stats.grpcwallet.io:10080     ACKED     1618529574783547920   type.googleapis.com/envoy.config.route.v3.RouteConfiguration         3 seconds ago
cloud-internal-istio:cloud_mp_830293263384_3566964729007423588          ACKED     1618529574783547920   type.googleapis.com/envoy.config.cluster.v3.Cluster                  3 seconds ago
cloud-internal-istio:cloud_mp_830293263384_7383783194368524341          ACKED     1618529574783547920   type.googleapis.com/envoy.config.cluster.v3.Cluster                  3 seconds ago
cloud-internal-istio:cloud_mp_830293263384_3363366193797120473          ACKED     1618529574783547920   type.googleapis.com/envoy.config.cluster.v3.Cluster                  3 seconds ago
cloud-internal-istio:cloud_mp_830293263384_3566964729007423588          ACKED     86                    type.googleapis.com/envoy.config.endpoint.v3.ClusterLoadAssignment   2 seconds ago
cloud-internal-istio:cloud_mp_830293263384_3363366193797120473          ACKED     86                    type.googleapis.com/envoy.config.endpoint.v3.ClusterLoadAssignment   2 seconds ago
cloud-internal-istio:cloud_mp_830293263384_7383783194368524341          ACKED     86                    type.googleapis.com/envoy.config.endpoint.v3.ClusterLoadAssignment   2 seconds ago

Vous pouvez trouver la définition de l'état de la configuration dans la documentation du proxy Envoy. En bref, l'état d'une ressource xDS est décrit par l'un des éléments suivants : REQUESTED, DOES_NOT_EXIST, ACKED ou NACKED.

Pour obtenir un vidage de configuration xDS brut, exécutez la commande suivante :

grpcdebug localhost:28881 xds config

Une liste JSON de l'objet PerXdsConfig s'affiche:

{
  "config":  [
    {
      "node":  {
        "id":  "projects/830293263384/networks/default/nodes/6e98b038-6d75-4a4c-8d35-b0c7a8c9cdde",
        "cluster":  "cluster",
        "metadata":  {
          "INSTANCE_IP":  "10.240.0.38",
          "TRAFFICDIRECTOR_GCP_PROJECT_NUMBER":  "830293263384",
          "TRAFFICDIRECTOR_NETWORK_NAME":  "default"
        },
        "locality":  {
          "zone":  "us-central1-a"
        },
        "userAgentName":  "gRPC Go",
        "userAgentVersion":  "1.37.0",
        "clientFeatures":  [
          "envoy.lb.does_not_support_overprovisioning"
        ]
      },
      "xdsConfig":  [
        {
          "listenerConfig":  {
            "versionInfo":  "1618529930989701137",
            "dynamicListeners":  [
              {
...

Si la sortie de configuration brute est trop détaillée, grpcdebug vous permet de filtrer en fonction de types xDS spécifiques. Exemple :

$ grpcdebug localhost:28881 xds config --type=cds
{
  "versionInfo":  "1618530076226619310",
  "dynamicActiveClusters":  [
    {
      "versionInfo":  "1618530076226619310",
      "cluster":  {
        "@type":  "type.googleapis.com/envoy.config.cluster.v3.Cluster",
        "name":  "cloud-internal-istio:cloud_mp_830293263384_7383783194368524341",
        "altStatName":  "/projects/830293263384/global/backendServices/grpcwallet-stats-service",
        "type":  "EDS",
        "edsClusterConfig":  {
          "edsConfig":  {
            "ads":  {},
            "initialFetchTimeout":  "15s",
...

Vous pouvez également obtenir le vidage de plusieurs types xDS à la fois :

$ grpcdebug localhost:28881 xds config --type=lds,eds
{
  "versionInfo":  "1618530076226619310",
  "dynamicListeners":  [...]
}
{
  "dynamicEndpointConfigs":  [...]
}

Étapes suivantes