微服务可观测性参考信息

配置数据

环境变量中的配置数据在下表中定义。

字段 规范
project_id String

将接收可观测性数据的项目的标识符。如果为空，则 gRPC 可观测性插件会尝试从环境变量或默认凭据中提取项目 ID。

如果未找到，则可观测性 init 函数会返回错误。
cloud_logging 对象

日志记录选项在此表中进行了分类。
如果此字段不存在，则系统会停用日志记录功能。
cloud_logging.client_rpc_events[] 列表

client_rpc_events 配置的列表，表示来自二进制文件的传出 RPC 的配置。

client_rpc_events 配置按文本顺序进行评估，系统会使用第一个匹配的配置。如果 RPC 与一个条目不匹配，则将继续匹配列表中的下一个条目。
cloud_logging.client_rpc_events[].methods[] 列表 [字符串]

方法标识符列表。

默认情况下，列表为空，不匹配任何方法。

该方法的值采用 [service]/[method] 形式。

接受 * 作为以下项的通配符：
  • 方法名称。 如果值为 [service]/*，则它与指定服务中的所有方法匹配。
  • 与任何 [service]/[method] 匹配的字段的完整值。如果 client_rpc_events[].exclude 为 true，则系统不支持。
  • * 通配符不能独立用于服务名称，并且系统不支持 */[method]。

服务名称（如果指定）必须是完全限定的服务名称，包括软件包名称。

示例：
  • goo.Foo/Bar 仅选择服务 goo.Foo 中的方法 Bar，此处的 goo 是软件包名称。
  • goo.Foo/* 选择服务 goo.Foo 中的所有方法
  • * 选择所有服务中的所有方法。
cloud_logging.client_rpc_events[].exclude 布尔值

是否应将由 client_rpc_events[].methods[] 表示的方法从日志记录中排除。

默认值为 false，意味着由 client_rpc_events[].methods[] 表示的方法将包含在日志记录中。

如果值为 true，则通配符 (*) 不能用作 client_rpc_events[].methods[]. 中的整个值
cloud_logging.client_rpc_events[].max_metadata_bytes Int

要记录的元数据字节数上限。如果元数据的大小大于定义的限制，系统不会记录超出此限制的键值对。

默认值为 0，表示不记录任何元数据。
cloud_logging.client_rpc_events[].max_message_bytes Int

要记录的每条消息的字节数上限。如果消息的大小大于定义的限制，超出限制的内容会予以截断。

默认值为 0，意味着不记录任何消息载荷。
cloud_logging.server_rpc_events[] 列表

server_rpc_events 配置列表，表示传入二进制文件的 RPC 的配置。

server_rpc_events 配置按文本顺序进行评估，系统会使用第一个匹配的配置。如果 RPC 与一个条目不匹配，则将继续匹配列表中的下一个

条目。
cloud_logging.server_rpc_events[].methods[] List [String]

可选择一组方法的字符串列表。

默认情况下，列表为空，不匹配任何方法。

该方法的值采用 [service]/[method] 形式。

接受 * 作为以下项的通配符：
  • 方法名称。 如果值为 [service]/*，则它与指定服务中的所有方法匹配。
  • 与任何 [service]/[method] 匹配的方法的完整值。如果 server_rpc_events[].exclude 为 true，则系统不支持。
  • * 通配符不能独立用于服务名称，并且系统不支持 */[method]。

服务名称（如果指定）必须是完全限定的服务名称，包括软件包名称。

