Informations de référence sur l'observabilité des microservices

Données de configuration

Les données de configuration que l'on retrouve dans les variables d'environnement sont définies dans le tableau suivant.

Fields Spécification
project_id Chaîne

Identifiant du projet auquel les données d'observabilité sont envoyées. Si ce champ est vide, le plug-in d'observabilité gRPC tente de récupérer l'ID du projet à partir des variables d'environnement ou des identifiants par défaut.

Si aucune fonction init d'observabilité n'est trouvée, l'erreur est renvoyée.
cloud_logging Objet

Les options de journalisation sont classées dans ce tableau.
En cas d'absence, la journalisation est désactivée.
cloud_logging.client_rpc_events[] Liste

Liste des configurations client_rpc_events, qui représente la configuration des RPC sortants du binaire.

Les configurations client_rpc_events sont évaluées dans l'ordre du texte. La première correspondance est utilisée. Si un RPC ne correspond à aucune entrée, l'évaluation passe à l'entrée suivante dans la liste.
cloud_logging.client_rpc_events[].methods[] Liste [Chaîne]

Liste d'identifiants de méthode.

Par défaut, la liste est vide et ne correspond à aucune méthode.

La valeur de la méthode est au format [service]/[method].

* est accepté comme caractère générique pour :
  • Nom de la méthode. Si la valeur est [service]/*, elle correspond à toutes les méthodes du service spécifié.
  • Valeur entière du champ correspondant à n'importe quel [service]/[method]. Il n'est pas accepté lorsque client_rpc_events[].exclude est défini sur "true".
  • Le caractère générique * ne peut pas être utilisé sur le nom du service de manière indépendante, */[method] n'est pas accepté.

Si spécifié, le nom du service doit être le nom complet du service, y compris le nom du package.

Exemples :
  • goo.Foo/Bar sélectionne uniquement la méthode Bar du service goo.Foo. Ici, goo est le nom du package.
  • goo.Foo/* sélectionne toutes les méthodes du service goo.Foo.
  • * sélectionne toutes les méthodes de tous les services.
cloud_logging.client_rpc_events[].exclude Bool

Indique si les méthodes désignées par client_rpc_events[].methods[] doivent être exclues de la journalisation.

La valeur par défaut est "false", ce qui signifie que les méthodes indiquées par client_rpc_events[].methods[] sont incluses dans l'enregistrement de journal.

Si la valeur est "true", le caractère générique (*) ne peut pas être utilisé comme valeur entière dans client_rpc_events[].methods[]..
cloud_logging.client_rpc_events[].max_metadata_bytes Int

Nombre maximal d'octets de métadonnées à consigner. Si la taille des métadonnées est supérieure à la limite définie, les paires clé/valeur au-delà de la limite ne sont pas consignées.

La valeur par défaut est 0, ce qui signifie qu'aucune métadonnée n'est enregistrée.
cloud_logging.client_rpc_events[].max_message_bytes Int

Nombre maximal d'octets de chaque message à consigner. Si la taille du message est supérieure à la limite définie, le contenu qui dépasse cette limite est tronqué.

La valeur par défaut est 0, ce qui signifie qu'aucune charge utile de message n'est consignée.
cloud_logging.server_rpc_events[] Liste

Liste des configurations server_rpc_events, qui représente la configuration des RPC entrants dans le binaire.

Les configurations server_rpc_events sont évaluées dans l'ordre du texte. La première correspondance est utilisée. Si un RPC ne correspond à aucune entrée, il passe à l'entrée

suivante dans la liste.
cloud_logging.server_rpc_events[].methods[] Répertorier [String]

Liste de chaînes pouvant sélectionner un groupe de méthodes.

Par défaut, la liste est vide et ne correspond à aucune méthode.

La valeur de la méthode est au format [service]/[method].

* est accepté comme caractère générique pour :
  • Nom de la méthode. Si la valeur est [service]/*, elle correspond à toutes les méthodes du service spécifié.
  • Valeur entière de la méthode correspondant à n'importe quel [service]/[method]. Il n'est pas compatible lorsque la valeur de server_rpc_events[].exclude est "true".
  • Le caractère générique * ne peut pas être utilisé sur le nom du service de manière indépendante, */[method] n'est pas accepté.

