Como depurar uma extensão

Você está visualizando a documentação do Apigee Edge.
Acesse a documentação da Apigee X. info

É possível depurar uma extensão usando mensagens que aparecem em dois lugares: a ferramenta Trace e os registros de extensão. Quando uma extensão não está funcionando, a identificação do problema às vezes exige informações dos dois lugares.

  • A ferramenta Trace do Apigee Edge é onde você testa e edita de forma iterativa o código do proxy de API durante o desenvolvimento. As mensagens de rastreamento incluem erros do código do proxy da API, incluindo a configuração da API e da política.

    Os erros relacionados à extensão que aparecem na ferramenta de rastreamento geralmente não contêm muitos detalhes, exceto para informar qual chamada de extensão falhou, além de um código de erro HTTP. Se você não encontrar nada útil aqui, o próximo lugar a ser verificado é o registro da extensão que você está usando.

  • As extensões geram entradas de registro no momento da execução. Os registros de extensão estão disponíveis apenas para administradores da organização.

    Esses registros incluem entradas retornadas pelo recurso externo com que a extensão está configurada para interagir. Por exemplo, se as credenciais de recursos externos estiverem incorretamente configuradas na extensão, o erro provavelmente vai aparecer aqui.

    Os registros também incluem entradas do código interno da extensão. Ao analisar os registros, lembre-se de que algumas das entradas não são relevantes para o erro que você está corrigindo. As entradas de registro relacionadas à extensão geralmente começam com a palavra details, como na seguinte entrada de registro da extensão 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 e causas de erros

O processamento da solicitação de extensão flui de uma política ExtensionCallout em um proxy de API, pela extensão, para o recurso externo e depois de volta. Portanto, um erro pode ocorrer em qualquer um desses lugares.

Os erros podem se enquadrar nas seguintes categorias.

Erros na configuração da extensão

Essa é a configuração que um administrador da organização faz ao adicionar uma extensão a um ambiente.

Por exemplo, se você configurar a extensão do Cloud Logging com um ID de projeto do Google Cloud incorreto, o Cloud Logging vai retornar um erro para a extensão. Os detalhes sobre esses erros geralmente estão no registro da extensão.

Evidências na ferramenta Trace

No editor de proxy, esses erros normalmente aparecem como um erro de nível 4xx ou 5xx. No entanto, o editor de proxy não mostra detalhes sobre a causa do erro, apenas que a extensão retornou um erro.

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

Evidências nos registros de extensão

Se houver detalhes sobre esse tipo de erro, eles vão aparecer nas entradas de registro da extensão. A mensagem de erro a seguir, retornada pelo serviço do Cloud Pub/Sub, é resultado de um ID de projeto incorreto.

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

Erros na configuração da política ExtensionCallout

Esses erros ocorrem quando a política ExtensionCallout está incorretamente configurada, seja por um erro de sintaxe de configuração da política ou por chaves ou valores de configuração incorretos. Esses erros podem ter duas formas, dependendo da configuração da política:

  • Valores incorretos avaliados pelo recurso externo

    Isso pode ocorrer quando o erro de configuração aparece válido para a extensão, mas é inválido para o recurso externo. Por exemplo, se a extensão transmitir um ID de banco de dados incorreto para o Cloud Spanner, o Cloud Spanner vai retornar um erro registrado no registro de extensão:

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

    Isso também pode ocorrer para JSON de configuração incorreto no elemento <Input> da política. Em algumas extensões, uma parte do JSON é processada pela extensão e outra é transmitida ao recurso. Por exemplo, o JSON de configuração da extensão do Cloud Logging inclui um objeto metadata cujo conteúdo é transmitido ao Cloud Logging. Nomes de chave incorretos, como typ em vez de type, podem retornar erros do recurso externo que aparecem como entradas no registro da extensão:

    details: 'Resource type cannot be empty'

  • Valores incorretos avaliados pela extensão

    Esses erros incluem erros de sintaxe em partes avaliadas pela política do JSON do elemento <Input>, erros de ortografia no nome da ação no elemento <Action> e assim por diante. Esses erros geralmente aparecem na ferramenta de rastreamento, mas não nos registros de extensão.

Evidências na ferramenta Trace

No editor de proxy, esses erros normalmente aparecem como um erro de nível 4xx ou 5xx. No entanto, o editor de proxy não mostra detalhes sobre a causa do erro, apenas que a extensão retornou um erro. O erro a seguir aparece na ferramenta Trace quando o nome da ação é escrito incorretamente na extensão do Cloud Firestore.

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

Evidências nos registros de extensão

Quando a configuração da política resulta em um erro de processamento no recurso externo, o erro geralmente aparece no registro.

Esse é um erro em que a solicitação ao recurso externo não teve êxito por motivos não relacionados à extensão.

Por exemplo, imagine que você está usando a extensão do Cloud Spanner para adicionar uma linha ao banco de dados, mas o valor da chave primária da linha já foi usado em uma linha existente. O Cloud Spanner vai retornar um erro para a extensão, que vai adicionar o erro ao registro da extensão.

Evidências na ferramenta Trace

No editor de proxy, esses erros geralmente aparecem como um erro de nível 4xx ou 5xx. No entanto, o editor de proxy não mostra detalhes sobre a causa do erro, apenas que a extensão retornou um erro.

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

Evidências nos registros de extensão

O registro geralmente tem entradas com mensagens do próprio recurso externo. A mensagem de registro a seguir do Cloud Spanner descreve o erro de valor da chave primária.

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