Solução de problemas de registros da Apigee ausentes do Cloud Logging

Esta é a documentação da Apigee e da Apigee híbrida.
Não há documentação equivalente do Apigee Edge para esse tópico.

Sintoma

Enviar registros da API Apigee para o Cloud Logging é um caso de uso comum. Geralmente, isso é feito com a política MessageLogging ou ServiceCallout. Em ambos os casos, a Apigee usa a API Cloud Logging para gravar os registros.

Em alguns casos, talvez você não veja os registros da API Apigee no Cloud Logging.

Mensagem de erro

Nenhuma mensagem de erro exibida.

Causas possíveis

Causa	Descrição	Instruções de solução de problemas aplicáveis para
A API Cloud Logging não está ativada	Verifique se você ativou a API Cloud Logging no projeto do Google Cloud da sua organização da Apigee.	Apigee e Apigee híbrida
Conta de serviço proxy configurada incorretamente	A conta de serviço usada no momento da implantação (Apigee) ou na configuração do ambiente de execução (Apigee híbrida) pode ter sido excluída ou configurada incorretamente.	Apigee e Apigee híbrida
Nome de projeto incorreto na configuração da política	O nome do projeto na configuração da política não é o mesmo associado à organização da Apigee.	Apigee e Apigee híbrida
Funções/permissões ausentes na conta de serviço do ambiente de execução	Para a Apigee híbrida, verifique se a conta de serviço do ambiente de execução tem o papel Criador de token de conta de serviço. Isso é obrigatório para usar a autenticação do Google.	Apigee híbrido
O tamanho da entrada de registro excede o limite permitido do Cloud Logging	O Cloud Logging tem um limite de tamanho de entrada de 256 KB que não pode ser alterado.	Apigee e Apigee híbrida
Exaustão da cota de solicitações de gravação por minuto da API Cloud Logging	Não exceda o valor da cota de solicitações de gravação por minuto da API Cloud Logging no seu projeto do Google Cloud.	Apigee e Apigee híbrida

Causa: a API Cloud Logging não está ativada

Diagnóstico

Verifique se a API Cloud Logging está ativada. Consulte Listar serviços ativados para instruções sobre como listar APIs e serviços ativados no console do Google Cloud.

Resolução

Se a API Cloud Logging não estiver ativada, siga as etapas em Como ativar serviços. Pode levar alguns minutos para ativar a API.

Se não for possível resolver o problema em que os registros não são vistos no Cloud Logging porque a API Cloud Logging não está ativada, consulte Precisa coletar informações de diagnóstico.

Causa: conta de serviço de proxy configurada incorretamente

Diagnóstico

Apigee

Encontrar o nome da conta de serviço.

Como usar a IU da Apigee:
1. Clique em Desenvolver > Proxies de API e no nome de um proxy. Por exemplo, TurboBooks.
2. Em Implantações, o nome da Conta de serviço é exibido.

Como usar a API Apigee:

Emita a seguinte chamada da API Apigee:

curl -H "Authorization: Bearer $(gcloud auth print-access-token)" "https://apigee.googleapis.com/v1/organizations/ORG_NAME/environments/ENV_NAME/apis/PROXY_NAME/revisions/REVISION_NUMBER/deployments"

Substitua:

ORG_NAME: o nome da organização. Por exemplo, apigee-example-org.
ENV_NAME: o nome do ambiente. Por exemplo, myenv.
PROXY_NAME: o nome do proxy. Por exemplo, TurboBooks.
REVISION_NUMBER: o número da revisão. Por exemplo, 4.

Exemplo:

curl -H "Authorization: Bearer $(gcloud auth print-access-token)" "https://apigee.googleapis.com/v1/organizations/apigee-example-org/environments/myenv/apis/TurboBooks/revisions/4/deployments"

Algo semelhante ao seguinte é retornado:

