解析 Google SaaS Service Management API 日志集成Rollout 与 Unit Operation 日志条目 Schema【免费下载链接】googleapisPublic interface definitions of Google APIs.项目地址: https://gitcode.com/GitHub_Trending/go/googleapis导读google/cloud/saasplatform/saasservicemgmt/logging/v1/目录中的 README.md 明确指出该模块的 protos 定义了SaaS Service Management API 的 rollout发布日志条目 Schema是服务生产者将发布编排rollout orchestration与单元操作unit operation过程接入统一日志体系的事实标准。本文以该 README 为骨架结合同目录的 rollout_log.proto、unit_operation_log.proto 以及 v1beta1 资源模型完整讲解RolloutLog、UnitOperationLog两条日志消息的字段语义、状态机取值、错误表达与多语言代码生成方式。读完本文你将能准确解读这套日志 schema并能据此编写日志消费、检索与告警逻辑。一、模块定位为 Rollout 编排而生的日志 Schema该日志模块位于google.cloud.saasplatform.saasservicemgmt.logging.v1包下与业务 API 的v1beta1版本saasservicemgmt/v1beta1保持配套关系。业务侧通过SaasRollouts服务见 rollouts_service.proto管理 SaaS 服务的发布而日志侧则定义了面向事件流的两种日志条目日志消息描述定义文件RolloutLogRollout 事件的日志消息rollout_log.protoUnitOperationLogUnit Operation 事件的日志消息unit_operation_log.proto从源码结构可以推断RolloutLog面向一次发布的粗粒度视图UnitOperationLog面向单个单元变更的细粒度视图两者通过 ID 字段相互关联共同构成可追踪的发布审计链。二、RolloutLogRollout 事件日志条目RolloutLog是本次日志集成的核心消息定义于 rollout_log.proto 第 30-57 行。它描述一次 rollout 执行过程中的状态迁移事件字段如下// Log message for Rollout events. message RolloutLog { // Unique identifier of the root rollout. string root_rollout_id 1; // Specified rollout type associated with this rollout. string rollout_kind 2; // Strategy used for executing this rollout. string rollout_orchestration_strategy 3; // The previous state of the rollout, e.g. RUNNING. RolloutState prev_state 4; // The current running state of the rollout, e.g. PAUSED. RolloutState current_state 5; // Brief description for the rollout event, e.g. “Waiting to start rollout.” string reason 6; // A human readable string that specifies relevant information about the // rollout’s last transition, // e.g. “Soaking for 2 hours.” string message 7; // Associated status corresponding to the event this log describes, // corresponds to the status of the actionable error message. google.rpc.Status error 8; }字段语义详解字段类型说明root_rollout_idstring根 rollout 的唯一标识。由于一个 rollout 可能派生出子 rollout业务资源模型中存在root_rollout与parent_rollout字段见 rollouts_resources.proto该字段用于把整棵发布树的所有日志收敛到同一条根发布链上。rollout_kindstring本次 rollout 关联的 rollout 类型RolloutKind名称。业务侧Rollout.rollout_kind是必需且不可变的字段决定了发布遵循的模板策略。rollout_orchestration_strategystring发布执行策略。业务模型中支持两种取值Google.Cloud.Simple.AllAtOnce一次全部发布与Google.Cloud.Simple.OneLocationAtATime逐区域发布。日志中记录实际生效的策略便于事后审计发布节奏。prev_state/current_stateRolloutState状态迁移的前一状态与当前状态。例如从RUNNING迁移到PAUSED即记录为prev_stateRUNNING、current_statePAUSED。reasonstring事件的简短原因例如Waiting to start rollout.等待发布开始。messagestring关于最近一次状态迁移的人类可读说明例如Soaking for 2 hours.发布后观察 2 小时。errorgoogle.rpc.Status与事件关联的状态对应可操作错误信息的状态错误规范遵循 google/rpc/status.proto。无错误时通常为OK。典型日志事件示例根据字段语义一次发布被暂停的日志条目可以还原为如下结构JSON 示意非仓库代码{ root_rollout_id: projects/p1/locations/us-central1/rollouts/r1, rollout_kind: projects/p1/locations/us-central1/rolloutKinds/k1, rollout_orchestration_strategy: Google.Cloud.Simple.OneLocationAtATime, prev_state: RUNNING, current_state: PAUSED, reason: Error budget exceeded, message: Soaking for 2 hours., error: { code: 13, message: rollout paused due to error budget exhaustion } }三、RolloutStateRollout 生命周期状态机RolloutState枚举rollout_log.proto 第 60-89 行刻画了 rollout 从创建到终态的全部状态// The state of the rollout. enum RolloutState { // Unspecified state. ROLLOUT_STATE_UNSPECIFIED 0; // Rollout is in progress. RUNNING 1; // Rollout has been paused. PAUSED 2; // Rollout is being paused. PAUSING 3; // Rollout is being resumed. RESUMING 4; // Rollout has been cancelled. CANCELLED 5; // Rollout has failed. FAILED 6; // Rollout is waiting for some condition to be met before starting. WAITING 7; // Rollout completed successfully. SUCCEEDED 8; // Rollout is being canceled. CANCELLING 9; }各状态含义如下枚举值值语义ROLLOUT_STATE_UNSPECIFIED0未指定状态proto3 默认值通常不应出现在真实日志中。RUNNING1发布进行中。PAUSED2已暂停可被恢复。PAUSING3正在暂停中间态。RESUMING4正在恢复中间态。CANCELLED5已取消终态。FAILED6已失败终态。WAITING7等待某条件满足后才开始如等待窗口、等待依赖发布完成。SUCCEEDED8成功完成终态。CANCELLING9正在取消中间态。状态机观察从枚举设计可以推断出两条规律中间态与稳态成对出现PAUSING/PAUSED、RESUMING/RUNNING、CANCELLING/CANCELLED形成进行中→已达成的迁移对这使得日志能够精确记录状态迁移的起止时刻。终态集合明确SUCCEEDED、FAILED、CANCELLED为终态消费端可据此判定一次发布是否结束。值得注意的是日志模块的RolloutState与业务资源模型中 rollouts_resources.proto 内的Rollout.RolloutState在状态集合上基本对应后者全部带ROLLOUT_STATE_前缀但数值编号并不完全一致例如业务侧ROLLOUT_STATE_PAUSED 2、SUCCEEDED 3。从源码结构看这属于日志模块独立维护的枚举消费日志时必须以日志侧枚举定义为准避免跨模块假设编号一致。四、UnitOperationLog单元操作日志条目UnitOperationLog定义于 unit_operation_log.proto 第 32-65 行描述对某个 Unit部署单元执行的具体操作事件// Log message for Unit Operation events. message UnitOperationLog { // Unique identifier for the unit operation and the trace id for correlating // with engine logs. string unit_operation_id 1; // Human-readable message indicating details about the last transition. // e.g. Invalid resource state for Cloud Build: Cloud Build returned a // failure status string message 2; // Short description for the unit operations last transition or error. string reason 3; // Error following actionable error message specified in // https://google.aip.dev/193 google.rpc.Status error 4; // Output only. The unit state at the time of emitting the log. The last log // entry for an operation should end in a terminal state. google.cloud.saasplatform.saasservicemgmt.v1beta1.Unit.UnitState unit_state 5 [(google.api.field_behavior) OUTPUT_ONLY]; // Output only. The previous unit state. It will be the same as unit_state if // there is no state change. google.cloud.saasplatform.saasservicemgmt.v1beta1.Unit.UnitState prev_unit_state 6 [(google.api.field_behavior) OUTPUT_ONLY]; // Output only. The unit operation state at the time of emitting the log. google.cloud.saasplatform.saasservicemgmt.v1beta1.UnitOperation .UnitOperationState unit_operation_state 7 [(google.api.field_behavior) OUTPUT_ONLY]; // The type of unit operation (e.g., PROVISION, UPGRADE). string unit_operation_type 8; }字段语义详解字段类型说明unit_operation_idstring单元操作唯一标识同时作为trace id用于与底层引擎日志如 Cloud Build 日志关联。messagestring最近一次状态迁移/错误的详细说明例如Invalid resource state for Cloud Build: Cloud Build returned a failure status。reasonstring最近一次状态迁移或错误的简短原因。errorgoogle.rpc.Status遵循 AIP-193 可操作错误规范的错误状态该规范属公开 API 改进提案仓库内注释明确引用。unit_stateUnit.UnitState日志发出时刻的单元状态Output only。同一操作的最后一条日志应处于终态。prev_unit_stateUnit.UnitState前一单元状态若状态未发生变化则与unit_state相同Output only。unit_operation_stateUnitOperation.UnitOperationState日志发出时刻的单元操作状态Output only。unit_operation_typestring操作类型例如PROVISION开通、UPGRADE升级。与业务模型中UnitOperation的oneof unit_operation_typeProvision/Upgrade/Deprovision对应。引用的两个状态枚举UnitOperationLog直接引用 v1beta1 资源模型中的嵌套枚举deployments_resources.protoUnit.UnitState第 382-406 行UNIT_STATE_UNSPECIFIED(0)、UNIT_STATE_NOT_PROVISIONED(1)、UNIT_STATE_PROVISIONING(2)、UNIT_STATE_UPDATING(3)、UNIT_STATE_DEPROVISIONING(4)、UNIT_STATE_READY(5)、UNIT_STATE_ERROR(6)。其中UNIT_STATE_READY与UNIT_STATE_ERROR为终态UNIT_STATE_NOT_PROVISIONED表示未开通。UnitOperation.UnitOperationState第 656-676 行UNIT_OPERATION_STATE_UNKNOWN(0)、UNIT_OPERATION_STATE_PENDING(1)、UNIT_OPERATION_STATE_SCHEDULED(2)、UNIT_OPERATION_STATE_RUNNING(4)、UNIT_OPERATION_STATE_SUCCEEDED(5)、UNIT_OPERATION_STATE_FAILED(6)、UNIT_OPERATION_STATE_CANCELLED(7)。终态为SUCCEEDED、FAILED、CANCELLED。通过unit_state、prev_unit_state与unit_operation_state三个快照字段消费端无需回查业务 API 即可重建操作执行期间 Unit 与操作的完整状态变化轨迹。典型日志事件示例一次升级失败的UnitOperationLogJSON 示意{ unit_operation_id: projects/p1/locations/us-central1/unitOperations/uop-01, message: Invalid resource state for Cloud Build: Cloud Build returned a failure status, reason: Engine execution failed, error: { code: 13, message: Cloud Build failure status }, unit_state: UNIT_STATE_ERROR, prev_unit_state: UNIT_STATE_UPDATING, unit_operation_state: UNIT_OPERATION_STATE_FAILED, unit_operation_type: UPGRADE }五、错误表达google.rpc.Status 与 AIP-193两个日志消息都使用google.rpc.Status定义于 google/rpc/status.proto表达错误其标准结构为message Status { int32 code 1; // gRPC 标准错误码如 3INVALID_ARGUMENT, 13INTERNAL string message 2; // 人类可读的错误描述 repeated google.protobuf.Any details 3; // 结构化错误详情 }设计要点RolloutLog.error对应该事件对应的可操作错误信息的状态——即只有事件与错误相关时才携带非OK值UnitOperationLog.error明确要求遵循 AIP-193API 改进提案规范了错误消息的结构化表达便于告警系统解析与自动化处理。六、跨日志关联一条完整的发布审计链结合两类日志的 ID 字段可以从源码结构推断出如下关联模型RolloutLog.root_rollout_id→ 定位根发布一次发布可派生子发布见业务模型中Rollout.root_rollout/parent_rolloutUnitOperationLog.unit_operation_id→ 关联到引擎日志作为 trace id业务模型中UnitOperation.rollout字段将单元操作挂接到发布上因此一条发布产生的所有单元操作日志可以在检索时按rollout过滤见 rollouts_resources.proto 第 716-721 行。实际检索时可先按root_rollout_id找到发布级事件序列再按unit_operation_id下钻到每个单元的操作明细实现发布 → 单元操作 → 引擎执行三级下钻审计。七、多语言代码生成与构建集成日志 protos 与其他 Google API protos 一样通过 Bazel 管理构建。见 logging/v1/BUILD.bazelproto_library( name logging_proto, srcs [ rollout_log.proto, unit_operation_log.proto, ], deps [ //google/api:field_behavior_proto, //google/cloud/saasplatform/saasservicemgmt/v1beta1:saasservicemgmt_proto, //google/rpc:status_proto, ], )该构建文件为两种日志消息同时生成了多语言产物语言目标产物示例Javajava_gapic_assembly_gradle_pkggoogle-cloud-saasplatform-saasservicemgmt-logging-v1-javaGogo_grpc_libraryimport pathcloud.google.com/go/saasplatform/saasservicemgmt/logging/apiv1/loggingpbPythonpy_gapic_librarytransport 同时启用grpcrestPHP / Ruby / C# / C*_proto_library等对应命名空间与包从构建依赖可以看出两个重要事实一是日志包依赖//google/rpc:status_proto支撑google.rpc.Status错误字段二是依赖//google/cloud/saasplatform/saasservicemgmt/v1beta1:saasservicemgmt_proto支撑对Unit.UnitState、UnitOperation.UnitOperationState的引用这印证了日志 schema 与业务资源模型深度耦合的设计。各语言对应的包命名空间来自 proto 文件中的 option 声明C#Google.Cloud.SaasPlatform.SaasServiceMgmt.Logging.V1Gocloud.google.com/go/saasplatform/saasservicemgmt/logging/apiv1/loggingpb;loggingpbJavacom.google.cloud.saasplatform.saasservicemgmt.logging.v1PHPGoogle\Cloud\SaasPlatform\SaasServiceMgmt\Logging\V1RubyGoogle::Cloud::SaasPlatform::SaasServiceMgmt::Logging::V1八、消费日志的实践建议基于以上 schema 分析给日志消费端检索、告警、审计几点可落地的建议以终态判定流程结束对RolloutLog判断current_state是否为SUCCEEDED/FAILED/CANCELLED对UnitOperationLog判断unit_operation_state是否为SUCCEEDED/FAILED/CANCELLED。prev_state/prev_unit_state可用于统计每次迁移的耗时。用error字段驱动告警error.code ! 0即表示异常可结合reason、message生成可读告警UnitOperationLog.error遵循 AIP-193可直接解析details中的结构化错误。按 trace 链聚合以root_rollout_id为一级分组键、unit_operation_id为二级键可还原一次发布的完整执行轨迹并与底层引擎日志Cloud Build 等对账。留意枚举编号差异日志侧RolloutState与业务侧Rollout.RolloutState编号不同跨模块转换时需按名称映射不能假设数值一致。延伸阅读logging/v1 README日志集成模块入口说明rollout_log.protoRolloutLog与RolloutState完整定义unit_operation_log.protoUnitOperationLog完整定义rollouts_resources.protoRollout、RolloutKind、RolloutStats等业务资源模型deployments_resources.protoUnit、UnitOperation及被日志引用的状态枚举common.protoUnitOperationErrorCategory错误分类FATAL/RETRIABLE/IGNORABLE/STANDARD可与日志error字段配合判断错误性质rollouts_service.protoSaasRollouts服务与 REST 映射是产生这些日志事件的 API 入口logging/v1 BUILD.bazel多语言代码生成配置google/rpc/status.protogoogle.rpc.Status错误类型定义【免费下载链接】googleapisPublic interface definitions of Google APIs.项目地址: https://gitcode.com/GitHub_Trending/go/googleapis创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 解析 Google SaaS Service Management API 日志集成：Rollout 与 Unit Operation 日志条目 Schema
解析 Google SaaS Service Management API 日志集成Rollout 与 Unit Operation 日志条目 Schema【免费下载链接】googleapisPublic interface definitions of Google APIs.项目地址: https://gitcode.com/GitHub_Trending/go/googleapis导读google/cloud/saasplatform/saasservicemgmt/logging/v1/目录中的 README.md 明确指出该模块的 protos 定义了SaaS Service Management API 的 rollout发布日志条目 Schema是服务生产者将发布编排rollout orchestration与单元操作unit operation过程接入统一日志体系的事实标准。本文以该 README 为骨架结合同目录的 rollout_log.proto、unit_operation_log.proto 以及 v1beta1 资源模型完整讲解RolloutLog、UnitOperationLog两条日志消息的字段语义、状态机取值、错误表达与多语言代码生成方式。读完本文你将能准确解读这套日志 schema并能据此编写日志消费、检索与告警逻辑。一、模块定位为 Rollout 编排而生的日志 Schema该日志模块位于google.cloud.saasplatform.saasservicemgmt.logging.v1包下与业务 API 的v1beta1版本saasservicemgmt/v1beta1保持配套关系。业务侧通过SaasRollouts服务见 rollouts_service.proto管理 SaaS 服务的发布而日志侧则定义了面向事件流的两种日志条目日志消息描述定义文件RolloutLogRollout 事件的日志消息rollout_log.protoUnitOperationLogUnit Operation 事件的日志消息unit_operation_log.proto从源码结构可以推断RolloutLog面向一次发布的粗粒度视图UnitOperationLog面向单个单元变更的细粒度视图两者通过 ID 字段相互关联共同构成可追踪的发布审计链。二、RolloutLogRollout 事件日志条目RolloutLog是本次日志集成的核心消息定义于 rollout_log.proto 第 30-57 行。它描述一次 rollout 执行过程中的状态迁移事件字段如下// Log message for Rollout events. message RolloutLog { // Unique identifier of the root rollout. string root_rollout_id 1; // Specified rollout type associated with this rollout. string rollout_kind 2; // Strategy used for executing this rollout. string rollout_orchestration_strategy 3; // The previous state of the rollout, e.g. RUNNING. RolloutState prev_state 4; // The current running state of the rollout, e.g. PAUSED. RolloutState current_state 5; // Brief description for the rollout event, e.g. “Waiting to start rollout.” string reason 6; // A human readable string that specifies relevant information about the // rollout’s last transition, // e.g. “Soaking for 2 hours.” string message 7; // Associated status corresponding to the event this log describes, // corresponds to the status of the actionable error message. google.rpc.Status error 8; }字段语义详解字段类型说明root_rollout_idstring根 rollout 的唯一标识。由于一个 rollout 可能派生出子 rollout业务资源模型中存在root_rollout与parent_rollout字段见 rollouts_resources.proto该字段用于把整棵发布树的所有日志收敛到同一条根发布链上。rollout_kindstring本次 rollout 关联的 rollout 类型RolloutKind名称。业务侧Rollout.rollout_kind是必需且不可变的字段决定了发布遵循的模板策略。rollout_orchestration_strategystring发布执行策略。业务模型中支持两种取值Google.Cloud.Simple.AllAtOnce一次全部发布与Google.Cloud.Simple.OneLocationAtATime逐区域发布。日志中记录实际生效的策略便于事后审计发布节奏。prev_state/current_stateRolloutState状态迁移的前一状态与当前状态。例如从RUNNING迁移到PAUSED即记录为prev_stateRUNNING、current_statePAUSED。reasonstring事件的简短原因例如Waiting to start rollout.等待发布开始。messagestring关于最近一次状态迁移的人类可读说明例如Soaking for 2 hours.发布后观察 2 小时。errorgoogle.rpc.Status与事件关联的状态对应可操作错误信息的状态错误规范遵循 google/rpc/status.proto。无错误时通常为OK。典型日志事件示例根据字段语义一次发布被暂停的日志条目可以还原为如下结构JSON 示意非仓库代码{ root_rollout_id: projects/p1/locations/us-central1/rollouts/r1, rollout_kind: projects/p1/locations/us-central1/rolloutKinds/k1, rollout_orchestration_strategy: Google.Cloud.Simple.OneLocationAtATime, prev_state: RUNNING, current_state: PAUSED, reason: Error budget exceeded, message: Soaking for 2 hours., error: { code: 13, message: rollout paused due to error budget exhaustion } }三、RolloutStateRollout 生命周期状态机RolloutState枚举rollout_log.proto 第 60-89 行刻画了 rollout 从创建到终态的全部状态// The state of the rollout. enum RolloutState { // Unspecified state. ROLLOUT_STATE_UNSPECIFIED 0; // Rollout is in progress. RUNNING 1; // Rollout has been paused. PAUSED 2; // Rollout is being paused. PAUSING 3; // Rollout is being resumed. RESUMING 4; // Rollout has been cancelled. CANCELLED 5; // Rollout has failed. FAILED 6; // Rollout is waiting for some condition to be met before starting. WAITING 7; // Rollout completed successfully. SUCCEEDED 8; // Rollout is being canceled. CANCELLING 9; }各状态含义如下枚举值值语义ROLLOUT_STATE_UNSPECIFIED0未指定状态proto3 默认值通常不应出现在真实日志中。RUNNING1发布进行中。PAUSED2已暂停可被恢复。PAUSING3正在暂停中间态。RESUMING4正在恢复中间态。CANCELLED5已取消终态。FAILED6已失败终态。WAITING7等待某条件满足后才开始如等待窗口、等待依赖发布完成。SUCCEEDED8成功完成终态。CANCELLING9正在取消中间态。状态机观察从枚举设计可以推断出两条规律中间态与稳态成对出现PAUSING/PAUSED、RESUMING/RUNNING、CANCELLING/CANCELLED形成进行中→已达成的迁移对这使得日志能够精确记录状态迁移的起止时刻。终态集合明确SUCCEEDED、FAILED、CANCELLED为终态消费端可据此判定一次发布是否结束。值得注意的是日志模块的RolloutState与业务资源模型中 rollouts_resources.proto 内的Rollout.RolloutState在状态集合上基本对应后者全部带ROLLOUT_STATE_前缀但数值编号并不完全一致例如业务侧ROLLOUT_STATE_PAUSED 2、SUCCEEDED 3。从源码结构看这属于日志模块独立维护的枚举消费日志时必须以日志侧枚举定义为准避免跨模块假设编号一致。四、UnitOperationLog单元操作日志条目UnitOperationLog定义于 unit_operation_log.proto 第 32-65 行描述对某个 Unit部署单元执行的具体操作事件// Log message for Unit Operation events. message UnitOperationLog { // Unique identifier for the unit operation and the trace id for correlating // with engine logs. string unit_operation_id 1; // Human-readable message indicating details about the last transition. // e.g. Invalid resource state for Cloud Build: Cloud Build returned a // failure status string message 2; // Short description for the unit operations last transition or error. string reason 3; // Error following actionable error message specified in // https://google.aip.dev/193 google.rpc.Status error 4; // Output only. The unit state at the time of emitting the log. The last log // entry for an operation should end in a terminal state. google.cloud.saasplatform.saasservicemgmt.v1beta1.Unit.UnitState unit_state 5 [(google.api.field_behavior) OUTPUT_ONLY]; // Output only. The previous unit state. It will be the same as unit_state if // there is no state change. google.cloud.saasplatform.saasservicemgmt.v1beta1.Unit.UnitState prev_unit_state 6 [(google.api.field_behavior) OUTPUT_ONLY]; // Output only. The unit operation state at the time of emitting the log. google.cloud.saasplatform.saasservicemgmt.v1beta1.UnitOperation .UnitOperationState unit_operation_state 7 [(google.api.field_behavior) OUTPUT_ONLY]; // The type of unit operation (e.g., PROVISION, UPGRADE). string unit_operation_type 8; }字段语义详解字段类型说明unit_operation_idstring单元操作唯一标识同时作为trace id用于与底层引擎日志如 Cloud Build 日志关联。messagestring最近一次状态迁移/错误的详细说明例如Invalid resource state for Cloud Build: Cloud Build returned a failure status。reasonstring最近一次状态迁移或错误的简短原因。errorgoogle.rpc.Status遵循 AIP-193 可操作错误规范的错误状态该规范属公开 API 改进提案仓库内注释明确引用。unit_stateUnit.UnitState日志发出时刻的单元状态Output only。同一操作的最后一条日志应处于终态。prev_unit_stateUnit.UnitState前一单元状态若状态未发生变化则与unit_state相同Output only。unit_operation_stateUnitOperation.UnitOperationState日志发出时刻的单元操作状态Output only。unit_operation_typestring操作类型例如PROVISION开通、UPGRADE升级。与业务模型中UnitOperation的oneof unit_operation_typeProvision/Upgrade/Deprovision对应。引用的两个状态枚举UnitOperationLog直接引用 v1beta1 资源模型中的嵌套枚举deployments_resources.protoUnit.UnitState第 382-406 行UNIT_STATE_UNSPECIFIED(0)、UNIT_STATE_NOT_PROVISIONED(1)、UNIT_STATE_PROVISIONING(2)、UNIT_STATE_UPDATING(3)、UNIT_STATE_DEPROVISIONING(4)、UNIT_STATE_READY(5)、UNIT_STATE_ERROR(6)。其中UNIT_STATE_READY与UNIT_STATE_ERROR为终态UNIT_STATE_NOT_PROVISIONED表示未开通。UnitOperation.UnitOperationState第 656-676 行UNIT_OPERATION_STATE_UNKNOWN(0)、UNIT_OPERATION_STATE_PENDING(1)、UNIT_OPERATION_STATE_SCHEDULED(2)、UNIT_OPERATION_STATE_RUNNING(4)、UNIT_OPERATION_STATE_SUCCEEDED(5)、UNIT_OPERATION_STATE_FAILED(6)、UNIT_OPERATION_STATE_CANCELLED(7)。终态为SUCCEEDED、FAILED、CANCELLED。通过unit_state、prev_unit_state与unit_operation_state三个快照字段消费端无需回查业务 API 即可重建操作执行期间 Unit 与操作的完整状态变化轨迹。典型日志事件示例一次升级失败的UnitOperationLogJSON 示意{ unit_operation_id: projects/p1/locations/us-central1/unitOperations/uop-01, message: Invalid resource state for Cloud Build: Cloud Build returned a failure status, reason: Engine execution failed, error: { code: 13, message: Cloud Build failure status }, unit_state: UNIT_STATE_ERROR, prev_unit_state: UNIT_STATE_UPDATING, unit_operation_state: UNIT_OPERATION_STATE_FAILED, unit_operation_type: UPGRADE }五、错误表达google.rpc.Status 与 AIP-193两个日志消息都使用google.rpc.Status定义于 google/rpc/status.proto表达错误其标准结构为message Status { int32 code 1; // gRPC 标准错误码如 3INVALID_ARGUMENT, 13INTERNAL string message 2; // 人类可读的错误描述 repeated google.protobuf.Any details 3; // 结构化错误详情 }设计要点RolloutLog.error对应该事件对应的可操作错误信息的状态——即只有事件与错误相关时才携带非OK值UnitOperationLog.error明确要求遵循 AIP-193API 改进提案规范了错误消息的结构化表达便于告警系统解析与自动化处理。六、跨日志关联一条完整的发布审计链结合两类日志的 ID 字段可以从源码结构推断出如下关联模型RolloutLog.root_rollout_id→ 定位根发布一次发布可派生子发布见业务模型中Rollout.root_rollout/parent_rolloutUnitOperationLog.unit_operation_id→ 关联到引擎日志作为 trace id业务模型中UnitOperation.rollout字段将单元操作挂接到发布上因此一条发布产生的所有单元操作日志可以在检索时按rollout过滤见 rollouts_resources.proto 第 716-721 行。实际检索时可先按root_rollout_id找到发布级事件序列再按unit_operation_id下钻到每个单元的操作明细实现发布 → 单元操作 → 引擎执行三级下钻审计。七、多语言代码生成与构建集成日志 protos 与其他 Google API protos 一样通过 Bazel 管理构建。见 logging/v1/BUILD.bazelproto_library( name logging_proto, srcs [ rollout_log.proto, unit_operation_log.proto, ], deps [ //google/api:field_behavior_proto, //google/cloud/saasplatform/saasservicemgmt/v1beta1:saasservicemgmt_proto, //google/rpc:status_proto, ], )该构建文件为两种日志消息同时生成了多语言产物语言目标产物示例Javajava_gapic_assembly_gradle_pkggoogle-cloud-saasplatform-saasservicemgmt-logging-v1-javaGogo_grpc_libraryimport pathcloud.google.com/go/saasplatform/saasservicemgmt/logging/apiv1/loggingpbPythonpy_gapic_librarytransport 同时启用grpcrestPHP / Ruby / C# / C*_proto_library等对应命名空间与包从构建依赖可以看出两个重要事实一是日志包依赖//google/rpc:status_proto支撑google.rpc.Status错误字段二是依赖//google/cloud/saasplatform/saasservicemgmt/v1beta1:saasservicemgmt_proto支撑对Unit.UnitState、UnitOperation.UnitOperationState的引用这印证了日志 schema 与业务资源模型深度耦合的设计。各语言对应的包命名空间来自 proto 文件中的 option 声明C#Google.Cloud.SaasPlatform.SaasServiceMgmt.Logging.V1Gocloud.google.com/go/saasplatform/saasservicemgmt/logging/apiv1/loggingpb;loggingpbJavacom.google.cloud.saasplatform.saasservicemgmt.logging.v1PHPGoogle\Cloud\SaasPlatform\SaasServiceMgmt\Logging\V1RubyGoogle::Cloud::SaasPlatform::SaasServiceMgmt::Logging::V1八、消费日志的实践建议基于以上 schema 分析给日志消费端检索、告警、审计几点可落地的建议以终态判定流程结束对RolloutLog判断current_state是否为SUCCEEDED/FAILED/CANCELLED对UnitOperationLog判断unit_operation_state是否为SUCCEEDED/FAILED/CANCELLED。prev_state/prev_unit_state可用于统计每次迁移的耗时。用error字段驱动告警error.code ! 0即表示异常可结合reason、message生成可读告警UnitOperationLog.error遵循 AIP-193可直接解析details中的结构化错误。按 trace 链聚合以root_rollout_id为一级分组键、unit_operation_id为二级键可还原一次发布的完整执行轨迹并与底层引擎日志Cloud Build 等对账。留意枚举编号差异日志侧RolloutState与业务侧Rollout.RolloutState编号不同跨模块转换时需按名称映射不能假设数值一致。延伸阅读logging/v1 README日志集成模块入口说明rollout_log.protoRolloutLog与RolloutState完整定义unit_operation_log.protoUnitOperationLog完整定义rollouts_resources.protoRollout、RolloutKind、RolloutStats等业务资源模型deployments_resources.protoUnit、UnitOperation及被日志引用的状态枚举common.protoUnitOperationErrorCategory错误分类FATAL/RETRIABLE/IGNORABLE/STANDARD可与日志error字段配合判断错误性质rollouts_service.protoSaasRollouts服务与 REST 映射是产生这些日志事件的 API 入口logging/v1 BUILD.bazel多语言代码生成配置google/rpc/status.protogoogle.rpc.Status错误类型定义【免费下载链接】googleapisPublic interface definitions of Google APIs.项目地址: https://gitcode.com/GitHub_Trending/go/googleapis创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考