Referenzinformationen für die Beobachtbarkeit von Mikrodiensten

Konfigurationsdaten

Die in den Umgebungsvariablen ermittelten Konfigurationsdaten werden in der folgenden Tabelle definiert.

Fields Spezifikation
project_id String

Die Kennzeichnung des Projekts, an das Beobachtbarkeitsdaten gesendet werden. Wenn dieses Feld leer ist, versucht das gRPC-Beobachtbarkeits-Plug-in, die Projekt-ID aus den Umgebungsvariablen oder aus den Standardanmeldedaten abzurufen.

Wenn nicht gefunden, geben die init-Funktionen für die Beobachtbarkeit einen Fehler zurück.
cloud_logging Objekt

Die Logging-Optionen sind in dieser Tabelle kategorisiert.
Wenn er fehlt, ist das Logging deaktiviert.
cloud_logging.client_rpc_events[] Liste

Eine Liste von client_rpc_events-Konfigurationen, die die Konfiguration für ausgehende RPCs von der Binärdatei darstellen.

Die client_rpc_events-Konfigurationen werden in Textreihenfolge ausgewertet. Die erste übereinstimmende Konfiguration wird verwendet. Wenn ein RPC nicht mit einem Eintrag übereinstimmt, wird mit dem nächsten Eintrag in der Liste fortgefahren.
cloud_logging.client_rpc_events[].methods[] Liste [String]

Eine Liste mit Methoden-IDs.

Standardmäßig ist die Liste leer und entspricht keinen Methoden.

Der Wert der Methode hat das Format [service]/[method].

* wird als Platzhalter für Folgendes akzeptiert:
  • Der Methodenname. Wenn der Wert [service]/* ist, entspricht er allen Methoden im angegebenen Dienst.
  • Der gesamte Wert des Felds, das mit einem beliebigen [service]/[method] übereinstimmt. Wird nicht unterstützt, wenn client_rpc_ereignisse[].Exclude wahr ist.
  • Der Platzhalter * kann nicht unabhängig für den Dienstnamen verwendet werden; */[method] wird nicht unterstützt.

Wenn angegeben, muss der Dienstname der vollständig qualifizierte Dienstname sein, einschließlich des Paketnamens.

Beispiele:
  • goo.Foo/Bar wählt nur die Methode Bar des Dienstes goo.Foo aus, wobei goo der Paketname ist.
  • Mit goo.Foo/* werden alle Methoden aus dem Dienst goo.Foo ausgewählt.
  • Mit * werden alle Methoden aus allen Diensten ausgewählt.
cloud_logging.client_rpc_events[].exclude Bool

Gibt an, ob die durch client_rpc_events[].methods[] gekennzeichneten Methoden vom Logging ausgeschlossen werden sollen.

Der Standardwert ist "false". Das bedeutet, dass die durch client_rpc_events[].methods[] angegebenen Methoden im Logeintrag enthalten sind.

Wenn der Wert "true" ist, kann der Platzhalter (*) nicht als der gesamte Wert in client_rpc_events[].methods[]. verwendet werden
cloud_logging.client_rpc_events[].max_metadata_bytes Int

Maximale Anzahl der zu protokollierenden Metadaten in Byte. Wenn die Größe der Metadaten das definierte Limit überschreitet, werden Schlüssel/Wert-Paare jenseits des Limits nicht protokolliert.

Der Standardwert ist 0, d. h., es werden keine Metadaten protokolliert.
cloud_logging.client_rpc_events[].max_message_bytes Int

Maximale Anzahl von Byte jeder zu protokollierenden Nachricht. Wenn die Größe der Nachricht das festgelegte Limit überschreitet, wird der Inhalt jenseits des Limits abgeschnitten.

Der Standardwert ist 0, d. h., es wird keine Nachrichtennutzlast protokolliert.
cloud_logging.server_rpc_events[] Liste

Eine Liste von server_rpc_events-Konfigurationen, steht für die Konfiguration eingehender RPCs an das Binärprogramm.

Die server_rpc_events-Konfigurationen werden in Textreihenfolge ausgewertet. Die erste übereinstimmende Konfiguration wird verwendet. Wenn ein RPC nicht mit einem Eintrag übereinstimmt, wird mit dem nächsten Eintrag in der Liste fortgefahren.
cloud_logging.server_rpc_events[].methods[] Liste [String]

Eine Liste von Strings, die eine Gruppe von Methoden auswählen können.

Standardmäßig ist die Liste leer und entspricht keinen Methoden.

Der Wert der Methode hat das Format [service]/[method].

* wird als Platzhalter für Folgendes akzeptiert:
  • Der Methodenname. Wenn der Wert [service]/* ist, entspricht er allen Methoden im angegebenen Dienst.
  • Der gesamte Wert der Methode, die mit einem beliebigen [service]/[method] übereinstimmt. Es wird nicht unterstützt, wenn server_rpc_events[].exclude "true" ist.
  • Der Platzhalter * kann nicht unabhängig für den Dienstnamen verwendet werden; */[method] wird nicht unterstützt.