{
  "environment": "myenv",
  "apiProxy": "TurboBooks",
  "revision": "4",
  "deployStartTime": "1687408163394",
  "state": "READY",
  "instances": [
    {
      "instance": "apiginstance",
      "deployedRevisions": [
        {
          "revision": "4",
          "percentage": 100
        }
    .
    .
    .
    .
  "serviceAccount": "projects/-/serviceAccounts/envsa-79@apigee-example-org.iam.gserviceaccount.com"
}

Em que serviceAccount é a conta de serviço associada ao proxy de API.

Verifique o seguinte nesta conta de serviço de proxy:
1. Essa conta de serviço precisa estar no mesmo projeto do Google Cloud usado para criar sua organização da Apigee. Por exemplo: apigee-example-org.
2. O usuário que implanta o proxy tem a permissão iam.serviceAccounts.actAs nessa conta de serviço.
  - Para uma lista de papéis, consulte Papéis de contas de serviço.
  - Para ver instruções sobre como visualizar os papéis de um usuário específico, consulte Ver acesso atual.
3. A conta de serviço do proxy tem as permissões necessárias para chamar o serviço do Cloud Logging.
  - Para conferir uma lista de papéis, consulte Papéis do Logging.
  - Para ver instruções sobre como visualizar as permissões da conta de serviço de proxy, consulte Visualizar acesso atual.

Apigee híbrido

Para a Apigee híbrida, além das etapas listadas na Apigee, abra o arquivo overrides.yaml e verifique se há uma conta de serviço especificada em cada ambiente que exige Autenticação do Google. Exemplo:

envs:
  - name: "ENVIRONMENT_NAME"
    serviceAccountPaths:
      runtime: "KEY_FILE_PATH"

Substitua:

ENVIRONMENT_NAME: o nome do ambiente. Por exemplo, myenv.
KEY_FILE_PATH: o caminho para o arquivo de chave da conta de serviço do ambiente de execução. Você normalmente teria criado a conta de serviço em Criar contas de serviço durante a instalação.

Resolução

Se a conta de serviço não estiver no mesmo projeto do Google Cloud usado para criar sua organização da Apigee, uma conta de serviço precisará ser criada no mesmo projeto do Google Cloud e usada. Isso também é mencionado em Como usar a autenticação do Google.
Se o usuário que implanta o proxy não tiver a permissão iam.serviceAccounts.actAs nessa conta de serviço, consulte Conceder um único papel.
Se a conta de serviço de proxy não tiver as permissões necessárias para chamar o serviço do Cloud Logging, consulte Conceder um único papel.

Se as etapas neste documento não resolverem o problema em que a conta de serviço de proxy está configurada incorretamente para a Apigee e a Apigee híbrida, consulte Precisa coletar informações de diagnóstico.

Causa: nome incorreto do projeto na configuração da política

Diagnóstico

Se você estiver usando a política MessageLogging para enviar registros ao Cloud Logging:

Na IU da Apigee, clique na guia Desenvolver > Proxies de API > Nome do proxy da API > Desenvolver.
No painel Código, localize o elemento <CloudLogging>.
Verifique se o valor <LogName> é o nome correto do projeto:
```
<CloudLogging>
  <LogName>projects/PROJECT_ID/logs/LOG_ID</LogName>
</CloudLogging>
```
Substitua:
- PROJECT_ID: o ID do projeto do Google Cloud. Por exemplo, apigee-example-org.
- LOG_ID: o ID do registro do Cloud Logging. Por exemplo, apigee-logs.

Resolução

Se o valor no elemento <LogName> não tiver o valor correto, atualize-o para o valor correto.

Se as etapas deste documento não resolverem o problema, consulte Precisa coletar informações de diagnóstico.

Causa: papéis/permissões ausentes na conta de serviço do ambiente de execução

Diagnóstico

Verifique se o ambiente de execução é capaz de representar a conta de serviço de proxy.

Execute o comando gcloud a seguir para verificar se a conta de serviço do ambiente de execução tem o papel iam.serviceAccountTokenCreator na conta de serviço de proxy:

gcloud iam service-accounts get-iam-policy PROXY_SA_NAME@PROJECT_ID.iam.gserviceaccount.com

Substitua:

PROXY_SA_NAME: o nome da conta de serviço do proxy. Por exemplo, envsa-79.
PROJECT_ID: o ID do projeto do Google Cloud. Por exemplo, apigee-example-org.

Algo semelhante ao seguinte é retornado:

- members:
  - serviceAccount:RUNTIME_SA_NAME@PROJECT_ID.iam.gserviceaccount.com
  role: roles/iam.serviceAccountTokenCreator

Substitua:

RUNTIME_SA_NAME: o ID da conta de serviço do ambiente de execução. Por exemplo, apigee-runtime.

Exemplo:

gcloud iam service-accounts get-iam-policy envsa-79@apigee-example-org.iam.gserviceaccount.com
  bindings:
  - members:
    - user:222larabrown@gmail.com
    role: roles/iam.serviceAccountAdmin
  - members:
    - serviceAccount:apigee-runtime@apigee-example-org.iam.gserviceaccount.com
    role: roles/iam.serviceAccountTokenCreator
  - members:
    - user:222larabrown@gmail.com
    role: roles/iam.serviceAccountUser
  etag: BwX-shcrL3o=
  version: 1

Se você não vir o papel iam.serviceAccountTokenCreator e o membro esperado na saída, siga as etapas em Resolução para conceder os papéis corretos.

Resolução

Conceda à conta de serviço do ambiente de execução o papel iam.serviceAccountTokenCreator na conta de serviço de proxy executando o seguinte comando gcloud:

gcloud iam service-accounts add-iam-policy-binding \
PROXY_SA_NAME@PROJECT_ID.iam.gserviceaccount.com \
--member=serviceAccount:RUNTIME_SA_NAME@PROJECT_ID.iam.gserviceaccount.com \
--role=roles/iam.serviceAccountTokenCreator

Substitua:

PROXY_SA_NAME: o nome da conta de serviço do proxy. Por exemplo, envsa-79.
PROJECT_ID: o ID do projeto do Google Cloud. Por exemplo, apigee-example-org.
RUNTIME_SA_NAME: o ID da conta de serviço do ambiente de execução. Por exemplo, apigee-runtime.

Se as etapas deste documento não resolverem o problema, consulte Precisa coletar informações de diagnóstico.

Causa: tamanho da entrada de registro que excede o limite de registro permitido

Diagnóstico

Se você não vir alguns dos registros aparecendo no Cloud Logging depois de garantir que as outras causas descritas neste documento não são o problema, é possível que o tamanho de algumas das entradas de registro enviadas da Apigee excedam 256 KB, que é o limite absoluto para uma entrada de tamanho de registro no Cloud Logging. Consulte Limites de uso do Logging para mais informações.

Resolução

Esse é um limite não configurável configurado no Cloud Logging e a única solução alternativa conhecida atualmente é manter o tamanho da entrada de registro enviado da Apigee abaixo de 256 KB. Se você estiver registrando um payload com potencial para exceder esse limite, não o registre ou algumas transações não serão registradas quando o limite for atingido.

Se as etapas deste documento não resolverem o problema, consulte Precisa coletar informações de diagnóstico.

Causa: esgotamento da cota de solicitações de gravação por minuto da API Cloud Logging

Diagnóstico

Às vezes, os clientes conseguem ver a solicitação na sessão de depuração, mas, ao mesmo tempo, a solicitação não é registrada no Explorador de registros, apesar de estar presente nos registros do Load Balancer.

A perda de mensagens observada pode ser atribuída ao esgotamento de cota no projeto. A API Cloud Logging aplica um limite de taxa de 120.000 solicitações de gravação por minuto. Exceder essa cota pode resultar em quedas de mensagens. Para mais informações, consulte Visualizar e gerenciar cotas.

Essas cotas podem ser aumentadas no console do Google Cloud, e isso pode ser feito pelo próprio cliente seguindo a documentação de aumento de cota.

Resolução

Siga o procedimento abaixo para aumentar uma cota:

Na página Cotas use as caixas de seleção para marcar API Cloud Logging e, em seguida, clique em Editar cotas. Se você receber o erro Edit is not allowed for this quota, entre em contato com o Google Cloud Customer Care para solicitar alterações na cota. O faturamento precisa estar ativado no projeto do Google Cloud para que você possa clicar nas caixas de seleção.
No painel "Alterações de cota", selecione o serviço para expandir a visualização e preencha os campos Novo limite e descrição da solicitação. Clique em Next.
Preencha o formulário no painel Detalhes do contato e clique em Enviar solicitação.

Para mais informações, consulte a documentação sobre cotas e limites.

É necessário coletar informações de diagnóstico

Se o problema persistir mesmo depois de seguir as instruções acima, colete as seguintes informações de diagnóstico e entre em contato com o Cloud Customer Care:

Organização da Apigee.
O ambiente e o proxy de API veem o problema.
Download da sessão de depuração (com todas as informações acima).
O nome específico da política no proxy de API que está enviando registros para o Cloud Logging.
Para a Apigee híbrida: o arquivo overrides.yaml.