Cómo depurar una extensión

Estás viendo la documentación de Apigee Edge.
Ir a la documentación de Apigee X. info

Puedes depurar una extensión con los mensajes visibles en dos lugares: la herramienta de Trace y los registros de extensión. Cuando una extensión no funciona, identificar el problema a veces puede requerir información de ambos lugares.

  • La herramienta de Trace de Apigee Edge es donde pruebas y editas de forma iterativa el código del proxy de API a medida que lo desarrollas. Los mensajes de Trace incluyen errores del código del proxy de API, incluida la configuración del proxy de API y de la política.

    Por lo general, los errores relacionados con la extensión que aparecen en la herramienta de Trace no contienen muchos detalles, excepto para indicar qué llamada de extensión falló, junto con un código de error HTTP. Cuando no ves nada útil aquí, el siguiente mejor lugar para buscar es el registro de la extensión que usas.

  • Las extensiones generan entradas de registro en el tiempo de ejecución. (Los registros de extensión solo están disponibles para los administradores de la organización).

    Estos registros incluyen entradas que muestra el recurso externo con el que la extensión está configurada para interactuar. Por ejemplo, si las credenciales de recursos externos están mal configuradas en la extensión, es probable que el error aparezca aquí.

    Los registros también incluyen entradas del código de extensión interno. Cuando revises los registros, ten en cuenta que algunas de las entradas no son relevantes para el error que corriges. Por lo general, las entradas de registro relacionadas con la extensión comienzan con la palabra details, como en la siguiente entrada de registro de la extensión de 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.'

Tipos de errores y causas

El flujo de procesamiento de solicitudes de extensión pasa de una política de ExtensionCallout en un proxy de API, a través de la extensión, al recurso externo y, luego, vuelve. Por lo tanto, puede ocurrir un error en cualquiera de esos lugares.

Los errores que ves pueden pertenecer a las siguientes categorías.

Errores en la configuración de la extensión

Esta es la configuración que realiza un administrador de la organización cuando agrega una extensión a un entorno.

Por ejemplo, si configuras la extensión de Cloud Logging con un ID del proyecto de Google Cloud incorrecto, Cloud Logging mostrará un error en la extensión. Por lo general, los detalles sobre estos errores se encuentran en el registro de extensión.

Evidencia en la herramienta de Trace

En el editor de proxy, estos errores suelen aparecer como un error de nivel 4xx o 5xx. Sin embargo, el editor de proxy no mostrará ninguna información específica sobre la causa del error, excepto para indicar que la extensión mostró un error.

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

Evidencia en los registros de extensión

Si hay detalles sobre este tipo de error, los verás en las entradas de registro de la extensión. El siguiente mensaje de error, que muestra el servicio de Cloud Pub/Sub, se debe a un ID del proyecto con errores de formato.

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

Errores en la configuración de la política de ExtensionCallout

Estos errores se producen cuando la política de ExtensionCallout está mal configurada, ya sea por un error de sintaxis de configuración de la política o por claves o valores de configuración incorrectos. Estos errores adoptan dos formas, según cómo se configure la política:

  • Valores incorrectos evaluados por el recurso externo

    Esto puede ocurrir cuando el error de configuración parecía válido para la extensión, pero no era válido para el recurso externo. Por ejemplo, si la extensión pasa un ID de base de datos incorrecto a Cloud Spanner, Cloud Spanner mostrará un error que se registrará en el registro de extensión:

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

    Esto también puede ocurrir para una configuración JSON incorrecta en el elemento <Input> de la política. En el caso de algunas extensiones, la extensión procesa una parte del JSON y otra parte se pasa al recurso. Por ejemplo, el JSON de configuración de la extensión de Cloud Logging incluye un objeto metadata cuyo contenido se pasa a Cloud Logging. Los nombres de clave incorrectos allí, como typ en lugar de type, pueden mostrar errores del recurso externo que aparecen como entradas en el registro de extensión:

    details: 'Resource type cannot be empty'

  • Valores incorrectos evaluados por la extensión

    Estos errores incluyen errores de sintaxis en las partes evaluadas por la política del JSON del elemento <Input>, errores de ortografía en el nombre de la acción en el elemento <Action>, etcétera. Por lo general, estos errores aparecerán en la herramienta de Trace, pero no en los registros de extensión.

Evidencia en la herramienta de Trace

En el editor de proxy, estos errores suelen aparecer como un error de nivel 4xx o 5xx. Sin embargo, el editor de proxy no mostrará ninguna información específica sobre la causa del error, excepto para indicar que la extensión mostró un error. El siguiente error aparece en la herramienta de Trace cuando se escribe mal el nombre de la acción en la extensión de Cloud Firestore.

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

Evidencia en los registros de extensión

Cuando la configuración de la política genera un error de procesamiento en el recurso externo, el error suele aparecer en el registro.

Este es un error en el que la solicitud al recurso externo no se realizó correctamente por motivos que no están relacionados con la extensión.

Por ejemplo, imagina que usas la extensión de Cloud Spanner para agregar una fila a la base de datos, pero el valor de la clave primaria de la fila ya se usa en una fila existente. Cloud Spanner mostrará un error en la extensión, que agregará el error al registro de extensión.

Evidencia en la herramienta de Trace

En el editor de proxy, estos errores suelen aparecer como un error de nivel 4xx- o 5xx. Sin embargo, el editor de proxy no mostrará ninguna información específica sobre la causa del error, excepto para indicar que la extensión mostró un error.

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

Evidencia en los registros de extensión

Por lo general, el registro tendrá entradas con mensajes del recurso externo. El siguiente mensaje de registro de Cloud Spanner describe el error de valor de clave primaria existente.

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