排查 Cloud Logging 中缺失 Apigee 日志的问题

您正在查看 Apigee 和 Apigee Hybrid 文档。
此主题没有等效的 Apigee Edge 文档。

症状

将 Apigee API 日志发送到 Cloud Logging 是一种常见的应用场景，通常通过 MessageLogging 政策或 ServiceCallout 政策完成。在这两种情况下，Apigee 都使用 Cloud Logging API 写入日志。

在某些情况下，在 Cloud Logging 中可能看不到 Apigee API 日志。

错误消息

不显示错误消息。

可能的原因

原因	说明	适用的问题排查说明
未启用 Cloud Logging API	确保您已在 Apigee 组织的 Google Cloud 项目中启用 Cloud Logging API。	Apigee 和 Apigee Hybrid
代理服务账号配置错误	在部署时 (Apigee) 或运行时配置 (Apigee Hybrid) 中使用的服务账号可能被删除/配置错误。	Apigee 和 Apigee Hybrid
政策配置中的项目名称不正确	政策配置中的项目名称与 Apigee 组织关联的项目名称不同。	Apigee 和 Apigee Hybrid
运行时服务账号缺少角色/权限	对于 Apigee Hybrid，请确保运行时服务账号具有 Service Account Token Creator 角色。这是使用 Google 身份验证所必需的角色。	Apigee Hybrid
日志条目大小超过允许的 Cloud Logging 限制	Cloud Logging 具有 256 KB 的条目大小限制，并且无法更改。	Apigee 和 Apigee Hybrid

原因：未启用 Cloud Logging API

诊断

验证 Cloud Logging API 已启用。如需了解如何在 Google Cloud 控制台中列出已启用的 API 和服务，请参阅列出已启用的服务。

解决方法

如果 Cloud Logging API 未启用，请按照启用服务中的步骤启用它。启用 API 可能需要几分钟时间。

如果您无法解决因未启用 Cloud Logging API 而导致 Cloud Logging 中缺少日志的问题，请参阅必须收集诊断信息。

原因：代理服务账号配置错误

诊断

Apigee

查找服务账号名称。

使用 Apigee 界面：
1. 点击开发 > API 代理，然后点击代理名称。例如，TurboBooks。
2. 部署下会显示服务账号名称。

使用 Apigee API：

发出以下 Apigee API 调用：

curl -H "Authorization: Bearer $(gcloud auth print-access-token)" "https://apigee.googleapis.com/v1/organizations/ORG_NAME/environments/ENV_NAME/apis/PROXY_NAME/revisions/REVISION_NUMBER/deployments"

请替换以下内容：

ORG_NAME：您的组织的名称。例如 apigee-example-org。
ENV_NAME：环境的名称。例如 myenv。
PROXY_NAME：代理的名称。例如 TurboBooks。
REVISION_NUMBER：修订版本号。例如 4。

例如：

curl -H "Authorization: Bearer $(gcloud auth print-access-token)" "https://apigee.googleapis.com/v1/organizations/apigee-example-org/environments/myenv/apis/TurboBooks/revisions/4/deployments"

将会返回类似如下的内容：