Si spécifié, le nom du service doit être le nom complet du service, y compris le nom du package.

Exemples :
  • goo.Foo/Bar sélectionne uniquement la méthode Bar du service goo.Foo. Ici, goo est le nom du package.
  • goo.Foo/* sélectionne toutes les méthodes du service goo.Foo.
  • * sélectionne toutes les méthodes de tous les services.
cloud_logging.server_rpc_events[].exclude Bool

Indique si les méthodes désignées par server_rpc_events[].methods[] doivent être exclues de la journalisation.

La valeur par défaut est "false", ce qui signifie que les méthodes indiquées par server_rpc_events[].methods[] sont consignées.

Si la valeur est "true", le caractère générique (*) ne peut être utilisé comme valeur entière dans une entrée de server_rpc_events[].methods[].
cloud_logging.server_rpc_events[].max_metadata_bytes Int

Nombre maximal d'octets de métadonnées à consigner. Si la taille des métadonnées est supérieure à la limite définie, les paires clé/valeur au-delà de la limite ne sont pas consignées.

La valeur par défaut est 0, ce qui signifie qu'aucune métadonnée n'est enregistrée.
cloud_logging.server_rpc_events[].max_message_bytes Int

Nombre maximal d'octets de chaque message à consigner. Si la taille du message est supérieure à la limite définie, le contenu qui dépasse cette limite est tronqué.

La valeur par défaut est 0, ce qui signifie qu'aucune charge utile de message n'est consignée.
cloud_monitoring Objet

Active Cloud Monitoring. Il n'y a aucune option de configuration. Si vous envoyez une objection de configuration vide, la surveillance est activée. Si vous ne fournissez pas d'objet de configuration, la surveillance est désactivée.

Par exemple, si aucune autre option n'est spécifiée, une section de configuration vide active la surveillance.
export GRPC_GCP_OBSERVABILITY_CONFIG='{
    "project_id": "your-project-here",
    "cloud_monitoring": {
    }
}'
cloud_trace Objet

Une section de configuration vide active le traçage avec les options de configuration par défaut. Si vous ne fournissez pas d'objet de configuration, le traçage est désactivé.

Par exemple, une section de configuration vide active le traçage avec les options de configuration par défaut.
export GRPC_GCP_OBSERVABILITY_CONFIG='{
    "project_id": "your-project-here",
    "cloud_trace": {
    }
}'


Lorsque le traçage est activé, même avec un taux d'échantillonnage de "0", la décision d'échantillonner une trace particulière est propagée.
cloud_trace.sampling_rate Nombre

Paramètre global qui contrôle la probabilité d'une trace RPC. Exemple :
  • La valeur 0.05 signifie qu'il y a 5 % de chances qu'un RPC soit tracé.
  • La valeur 1.0 signifie que chaque appel est tracé.
  • La valeur 0 signifie que ne pas démarrer de nouvelles traces.

Par défaut, le sampling_rate (taux d'échantillonnage) est 0.

Le plug-in respecte la décision d'échantillonnage en amont. Si un RPC est choisi pour l'échantillonnage en amont, le plug-in collecte les délais et importe les données dans le backend, quel que soit le paramètre de taux d'échantillonnage du plug-in.
labels Objet

Objet JSON contenant un ensemble de paires clé/valeur. La clé et la valeur sont des chaînes.

Les étiquettes sont appliquées ensemble sur Cloud Logging, Cloud Monitoring et Cloud Trace.

Définitions de trace

Cette section fournit des informations sur le traçage.

Propagation du contexte de trace

Pour que le traçage interservice fonctionne, le propriétaire du service doit permettre la propagation du contexte de trace reçu en amont (ou démarré seul) en aval. Le contexte de trace est propagé entre les services via des métadonnées gRPC. Veillez à activer les API Monitoring, Cloud Logging, Cloud Trace et Microservices, qui permettent aux services de cette configuration de signaler leurs données de télémétrie au service approprié.

Sans compatibilité avec la propagation, les services en aval ne peuvent pas générer de délais pour une trace. Les délais existants ne sont pas affectés. Les plug-ins d'observabilité des microservices sont compatibles avec le format binaire OpenCensus pour l'encodage et le contexte de trace d'encodage.

Segments

Le nom d'un délai est au format suivant :

Type Exemple de valeur Utilisation
Délai RPC [Sent|Recv].helloworld.Greeter.SayHello Le nom du délai est le nom complet de la méthode, relié par des points, sans barre oblique.
Les noms de délai sont précédés du préfixe Sent. pour le délai RPC CLIENT et du préfixe Recv. pour le délai RPC SERVER devant le nom complet de la méthode.
Délai de tentative Attempt.helloworld.Greeter.SayHello Associer un préfixe Attempt. devant le nom complet de la méthode.

Libellés de délais

Les intégrations fournissent différents libellés de délais.

Pour les délais de tentative, deux attributs supplémentaires liés aux nouvelles tentatives (libellés de délai) sont associés :

Libellé Exemple de valeur Utilisation
previous-rpc-attempts 0 Les nouvelles tentatives sont comptabilisées avant ce RPC.
transparent-retry True/False Indique si ce RPC est lancé par une nouvelle tentative transparente.

Définitions des métriques

Les métriques suivantes sont disponibles et s'affichent dans un tableau de bord nommé Microservices (gRPC) Monitoring pour les parcours utilisateur courants :

Voici les métriques gRPC côté client :

Nom de la métrique Description Genre, type, unité Libellés
custom.googleapis.com/opencensus/grpc.io/client/started_rpcs Nombre de tentatives de RPC client lancées, y compris celles qui ne sont pas terminées. Cumulé, Int64, 1 grpc_client_method
custom.googleapis.com/opencensus/grpc.io/client/completed_rpcs Nombre de RPC client terminés, par exemple lorsqu'une réponse est reçue ou envoyée par le serveur. Cumulé, Int64, 1 grpc_client_method, grpc_client_status
custom.googleapis.com/opencensus/grpc.io/client/roundtrip_latency Temps de bout en bout nécessaire pour effectuer une tentative RPC, y compris le temps nécessaire pour choisir un sous-canal. Cumulée, Distribution, ms grpc_client_method
custom.googleapis.com/opencensus/grpc.io/client/api_latency Temps total pris par la bibliothèque gRPC pour effectuer un RPC du point de vue de l'application. Cumulé, Distribution, ms grpc_client_method, grpc_client_status
custom.googleapis.com/opencensus/grpc.io/client/sent_compressed_message_bytes_per_rpc Nombre total d'octets (compressés, non chiffrés) envoyés par tous les messages de requête par tentative de RPC. Cumulé, Distribution, Par grpc_client_method, grpc_client_status
custom.googleapis.com/opencensus/grpc.io/client/received_compressed_message_bytes_per_rpc Nombre total d'octets (compressés, non chiffrés) reçus par tous les messages de réponse par tentative de RPC. Cumulé, distribution, par grpc_client_method, grpc_client_status

Les métriques côté serveur gRPC suivantes sont disponibles :

Nom de la métrique Description Genre, type, unité Libellés
custom.googleapis.com/opencensus/grpc.io/server/started_rpcs
Nombre de RPC reçus au serveur, y compris les RPC qui ne sont pas terminés.		 Cumulé, Int64, 1 grpc_server_method
custom.googleapis.com/opencensus/grpc.io/server/completed_rpcs
Nombre total de RPC terminés, par exemple lorsqu'une réponse est envoyée par le serveur.		 Cumulé, Int64, 1 grpc_server_method, grpc_server_status
custom.googleapis.com/opencensus/grpc.io/server/sent_compressed_message_bytes_per_rpc
Nombre total d'octets (compressés, non chiffrés) envoyés par tous les messages de réponse par RPC.		 Cumulé, distribution, par grpc_server_method, grpc_server_status
custom.googleapis.com/opencensus/grpc.io/server/received_compressed_message_bytes_per_rpc
Nombre total d'octets (compressés, non chiffrés) reçus par tous les messages de requête par RPC.		 Cumulé, Distribution, Par grpc_server_method, grpc_server_status
custom.googleapis.com/opencensus/grpc.io/server/server_latency
Temps total pris par un RPC du point de vue du transport de serveur (HTTP2 / inproc / cronet).		 Cumulée, Distribution, ms grpc_server_method

Chaque distribution du tableau ci-dessus contient un histogramme avec des buckets comme suit :

  • Taille en octets : 0, 1024, 2048, 4096, 16384, 65536, 262144, 1048576, 4194304, 16777216, 67108864, 268435456, 1073741824, 4294967296

  • Latence en ms : 0, 0.01, 0.05, 0.1, 0.3, 0.6, 0.8, 1, 2, 3, 4, 5, 6, 8, 10, 13, 16, 20, 25, 30, 40, 50, 65, 80, 100, 130, 160, 200, 250, 300, 400, 500, 650, 800, 1000, 2000, 5000, 10000, 20000, 50000, 100000

Description du tag :

  • grpc_client_method : nom complet de la méthode gRPC, y compris le package, le service et la méthode (par exemple, google.bigtable.v2.Bigtable/CheckAndMutateRow)
  • grpc_client_status : code d'état du serveur gRPC reçu (par exemple, OK, CANCELLED, DEADLINE_EXCEEDED)
  • grpc_server_method : nom complet de la méthode gRPC, y compris le package, le service et la méthode (par exemple, com.exampleapi.v4.BookshelfService/Checkout)
  • grpc_server_status : code d'état du serveur gRPC renvoyé (par exemple, OK, CANCELLED, DEADLINE_EXCEEDED)

Définitions des enregistrements de journal

Les journaux d'observabilité des microservices sont importés dans Cloud Logging avec le nom de journal (PROJECT_ID est l'espace réservé à la chaîne représentant votre projet) :

logName=projects/[PROJECT_ID]/logs/microservices.googleapis.com%2Fobservability%2Fgrpc

Voici la représentation JSON de l'enregistrement de journal généré :

{
    "authority": string,
    "callId": string,
    "type": string,
    "logger": string,
    "serviceName": string,
    "methodName": string,
    "peer": {
        "type": string,
        "address": string,
        "ipPort": int
    },
    "payload": {
        "timeout": string,
        "metadata":
            {
                string: string,
                string: string
            },
        "statusCode": string,
        "statusMessage": string,
        "statusDetails": string,
        "message": string,
        "messageLength": int,
    },
    "sequenceId": int
}

Le tableau suivant décrit les champs de l'entrée de journal :

Fields Spécification
Autorité Chaîne

Un processus unique peut être utilisé pour exécuter plusieurs serveurs virtuels avec des identités différentes.

L'autorité est le nom d'une telle identité de serveur. Il s'agit généralement d'une partie de l'URI sous la forme d'hôte ou de hôte:port.
callId Chaîne

Identifie de manière unique un appel [client/serveur] qui est un UUID. Chaque appel peut contenir plusieurs entrées de journal. Ils ont tous le même ID d'appel.
type Chaîne

Type de l'événement de journal.

Types d'événements :
EVENT_TYPE_UNKNOWN
CLIENT_HEADER
SERVER_HEADER
CLIENT_MESSAGE
SERVER_MESSAGE
CLIENT_HALF_CLOSE
SERVER_TRAILER
CANCEL
logger Chaîne

Type de l'enregistreur d'événements.

Les types de journaux d'événements sont les suivants :
LOGGER_UNKNOWN, CLIENT, SERVER
serviceName Chaîne

Le nom du service.
methodName Chaîne

Nom de la méthode RPC.
pair Object

Informations sur l'adresse du pair. Du côté client, le pair est consigné dans les événements d'en-tête du serveur et les évènements de suivi. Du côté du serveur, le pair est toujours enregistré sur l'événement d'en-tête du client.
peer.type Chaîne

Type d'adresse : IPv4, IPv6 ou UNIX.
peer.address Chaîne

Contenu de l'adresse.
peer.ip_port Int

Numéro de port de l'adresse. Disponible uniquement pour les adresses IPv4 et IPv6.
payload Objet

La charge utile peut inclure une combinaison de métadonnées, de délai avant expiration, de message et d'état en fonction de l'événement.

  • Pour les événements de message, la charge utile est des données réelles transmises en tant que messages client/serveur et la longueur du message.
  • Pour les événements d'en-tête, la charge utile inclut le nom et la valeur de l'en-tête.
  • Pour les événements de trace, la charge utile inclut des détails sur l'état ainsi que les métadonnées de la bande-annonce (le cas échéant).
  • Pour les événements d'en-tête client, si le délai avant expiration est défini, la charge utile inclut également le délai avant expiration.
payload.timeout Chaîne

Chaîne représentant google.protobuf.Duration, telle que "1.2 s".

Valeur du délai RPC.
payload.metadata Mapping[String, String]

Utilisé par l'événement d'en-tête ou l'événement de suivi.
payload.message Chaîne (octets)

Charge utile du message.
payload.messageLength Int

Taille du message, qu'il soit consigné ou non (par exemple, il peut être tronqué ou omis).
payload.statusCode Chaîne

Code d'état gRPC.
payload.statusMessage Chaîne

Message d'état gRPC.
payload.statusDetails Chaîne

Valeur de la clé de métadonnées grpc-status-details-bin, le cas échéant. Il s'agit toujours d'un message google.rpc.Status encodé.
payloadTruncated Bool

Vrai si le champ du message ou des métadonnées est tronqué ou omis en raison des options de configuration.
sequenceId Int

ID de séquence des messages pour cet appel. Le premier message a une valeur de 1, pour lever toute ambiguïté avec une valeur non définie. L'objectif de ce champ est de détecter les entrées manquantes dans les environnements où la durabilité ou l'ordre n'est pas garanti.

Étiquettes de ressource

Les étiquettes de ressources identifient la source qui génère des données d'observabilité. Chaque étiquette de ressource est une paire clé/valeur, où les clés sont des valeurs prédéfinies spécifiques à l'environnement source (par exemple, GKE ou Compute Engine).

Pour les métriques et le traçage sur les déploiements GKE, les étiquettes de ressource sont renseignés par défaut, à l'exception du nom du conteneur et du nom de l'espace de noms. Les valeurs manquantes peuvent être renseignées à l'aide de l'API Downward.

Voici les clés de la variable d'environnement :

  • CONTAINER_NAME
  • NAMESPACE

Par exemple, la section env de la section suivante inclut deux étiquettes de ressource :

apiVersion: apps/v1
kind: Deployment
metadata:
  labels:
    run: app1
  name: app1
spec:
  replicas: 2
  selector:
    matchLabels:
      run: app1
  template:
    metadata:
      labels:
        run: app1
    spec:
      containers:
        - image: 'o11y-examples:1.00'
          name: container1
          ports:
            - protocol: TCP
              containerPort: 50051
          env:
            - name: CONTAINER_NAME
              value: container1
            - name: NAMESPACE
              valueFrom:
                fieldRef:
                  fieldPath: metadata.namespace

Libellés personnalisés

Les étiquettes personnalisées représentent des informations supplémentaires fournies par l'utilisateur dans les données d'observabilité. Les libellés sont constitués d'une clé et d'une valeur. La paire clé/valeur est associée au traçage de données en tant qu'étiquettes de délais, aux données de métriques en tant qu"étiquettes de métriques et aux données de journalisation en tant qu'étiquettes d'entrées de journal. Tous les libellés personnalisés sont de type STRING.

Vous pouvez fournir des étiquettes personnalisées dans la configuration en spécifiant une liste de paires clé/valeur pour labels. La mise en œuvre lit la configuration et crée une étiquette distincte pour chaque paire clé/valeur, puis associe l'étiquette aux données d'observabilité. Exemple :

"labels": {
    "DATACENTER": "SAN_JOSE_DC",
    "APP_ID": "24512"
  }

Chaque entrée de journal contient les libellés supplémentaires suivants :

{
   "DATACENTER": "SAN_JOSE_DC"
   "APP_ID": "24512"
}

Étapes suivantes