示例：
  • goo.Foo/Bar 仅选择服务 goo.Foo 中的方法 Bar，此处的 goo 是软件包名称。
  • goo.Foo/* 选择服务 goo.Foo 中的所有方法
  • * 选择所有服务中的所有方法。
cloud_logging.server_rpc_events[].exclude 布尔值

是否应将由 server_rpc_events[].methods[] 表示的方法从日志记录中排除。

默认值为 false，意味着记录了由 server_rpc_events[].methods[] 表示的方法。

如果值为 true，则通配符 (*) 不能用作 server_rpc_events[].methods[] 的任何条目的整个值。
cloud_logging.server_rpc_events[].max_metadata_bytes Int

要记录的元数据字节数上限。如果元数据的大小大于定义的限制，系统不会记录超出此限制的键值对。

默认值为 0，表示不记录任何元数据。
cloud_logging.server_rpc_events[].max_message_bytes Int

要记录的每条消息的字节数上限。如果消息的大小大于定义的限制，超出限制的内容会予以截断。

默认值为 0，意味着不记录任何消息载荷。
cloud_monitoring 对象

启用 Cloud Monitoring。没有配置选项。如果您提供空配置对象，则系统会启用监控功能。如果您未提供配置对象，则系统会停用监控功能。

例如，如果未指定其他选项，则空配置部分会启用监控功能。
export GRPC_GCP_OBSERVABILITY_CONFIG='{
    "project_id": "your-project-here",
    "cloud_monitoring": {
    }
}'
cloud_trace 对象

空配置部分使用默认配置选项启用跟踪记录功能。如果您未提供配置对象，则系统会停用跟踪记录功能。

例如，空配置部分使用默认配置选项启用跟踪记录功能。
export GRPC_GCP_OBSERVABILITY_CONFIG='{
    "project_id": "your-project-here",
    "cloud_trace": {
    }
}'


启用跟踪记录功能后，即使采样率为“0”，系统也会传播对特定跟踪记录进行采样的决策。
cloud_trace.sampling_rate 数字

用于控制正在跟踪的 RPC 概率的全局设置。例如：
  • 值 0.05 意味着跟踪 RPC 的可能性为 5%。
  • 值 1.0 意味着跟踪每次调用。
  • 值 0 表示不启动新的跟踪记录。

默认情况下，sampling_rate 为 0。

插件遵循上游采样决策。如果选择了 RPC 进行上游采样，则无论插件的采样率设置如何，插件都会收集 span 并将数据上传到后端。
labels Object

包含一组键值对的 JSON 对象。键和值都是字符串。

标签同时应用于 Cloud Logging、Cloud Monitoring 和 Cloud Trace。

跟踪记录定义

本部分提供有关跟踪的信息。

跟踪上下文传播

若要让跨服务跟踪正常工作，服务所有者必须支持将来自上游（或单独启动）的跟踪上下文传播到下游。跟踪上下文通过 gRPC 元数据在服务之间传播。请确保启用 Cloud Monitoring、Cloud Logging、Cloud Trace API 和 Microservices API，以允许此配置中的服务向相应的服务报告遥测数据。

如果不支持传播，下游服务无法为跟踪记录生成 span。现有 span 不受影响。微服务可观测性插件支持 OpenCensus 二进制格式，用于编码和编码跟踪记录上下文。

Span

span 的名称格式如下：

类型 示例值 用法
RPC span [Sent|Recv].helloworld.Greeter.SayHello span 名称是完整方法名称（由英文句点连接，不带前缀斜杠）。
span 名称的前缀为 Sent.（对于 CLIENT RPC span）和 Recv.（对于 SERVER RPC span），位于完整方法名称前面。
尝试 span Attempt.helloworld.Greeter.SayHello 在完整方法名称前附加前缀 Attempt.。

span 标签

集成会提供不同的 span 标签。

对于尝试 span，附加了两个与重试相关的额外特性（span 标签）：

标签 示例值 用量
previous-rpc-attempts 0 在此 RPC 之前的重试尝试计数。
transparent-retry True/False 此 RPC 是否由透明重试启动。

指标定义

以下指标可用并显示在名为微服务 (gRPC) Monitoring 的信息中心内，用于常见用户体验历程。

以下是来自 gRPC 客户端指标的指标：

指标名称 说明 种类、类型、单元 标签
custom.googleapis.com/opencensus/grpc.io/client/started_rpcs 已启动的客户端 RPC 尝试次数，包括尚未完成的 RPC 尝试。 累计、Int64、1 grpc_client_method
custom.googleapis.com/opencensus/grpc.io/client/completed_rpcs 已完成的客户端 RPC 的计数，例如，服务器收到或发送响应时。 累计、Int64、1 grpc_client_method，grpc_client_status
custom.googleapis.com/opencensus/grpc.io/client/roundtrip_latency 完成 RPC 尝试所需的端到端时间（包括选择子通道所需的时间）。 累计、分布、毫秒 grpc_client_method
custom.googleapis.com/opencensus/grpc.io/client/api_latency gRPC 库从应用的角度完成 RPC 所需的总时间。 累计、分布、毫秒 grpc_client_method，grpc_client_status
custom.googleapis.com/opencensus/grpc.io/client/sent_compressed_message_bytes_per_rpc 每次 RPC 尝试在所有请求消息中发送的总字节数（压缩，未加密）。 累计、分布、方式 grpc_client_method，grpc_client_status
custom.googleapis.com/opencensus/grpc.io/client/received_compressed_message_bytes_per_rpc 每次 RPC 尝试在所有响应消息中收到的总字节数（压缩，未加密）。 累计、分布、方式 grpc_client_method，grpc_client_status

您可以使用以下 gRPC 服务器端指标：

指标名称 说明 种类、类型、单元 标签
custom.googleapis.com/opencensus/grpc.io/server/started_rpcs
在服务器上收到的 RPC 数量，包括尚未完成的 RPC。		 累计、Int64、1 grpc_server_method
custom.googleapis.com/opencensus/grpc.io/server/completed_rpcs
已完成 RPC 的总数，例如，服务器发送响应时。		 累计、Int64、1 grpc_server_method，grpc_server_status
custom.googleapis.com/opencensus/grpc.io/server/sent_compressed_message_bytes_per_rpc
每个 RPC 的所有响应消息中发送的总字节数（压缩，未加密）。		 累计、分布、方式 grpc_server_method，grpc_server_status
custom.googleapis.com/opencensus/grpc.io/server/received_compressed_message_bytes_per_rpc
每个 RPC 的所有请求消息中接收的总字节数（压缩，未加密）。		 累计、分布、方式 grpc_server_method，grpc_server_status
custom.googleapis.com/opencensus/grpc.io/server/server_latency
从服务器传输的 (HTTP2 / inproc / cronet) 角度来看，远程过程调用 (RPC) 所需的总时间。		 累计、分布、毫秒 grpc_server_method

上表中的每个分布均包含一个直方图，其中包含存储桶，如下所示：

  • 大小（字节数）：0、1024、2048、4096、16384、65536、262144、1048576、4194304、16777216、67108864、268435456、1073741824、4294967296

  • 延迟时间（毫秒）：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

标记说明：

  • grpc_client_method：完整的 gRPC 方法名称，包括软件包、服务和方法，例如 google.bigtable.v2.Bigtable/CheckAndMutateRow
  • grpc_client_status：收到的 gRPC 服务器状态代码，例如 OK、CANCELLED、DEADLINE_EXCEEDED
  • grpc_server_method：完整的 gRPC 方法名称，包括软件包、服务和方法，例如 com.exampleapi.v4.BookshelfService/Checkout
  • grpc_server_status：返回的 gRPC 服务器状态代码，例如 OK、CANCELLED、DEADLINE_EXCEEDED

日志记录定义

微服务可观测性日志使用日志名称（PROJECT_ID 是表示项目的字符串的占位符）上传到 Cloud Logging：

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

以下是生成的日志记录的 JSON 表示法：

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

下表介绍了日志条目中的字段：

字段 规范
authority 字符串

单个进程可用于运行具有不同身份的多个虚拟服务器。

authority 是此类服务器身份的名称。它通常是 URI 的一部分，格式为 host 或 host:port。
callId 字符串

唯一标识 [client/server] 调用（即 UUID）。每次调用可以有多个日志条目。它们都具有相同的 callId。
type String

日志事件的类型。

事件类型有：
EVENT_TYPE_UNKNOWN
CLIENT_HEADER
SERVER_HEADER
CLIENT_MESSAGE
SERVER_MESSAGE
CLIENT_HALF_CLOSE
SERVER_TRAILER
CANCEL
logger 字符串

事件日志记录器的类型。

事件日志记录器的类型包括：
LOGGER_UNKNOWN、CLIENT、SERVER
serviceName 字符串

服务的名称。
methodName String

RPC 方法的名称。
对等 Object

对等地址信息。在客户端，对等地址记录在服务器标头事件和尾随事件上。在服务器端，对等地址始终记录在客户端标头事件上。
peer.type String

地址的类型，可以是 IPv4、IPv6 或 UNIX。
peer.address String

地址的内容。
peer.ip_port Int

地址的端口号。仅适用于 IPv4 和 IPv6 地址。
payload Object

载荷可以包括元数据、超时、消息和状态的组合，具体取决于事件。

  • 对于消息事件，载荷是作为客户端/服务器消息和消息长度传递的实际数据。
  • 对于标头事件，载荷包含标头名称和值。
  • 对于尾部事件，载荷包含状态详细信息以及尾部元数据（如果存在）。
  • 对于客户端标头事件，如果设置了超时，则载荷也包括超时。
payload.timeout 字符串

表示 google.protobuf.Duration 的字符串，例如“1.2 s”。

RPC 超时值。
payload.metadata Mapping[String, String]

供标头事件或跟踪事件使用。
payload.message String (Bytes)

消息载荷。
payload.messageLength Int

消息的大小，无论是否记录完整消息（例如，它们可能会被截断或被省略）。
payload.statusCode 字符串

gRPC 状态代码。
payload.statusMessage String

gRPC 状态消息。
payload.statusDetails String

grpc-status-details-bin 元数据键的值（如有）。这始终是已编码的 google.rpc.Status 消息。
payloadTruncated 布尔值

如果配置选项导致消息或元数据字段被截断或省略，则为 True。
sequenceId Int

此调用的消息序列 ID。第一条消息的值为 1，用以消除未设置的值。此字段的目的是检测不保证耐用性和排序的环境中缺失的条目。

资源标签

资源标签标识生成可观测性数据的来源。每个资源标签都是一个键值对，其中键是特定于来源环境（例如 GKE 或 Compute Engine）的预定义值。

对于 GKE 部署中的指标和跟踪，系统会默认填充资源标签（容器名称和命名空间名称除外）。可以使用 Downward API 填充缺失值。

以下是环境变量键：

  • CONTAINER_NAME
  • NAMESPACE

例如，下面的 env 部分包含两个资源标签：

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

自定义标签

自定义标签表示可观测性数据中用户提供的其他信息。标签由键和值组成。键值对附加到跟踪记录数据（作为 span 标签）、指标数据（作为指标标签）以及日志记录数据（作为日志条目标签）。所有自定义标签都是 STRING 类型。

您可以指定 labels 的键值对列表，在配置中提供自定义标签。该实现会读取配置并为每个键值对创建单独的标签，然后将该标签附加到可观测性数据。例如：

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

每个日志条目都包含以下附加标签：

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

后续步骤