微服务可观测性参考信息

配置数据

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

字段	规范
`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。
类型	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"
}

后续步骤

如需了解指标种类和类型，请参阅值类型和指标种类。
如需了解分布，请参阅分布参考页面。
如需了解如何为这些分布指标绘制图表，请参阅分布指标。
如需了解单位（例如 1、ms 和 By），请参阅 MetricDescriptor 参考中的单位字段。