{
  "environment": "myenv",
  "apiProxy": "TurboBooks",
  "revision": "4",
  "deployStartTime": "1687408163394",
  "state": "READY",
  "instances": [
    {
      "instance": "apiginstance",
      "deployedRevisions": [
        {
          "revision": "4",
          "percentage": 100
        }
    .
    .
    .
    .
  "serviceAccount": "projects/-/serviceAccounts/envsa-79@apigee-example-org.iam.gserviceaccount.com"
}

其中，serviceAccount 是与 API 代理关联的服务账号。

验证此代理服务账号满足以下条件：
1. 此服务账号必须位于您用于创建 Apigee 组织的同一 Google Cloud 项目中。例如，apigee-example-org.
2. 部署代理的用户具有此服务账号的 iam.serviceAccounts.actAs 权限。
  - 如需查看角色列表，请参阅服务账号角色。
  - 如需了解如何查看特定用户的角色，请参阅查看当前访问权限。
3. 代理服务账号具有调用 Cloud Logging 服务所需的权限。
  - 如需查看角色列表，请参阅 Logging 角色。
  - 如需了解如何查看代理服务账号权限，请参阅查看当前访问权限。

Apigee Hybrid

对于 Apigee Hybrid，除了 Apigee 中列出的步骤之外，请打开您的 overrides.yaml 文件，并确保每个需要 Google 身份验证的环境下都指定了服务账号。例如：

envs:
  - name: "ENVIRONMENT_NAME"
    serviceAccountPaths:
      runtime: "KEY_FILE_PATH"

请替换以下内容：

ENVIRONMENT_NAME：环境的名称。例如 myenv。
KEY_FILE_PATH：运行时服务账号密钥文件的路径。通常，您应该已在安装过程中创建了服务账号，详见创建服务账号。

解决方法

如果服务账号不属于您用于创建 Apigee 组织的 Google Cloud 项目，则需要在同一 Google Cloud 项目中创建和使用服务账号。使用 Google 身份验证中也对此进行了介绍。
如果部署代理的用户没有此服务账号的 iam.serviceAccounts.actAs 权限，请参阅授予单个角色。
如果代理服务账号没有调用 Cloud Logging 服务所需的权限，请参阅授予单个角色。

如果本文档中的步骤无法解决 Apigee 和 Apigee Hybrid 代理服务账号配置错误的问题，请参阅必须收集诊断信息。

原因：政策配置中的项目名称不正确

诊断

如果您使用 MessageLogging 政策将日志发送到 Cloud Logging，请执行以下操作：

在Apigee 界面中，点击开发 > API 代理 > API 代理名称 > 开发标签页。
在代码窗格中，找到 <CloudLogging> 元素。
验证 <LogName> 值是否是正确的项目名称：
```
<CloudLogging>
  <LogName>projects/PROJECT_ID/logs/LOG_ID</LogName>
</CloudLogging>
```
替换以下内容：
- PROJECT_ID：Google Cloud 项目 ID。例如 apigee-example-org。
- LOG_ID：Cloud Logging 日志 ID。例如 apigee-logs。

解决方法

如果 <LogName> 元素中的值不正确，请将其更新为正确的值。

如果本文档中的步骤无法解决问题，请参阅必须收集诊断信息。

原因：运行时服务账号缺少角色/权限

诊断

确保运行时能够模拟代理服务账号。

运行以下 gcloud 命令验证运行时服务账号是否具有代理服务账号的 iam.serviceAccountTokenCreator 角色：

gcloud iam service-accounts get-iam-policy PROXY_SA_NAME@PROJECT_ID.iam.gserviceaccount.com

请替换以下内容：

PROXY_SA_NAME：代理服务账号的名称。例如 envsa-79。
PROJECT_ID：Google Cloud 项目 ID。例如 apigee-example-org。

将会返回类似如下的内容：

- members:
  - serviceAccount:RUNTIME_SA_NAME@PROJECT_ID.iam.gserviceaccount.com
  role: roles/iam.serviceAccountTokenCreator

请替换以下内容：

RUNTIME_SA_NAME：运行时服务账号的 ID。例如 apigee-runtime。

例如：

gcloud iam service-accounts get-iam-policy envsa-79@apigee-example-org.iam.gserviceaccount.com
  bindings:
  - members:
    - user:222larabrown@gmail.com
    role: roles/iam.serviceAccountAdmin
  - members:
    - serviceAccount:apigee-runtime@apigee-example-org.iam.gserviceaccount.com
    role: roles/iam.serviceAccountTokenCreator
  - members:
    - user:222larabrown@gmail.com
    role: roles/iam.serviceAccountUser
  etag: BwX-shcrL3o=
  version: 1

如果您在输出中没有看到 iam.serviceAccountTokenCreator 角色和预期成员，请按照解决方法中的步骤授予正确的角色。

解决方法

行以下 gcloud 命令，向运行时服务账号授予代理服务账号的 iam.serviceAccountTokenCreator 角色：

gcloud iam service-accounts add-iam-policy-binding \
PROXY_SA_NAME@PROJECT_ID.iam.gserviceaccount.com \
--member=serviceAccount:RUNTIME_SA_NAME@PROJECT_ID.iam.gserviceaccount.com \
--role=roles/iam.serviceAccountTokenCreator

请替换以下内容：

PROXY_SA_NAME：代理服务账号的名称。例如，envsa-79。
PROJECT_ID：Google Cloud 项目 ID。例如 apigee-example-org。
RUNTIME_SA_NAME：运行时服务账号的 ID。例如，apigee-runtime。

如果本文档中的步骤无法解决问题，请参阅必须收集诊断信息。

原因：日志条目大小超过允许的日志记录限制

诊断

如果在确保本文档中所述的其他原因不是问题所在后您未在 Cloud Logging 中看到某些日志，则可能是从 Apigee 发送的部分日志条目的大小超过了 256 KB，这是 Cloud Logging 中日志条目大小的硬性限制。如需了解详情，请参阅 Logging 使用限制。

解决方法

这是 Cloud Logging 中不可配置的限制，目前已知的唯一解决方法是将 Apigee 发送的日志条目的大小保持在 256 KB 以下。如果您记录的载荷可能会超出此限制，请勿记录此载荷，或者了解在达到限制后某些事务将不会被记录。

如果本文档中的步骤无法解决问题，请参阅必须收集诊断信息。

必须收集的诊断信息

如果按照上述说明操作后问题仍然存在，请收集以下诊断信息，然后联系 Apigee 支持团队：

Apigee 组织。
发生问题的环境和 API 代理。
下载的调试会话（将提供上述所有信息）。
API 代理中将日志发送到 Cloud Logging 的具体政策名称。
对于 Apigee Hybrid：overrides.yaml 文件。