Cómo depurar una extensión

Estás consultando la documentación de Apigee Edge.
Consulta la documentación de Apigee X.
Información

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

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

    Los errores relacionados con las extensiones que aparecen en la Herramienta de seguimiento no suelen contener muchos detalles, excepto para indicar qué texto destacado de extensión falló, junto con un código de error de HTTP. Cuando aquí no veas nada útil, el siguiente mejor lugar para buscar es el registro de la extensión que estás usando.

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

    Estos registros incluyen las 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 interna. Cuando busques en los registros, ten en cuenta que algunas de las entradas no son relevantes para el error que estás corrigiendo. Las entradas de registro relacionadas con la extensión suelen comenzar con la palabra details, como en la siguiente entrada de registro de la extensión 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 procesamiento de solicitudes de extensión fluye desde una política ExtensionExtension en un proxy de API, a través de la extensión, al recurso externo y, luego, regresa. Por lo tanto, puede producirse un error en cualquiera de esos lugares.

Los errores que ves pueden clasificarse en 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, Google Cloud Logging mostrará un error a la extensión. Por lo general, los detalles de estos errores se encuentran en el registro de extensiones.

Evidencia en la herramienta Trace

En el editor de proxy, estos errores suelen aparecer como un error a nivel de 4xx o 5xx. Sin embargo, el editor de proxy no mostrará ningún detalle 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 registros de extensiones

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, es el resultado de 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 ExtensionExtension

Estos errores ocurren cuando la política ExtensionExtension está mal configurada, ya sea debido a un error de sintaxis de configuración de la política o a claves o valores de configuración incorrectos. Estos errores pueden presentarse de dos formas, según cómo esté configurada la política:

  • Valores incorrectos evaluados por el recurso externo

    Esto puede ocurrir cuando el error de configuración parece válido para la extensión, pero no 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 registrado en el registro de la extensión:

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

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

    details: 'Resource type cannot be empty'
    
  • Valores incorrectos que evaluó la extensión

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

Evidencia en la herramienta Trace

En el editor de proxy, estos errores suelen aparecer como un error a nivel de 4xx o 5xx. Sin embargo, el editor de proxy no mostrará ningún detalle sobre la causa del error, excepto para indicar que la extensión mostró un error. El siguiente error aparece en la herramienta de seguimiento 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 registros de extensiones

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 a la extensión, que agregará el error al registro de la extensión.

Evidencia en la herramienta 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á detalles específicos 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 registros de extensiones

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

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