Como depurar uma extensão

Você está vendo a documentação do Apigee Edge.
Acesse a documentação da Apigee X. informações

É possível depurar uma extensão usando mensagens visíveis em dois locais: na ferramenta Trace e nos registros da extensão. Quando uma extensão não está funcionando, a identificação do problema pode exigir informações dos dois lugares.

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

    Os erros relacionados à extensão que aparecem na ferramenta Trace geralmente não contêm muitos detalhes, exceto dizer qual chamada de extensão falhou, junto com um código de erro HTTP. Quando você não encontrar nada útil aqui, o melhor lugar para procurar é 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 configuradas incorretamente na extensão, o erro provavelmente vai aparecer aqui.

    Os registros também incluem entradas do código interno da extensão. Ao examinar 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 nesta entrada de registro da extensão do 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 ExtensionPor em um proxy de API, pela extensão, para o recurso externo e depois volta novamente. Portanto, um erro pode ocorrer em qualquer um desses lugares.

Os erros que você vê podem se enquadrar nas categorias a seguir.

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 do projeto do Google Cloud incorreto, o Google Cloud Logging retornará um erro para a extensão. Os detalhes desses erros geralmente estão no registro da extensão.

Evidência na ferramenta Trace

No editor de proxy, esses erros geralmente aparecem como um erro no nível 4xx ou 5xx. No entanto, o editor de proxy não mostrará detalhes sobre a causa do erro, exceto para dizer 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ência nos registros de extensão

Se houver detalhes sobre esse tipo de erro, você o verá nas entradas de registro da extensão. A mensagem de erro a seguir, retornada pelo serviço Cloud Pub/Sub, resulta de um ID de projeto incorreto.

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

Erros na configuração da política ExtensionFrase

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

  • Valores incorretos avaliados pelo recurso externo

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

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

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

    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 do nome da ação no elemento <Action> e assim por diante. Esses erros geralmente aparecem na ferramenta Trace, mas não nos registros de extensão.

Evidência na ferramenta Trace

No editor de proxy, esses erros geralmente aparecem como um erro no nível 4xx ou 5xx. No entanto, o editor de proxy não mostrará detalhes sobre a causa do erro, exceto para dizer que a extensão retornou um erro. O erro a seguir aparece na ferramenta Trace ao escrever incorretamente o nome da ação 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ência 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.

Este é um erro em que a solicitação para o recurso externo não foi bem-sucedida por motivos não relacionados à extensão.

Por exemplo, imagine que você esteja 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á esteja sendo usado em uma linha atual. O Cloud Spanner retornará um erro para a extensão, que adicionará o erro ao registro da extensão.

Evidência na ferramenta Trace

No editor de proxy, esses erros normalmente aparecem como um erro no nível 4xx ou 5xx. No entanto, o editor de proxy não exibirá detalhes sobre a causa do erro, exceto para dizer 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ência nos registros de extensão

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

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