配置数据
环境变量中的配置数据在下表中定义。
字段 | 规范 |
---|---|
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] 形式。接受 * 作为以下项的通配符:
服务名称(如果指定)必须是完全限定的服务名称,包括软件包名称。 示例:
|
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] 形式。接受 * 作为以下项的通配符:
服务名称(如果指定)必须是完全限定的服务名称,包括软件包名称。 示例:
|
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 概率的全局设置。例如:
默认情况下,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 | Stringgrpc-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
参考中的单位字段。