调试扩展程序

您正在查看 Apigee Edge 文档。
转到 Apigee X 文档。 info

您可以使用在两个位置可见的消息调试扩展程序：Trace 工具和扩展程序日志。当扩展程序无法正常工作时，有时需要同时查看这两个位置的信息才能找出问题。

  • Apigee Edge Trace 工具是您在开发 API 代理代码时对其进行迭代测试和修改的地方。跟踪消息包含来自 API 代理代码的错误，包括 API 代理和政策配置。

    Trace 工具中显示的与扩展程序相关的错误通常不包含太多详细信息，只会说明哪个扩展程序调用失败，以及 HTTP 错误代码。如果您在此处看不到任何有用的信息，那么下一个最佳查看位置是您正在使用的扩展程序的日志。

  • 扩展程序会在运行时生成日志条目。（扩展程序日志仅适用于组织管理员。）

    这些日志包含扩展程序配置为与之交互的外部资源返回的条目。例如，如果在扩展程序中错误配置了外部资源凭据，则错误很可能会显示在此处。

    日志还包含来自内部扩展程序代码的条目。在查看日志时，请注意，某些条目与您要更正的错误无关。与扩展程序相关的日志条目通常以字词 details 开头，如以下 Cloud Pub/Sub 扩展程序的日志条目所示：

    details: 'Invalid resource name given (name=projects/example-test-123456/topic/extension-example). Refer to https://cloud.google.com/pubsub/docs/admin#resource_names for more information.'

错误类型和原因

扩展程序请求处理流程从 API 代理中的 ExtensionCallout 政策开始，通过扩展程序，到外部资源，然后再返回。因此，任何这些位置都可能发生错误。

您看到的错误可能属于以下类别。

扩展程序配置中的错误

这是组织管理员在向环境添加扩展程序时进行的配置。

例如，如果您使用不正确的 Google Cloud 项目 ID 配置 Cloud Logging 扩展程序，Google Cloud Logging 会向扩展程序返回错误。 有关这些错误的详细信息通常位于扩展程序日志中。

Trace 工具中的证据

在代理编辑器中，这些错误通常会显示为 4xx 或 5xx-级错误。不过，代理编辑器不会显示有关错误原因的任何具体信息 ，只会说明扩展程序返回了错误。

{
  "fault": {
    "faultstring":"Execution of ConnectorCallout Logging-Extension failed. Reason: Connector returned error statuscode=500",
    "detail": {
      "errorcode":"steps.connectorcallout.ExecutionFailed"
    }
  }
}

扩展程序日志中的证据

如果存在有关此类错误的详细信息，您会在扩展程序的日志条目中看到这些信息。以下错误消息由 Cloud Pub/Sub 服务 返回，原因是项目 ID 格式不正确。

details: 'Project does not exist: example-test-12345'

ExtensionCallout 政策配置中的错误

当 ExtensionCallout 政策配置错误时，就会发生这些错误，可能是因为政策配置语法错误，也可能是因为配置键或值不正确。这些错误有两种形式，具体取决于政策的配置方式：

  • 外部资源评估的值不正确

    当配置错误对扩展程序来说似乎有效，但对外部资源来说无效时，可能会发生这种情况。例如，如果扩展程序将不正确的数据库 ID 传递给 Cloud Spanner，Cloud Spanner 会返回一个错误，该错误会记录在扩展程序日志中：

    details: 'Database not found: projects/example-test-123456/instances/spanner-extension-example-db/databases/my-business-d'

    如果政策的 <Input> 元素中的配置 JSON 不正确，也可能会发生这种情况。对于某些扩展程序，JSON 的一部分由扩展程序处理，一部分传递给资源。例如，Cloud Logging 扩展程序配置 JSON 包含一个 metadata 对象，其内容会传递给 Cloud Logging。如果其中的键名称不正确（例如 typ 而不是 type），则可能会从外部资源返回错误，这些错误会显示为扩展程序日志中的条目：

    details: 'Resource type cannot be empty'

  • 扩展程序评估的值不正确

    这些错误包括 <Input> 元素 JSON 中政策评估部分的语法错误、<Action> 元素中操作名称的拼写错误等。这些错误通常会显示在 Trace 工具中，但不会显示在扩展程序日志中。

Trace 工具中的证据

在代理编辑器中，这些错误通常会显示为 4xx 或 5xx-级错误。不过，代理编辑器不会显示有关错误原因的任何具体信息 ，只会说明扩展程序返回了错误。在 Cloud Firestore 扩展程序中拼错操作名称时，Trace 工具中会显示以下 错误。

{
  "fault":{
    "faultstring":"Execution of ConnectorCallout Add-User-Data failed. Reason: Connector returned error statuscode=404","detail":
    {
      "errorcode":"steps.connectorcallout.ExecutionFailed"
    }
  }
}

扩展程序日志中的证据

当政策配置导致外部资源中出现处理错误时，该错误通常会显示在日志中。

这是指由于与扩展程序无关的原因，向外部资源发出的请求未成功。

例如，假设您使用 Cloud Spanner 扩展程序 向数据库添加行，但该行的主键值已在现有行中使用。Cloud Spanner 会向扩展程序返回错误，扩展程序会将该错误添加到扩展程序日志中。

Trace 工具中的证据

在代理编辑器中，这些错误通常会显示为 4xx- 或 或 5xx-级错误。不过，代理编辑器不会显示有关错误原因的任何 具体信息，只会说明扩展程序返回了错误。

{
  "fault":{
    "faultstring":"Execution of ConnectorCallout Add-User-Data failed. Reason: Connector returned error statuscode=404",
    "detail":{
      "errorcode":"steps.connectorcallout.ExecutionFailed"
    }
  }
}

扩展程序日志中的证据

日志通常包含来自外部资源本身的消息条目。以下来自 Cloud Spanner 的日志消息描述了现有主键值错误。

details: 'Row [jonesy42] in table user already exists'