Wenn angegeben, muss der Dienstname der vollständig qualifizierte Dienstname sein, einschließlich des Paketnamens.

Beispiele:
  • goo.Foo/Bar wählt nur die Methode Bar des Dienstes goo.Foo aus, wobei goo der Paketname ist.
  • Mit goo.Foo/* werden alle Methoden aus dem Dienst goo.Foo ausgewählt.
  • Mit * werden alle Methoden aus allen Diensten ausgewählt.
cloud_logging.server_rpc_events[].exclude Bool

Gibt an, ob die durch server_rpc_events[].methods[] gekennzeichneten Methoden vom Logging ausgeschlossen werden sollen.

Der Standardwert ist "false". Das bedeutet, dass die durch server_rpc_events[].methods[] angegebenen Methoden in Logs erfasst werden.

Wenn der Wert "true" ist, kann der Platzhalter (*) nicht als ganzer Wert in einem Eintrag von server_rpc_events[].methods[] verwendet werden.
cloud_logging.server_rpc_events[].max_metadata_bytes Int

Maximale Anzahl der zu protokollierenden Metadaten in Byte. Wenn die Größe der Metadaten das definierte Limit überschreitet, werden Schlüssel/Wert-Paare jenseits des Limits nicht protokolliert.

Der Standardwert ist 0, d. h., es werden keine Metadaten protokolliert.
cloud_logging.server_rpc_events[].max_message_bytes Int

Maximale Anzahl von Byte jeder zu protokollierenden Nachricht. Wenn die Größe der Nachricht das festgelegte Limit überschreitet, wird der Inhalt, der das Limit überschreitet, abgeschnitten.

Der Standardwert ist 0, d. h., es wird keine Nachrichtennutzlast protokolliert.
cloud_monitoring Objekt

Aktiviert Cloud Monitoring. Es gibt keine Konfigurationsoptionen. Wenn Sie ein leeres Konfigurationsobjekt angeben, wird das Monitoring aktiviert. Wenn Sie kein Konfigurationsobjekt angeben, wird das Monitoring deaktiviert.

Wenn beispielsweise keine anderen Optionen angegeben sind, aktiviert ein leerer Konfigurationsabschnitt das Monitoring.

export GRPC_GCP_OBSERVABILITY_CONFIG='{
    "project_id": "your-project-here",
    "cloud_monitoring": {
    }
}'
cloud_trace Objekt

Ein leerer Konfigurationsabschnitt aktiviert das Tracing mit den Standardkonfigurationsoptionen. Wenn Sie kein Konfigurationsobjekt angeben, wird das Tracing deaktiviert.

Ein leerer Konfigurationsabschnitt aktiviert beispielsweise das Tracing mit Standardkonfigurationsoptionen.

export GRPC_GCP_OBSERVABILITY_CONFIG='{
    "project_id": "your-project-here",
    "cloud_trace": {
    }
}'


Wenn das Tracing aktiviert ist, selbst bei einer Abtastrate von "0", wird die Entscheidung zum Abtasten eines bestimmten Trace weitergegeben.
cloud_trace.sampling_rate Zahl

Die globale Einstellung, die die Wahrscheinlichkeit bestimmt, dass ein RPC verfolgt wird. Beispiel:
  • Der Wert 0.05 bedeutet, dass eine Wahrscheinlichkeit von 5 % besteht, dass ein RPC verfolgt wird.
  • Der Wert 1.0 bedeutet, dass jeder Aufruf verfolgt wird.
  • Der Wert 0 bedeutet, dass keine neuen Traces gestartet werden.

Die Abtastrate ist standardmäßig 0.

Das Plug-in berücksichtigt die vorgelagerte Abtastentscheidung. Wenn ein RPC für das vorgelagerte Abtasten ausgewählt wird, erfasst das Plug-in die Spans und lädt die Daten in das Backend hoch, unabhängig von der Einstellung der Abtastrate für das Plug-in.
labels Objekt

Ein JSON-Objekt, das eine Reihe von Schlüssel/Wert-Paaren enthält. Sowohl der Schlüssel als auch der Wert sind Strings.

Labels werden zusammen auf Cloud Logging, Cloud Monitoring und Cloud Trace angewendet.

Trace-Definitionen

Dieser Abschnitt enthält Informationen zum Tracing.

Weitergabe von Trace-Kontext

Damit das dienstübergreifende Tracing funktioniert, muss der Dienstinhaber die Weitergabe von vorgelagertem (oder selbst gestartetem) Trace-Kontext zum nachgelagerten unterstützen. Der Trace-Kontext wird über gRPC-Metadaten zwischen Diensten weitergegeben. Aktivieren Sie die Cloud Monitoring, Cloud Logging, Cloud Trace APIs und Microservices APIs, mit denen Dienste in dieser Konfiguration ihre Telemetriedaten dem entsprechenden Dienst übergeben können.

Ohne die Unterstützung der Weitergabe können nachgelagerte Dienste keine Spans für einen Trace generieren. Vorhandene Spans sind nicht betroffen. Die Microdienst-Beobachtbarkeits-Plug-ins unterstützen das OpenCensus-Binärformat für die Codierung und deren Trace-Kontext.

Spans

Der Name eines Spans wird so formatiert:

Typ Beispielwert Nutzung
RPC-Span [Sent|Recv].helloworld.Greeter.SayHello Der Span-Name ist der vollständige Methodenname, verbunden mit Punkten, ohne Präfix-Schrägstrich.
Span-Namen haben das Präfix Sent. für CLIENT-RPC-Spans und Recv. für SERVER-RPC-Spans vor dem vollständigen Methodennamen.
Versuchs-Span Attempt.helloworld.Greeter.SayHello Fügt das Präfix Attempt. vor dem vollständigen Methodennamen ein.

Span-Labels

Die Integrationen bieten verschiedene Span-Labels.

Bei Versuchs-Spans sind zwei zusätzliche Wiederholungsattribute (Span-Labels) angehängt:

Label Beispielwert Nutzung
previous-rpc-attempts 0 Die Zahl der Wiederholungsversuche vor diesem RPC.
transparent-retry True/False Gibt an, ob dieser RPC durch einen transparenten Wiederholungsversuch initiiert wird.

Messwertdefinitionen

Die folgenden Messwerte sind verfügbar und werden in einem Dashboard mit dem Namen Microservices (gRPC) Monitoring für gängige Nutzerverhalten angezeigt:

Im Folgenden finden Sie Messwerte aus den clientseitigen gRPC-Messwerten:

Name des Messwerts Beschreibung Art, Typ, Einheit Labels
custom.googleapis.com/opencensus/grpc.io/client/started_rpcs Die Anzahl der gestarteten Client-RPC-Versuche, einschließlich der noch nicht abgeschlossenen Versuche. Kumulativ, Int64, 1 grpc_client_method
custom.googleapis.com/opencensus/grpc.io/client/completed_rpcs Die Anzahl der Client-RPCs, die abgeschlossen wurden, z. B. wenn eine Antwort vom Server empfangen oder gesendet wurde. Kumulativ, Int64, 1 grpc_client_method, grpc_client_status
custom.googleapis.com/opencensus/grpc.io/client/roundtrip_latency End-to-End-Zeit benötigt um einen RPC-Versuch abzuschließen, einschließlich der Zeit für die Auswahl eines Subkanals. Kumulativ, Verteilung, ms grpc_client_method
custom.googleapis.com/opencensus/grpc.io/client/api_latency Die Gesamtzeit, die von der gRPC-Bibliothek benötigt wird, um einen RPC abzuschließen, aus Sicht der Anwendung. Kumulativ, Verteilung, ms grpc_client_method, grpc_client_status
custom.googleapis.com/opencensus/grpc.io/client/sent_compressed_message_bytes_per_rpc Die Gesamtzahl der komprimierten und nicht verschlüsselten Byte in allen Anfragenachrichten pro RPC-Versuch. Kumulativ, Verteilung, nach grpc_client_method, grpc_client_status
custom.googleapis.com/opencensus/grpc.io/client/received_compressed_message_bytes_per_rpc Die Gesamtzahl der (komprimierten, nicht verschlüsselten) Byte in allen Antwortnachrichten pro RPC-Versuch. Kumulativ, Verteilung, nach grpc_client_method, grpc_client_status

Die folgenden gRPC-Serverseitigen messwerte sind verfügbar:

Name des Messwerts Beschreibung Art, Typ, Einheit Labels
custom.googleapis.com/opencensus/grpc.io/server/started_rpcs
Die Anzahl der RPCs, die jemals auf dem Server empfangen wurden, einschließlich RPCs, die noch nicht abgeschlossen wurden.		 Kumulativ, Int64, 1 grpc_server_method
custom.googleapis.com/opencensus/grpc.io/server/completed_rpcs
Die Gesamtzahl der abgeschlossenen RPCs, z. B. wenn eine Antwort vom Server gesendet wird.		 Kumulativ, Int64, 1 grpc_server_method, grpc_server_status
custom.googleapis.com/opencensus/grpc.io/server/sent_compressed_message_bytes_per_rpc
Die Gesamtzahl der (komprimierten, nicht verschlüsselten) Byte in allen Antwortnachrichten pro RPC.		 Kumulativ, Verteilung, nach grpc_server_method, grpc_server_status
custom.googleapis.com/opencensus/grpc.io/server/received_compressed_message_bytes_per_rpc
Die Gesamtzahl der (komprimierten, nicht verschlüsselten) Byte in allen Anfragenachrichten pro RPC.		 Kumulativ, Verteilung, nach grpc_server_method, grpc_server_status
custom.googleapis.com/opencensus/grpc.io/server/server_latency
Die Gesamtzeit, die ein RPC aus Sicht des Servertransport (HTTP2 / inproc / cronet) benötigt hat.		 Kumulativ, Verteilung, ms grpc_server_method

Jede Verteilung in der obigen Tabelle enthält ein Histogramm mit Buckets wie folgende:

  • Größe in Byte: 0, 1024, 2048, 4096, 16384, 65536, 262144, 1048576, 4194304, 16777216, 67108864, 268435456, 1073741824, 4294967296

  • Latenz in 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

Tag-Beschreibung

  • grpc_client_method: Vollständiger gRPC-Methodenname, einschließlich Paket, Dienst und Methode, z. B. google.bigtable.v2.Bigtable/CheckAndMutateRow
  • grpc_client_status: empfangener gRPC-Serverstatuscode, z. B. OK, CANCELLED, DEADLINE_EXCEEDED
  • grpc_server_method: Vollständiger gRPC-Methodenname, einschließlich Paket, Dienst und Methode, z. B. com.exampleapi.v4.BookshelfService/Checkout
  • grpc_server_status: zurückgegebener gRPC-Server-Statuscode, z. B. OK, CANCELLED, DEADLINE_EXCEEDED

Logdatensatzdefinitionen

Die Logs für die Beobachtbarkeit von Mikrodiensten werden mithilfe des Lognamens in Cloud Logging hochgeladen. PROJECT_ID ist der Platzhalter für den String, der Ihr Projekt darstellt:

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

Im Folgenden sehen Sie die JSON-Darstellung des generierten Logdatensatzes:

{
    "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
}

In der folgenden Tabelle werden die Felder aus dem Logeintrag beschrieben:

Fields Spezifikation
authority String

Ein einzelner Prozess kann verwendet werden, um mehrere virtuelle Server mit unterschiedlichen Identitäten auszuführen.

Der Wert unter "authority" ist der Name einer solchen Serveridentität. Er ist normalerweise ein Teil des URI in Form "host" oder "host:port".
callId String

Identifiziert eindeutig einen [client/server]-Aufruf, der eine UUID ist. Jeder Aufruf kann mehrere Logeinträge enthalten. Sie haben alle dieselbe callId.
Typ String

Der Typ des Logereignisses.

Ereignistypen sind:
EVENT_TYPE_UNKNOWN
CLIENT_HEADER
SERVER_HEADER
CLIENT_MESSAGE
SERVER_MESSAGE
CLIENT_HALF_CLOSE
SERVER_TRAILER
CANCEL
logger String

Der Typ des Ereignis-Loggers.

Die Typen des Ereignis-Loggers sind:
LOGGER_UNKNOWN, CLIENT, SERVER
serviceName String

Der Name des Dienstes
methodName String

Der Name der RPC-Methode.
Peering-Komponente Objekt

Peer-Adressinformationen. Auf Clientseite wird der Peer bei Server-Header- und Trailer-Ereignissen protokolliert. Auf der Serverseite wird der Peer immer im Client-Header-Ereignis protokolliert.
peer.type String

Der Typ der Adresse, ob IPv4, IPv6 oder UNIX.
peer.address String

Der Inhalt der Adresse.
peer.ip_port Int

Die Portnummer für die Adresse. Nur für IPv4- und IPv6-Adressen verfügbar.
payload Objekt

Die Nutzlast kann je nach Ereignis eine Kombination aus Metadaten, Zeitlimit, Nachricht und Status enthalten.

  • Bei Nachrichtenereignissen entspricht die Nutzlast den tatsächlichen Daten, die als Client-/Servernachrichten übergeben werden und der Länge der Nachricht.
  • Bei Headerereignissen enthält die Nutzlast den Namen und den Wert des Headers.
  • Bei Trailer-Ereignissen enthält die Nutzlast Statusdetails sowie Trailer-Metadaten (falls vorhanden).
  • Wenn bei Client-Headerereignissen ein Zeitlimit festgelegt ist, enthält die Nutzlast auch ein Zeitlimit.
payload.timeout String

Ein String, der google.protobuf.Duration darstellt, z. B. "1,2 s".

Der RPC-Zeitüberschreitungswert.
payload.metadata Zuordnung[String, String]

Wird von Header-Ereignis oder Trailer-Ereignis verwendet.
payload.message String (Byte)

Die Nachrichtennutzlast.
payload.messageLength Int

Größe der Nachricht, unabhängig davon, ob die vollständige Nachricht protokolliert wird (z. B. kann sie gekürzt oder weggelassen werden).
payload.statusCode String

Der gRPC-Statuscode.
payload.statusMessage String

Die gRPC-Statusmeldung.
payload.statusDetails String

Der Wert des Metadatenschlüssels grpc-status-details-bin, falls vorhanden. Dies ist immer eine codierte google.rpc.Status-Nachricht.
payloadTruncated Bool

True, wenn das Feld "Nachricht" oder "metadata" aufgrund der Konfigurationsoptionen entweder gekürzt oder weggelassen wird.
sequenceId Int

Die Nachrichtensequenz-ID für diesen Aufruf. Die erste Nachricht hat den Wert 1, um sie von einem nicht festgelegten Wert zu unterscheiden. Zweck dieses Felds ist es, fehlende Einträge in Umgebungen zu erkennen, in denen die Langlebigkeit oder Reihenfolge nicht garantiert ist.

Ressourcenlabels

Ressourcenlabels identifizieren die Quelle, die Beobachtbarkeitsdaten generiert. Jedes Ressourcenlabel ist ein Schlüssel/Wert-Paar, bei dem Schlüssel für die Quellumgebung (z. B. GKE oder Compute Engine) spezifische, vordefinierte Werte sind.

Für Messwerte und Tracing in GKE-Deployments werden Ressourcenlabels standardmäßig mit Ausnahme des Containernamens und des Namespace-Namens ausgefüllt. Die fehlenden Werte können mithilfe der Downward API ausgefüllt werden.

Im Folgenden finden Sie die Umgebungsvariablenschlüssel:

  • CONTAINER_NAME
  • NAMESPACE

Der Abschnitt env im Folgenden enthält beispielsweise zwei Ressourcenlabels:

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

Benutzerdefinierte Labels

Benutzerdefinierte Labels stellen zusätzliche vom Nutzer bereitgestellte Informationen in den Beobachtbarkeitsdaten dar. Labels bestehen aus einem Schlüssel und einem Wert. Das Schlüssel/Wert-Paar wird an Tracing-Daten als Span-Labels, an Messwertdaten als Messwertlabels und an Logging-Daten als Logeintrag-Labels angehängt. Alle benutzerdefinierten Labels sind vom Typ STRING.

Sie können in der Konfiguration benutzerdefinierte Labels angeben, indem Sie eine Liste von Schlüssel/Wert-Paaren für labels angeben. Die Implementierung liest die Konfiguration und erstellt ein separates Label für jedes Schlüssel/Wert-Paar. Anschließend wird das Label an die Beobachtbarkeitsdaten angehängt. Beispiel:

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

Jeder Logeintrag enthält folgende zusätzliche Labels:

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

Nächste Schritte