Instrumente apps Python para o Error Reporting

Pode enviar relatórios de erros para o Error Reporting a partir de aplicações Python usando a biblioteca Error Reporting para Python. Use a biblioteca Error Reporting para Python para criar grupos de erros nos seguintes casos:

  • Um contentor de registos que contém as suas entradas de registo tem chaves de encriptação geridas pelo cliente (CMEK).
  • O contentor de registos cumpre um dos seguintes requisitos:
    • O contentor de registos é armazenado no mesmo projeto onde as entradas de registo tiveram origem.
    • As entradas de registo foram encaminhadas para um projeto e, em seguida, esse projeto armazenou essas entradas de registo num contentor de registos que lhe pertence.
  • Quer criar relatórios de eventos de erro personalizados.

O Error Reporting está integrado com alguns Google Cloud serviços, como o Cloud Functions e o App Engine, o Compute Engine e o Google Kubernetes Engine. O Error Reporting apresenta os erros registados no Cloud Logging por aplicações em execução nesses serviços. Para mais informações, aceda a Executar em Google Cloud nesta página.

Também pode enviar dados de erros para o Error Reporting através do Logging. Para obter informações sobre os requisitos de formatação de dados, leia o artigo Mensagens de erro de formatação no registo.

Antes de começar

  1. Sign in to your Google Cloud account. If you're new to Google Cloud, create an account to evaluate how our products perform in real-world scenarios. New customers also get $300 in free credits to run, test, and deploy workloads.

  2. In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

    Roles required to select or create a project

    • Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
    • Create a project: To create a project, you need the Project Creator (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

    Go to project selector

  3. Verify that billing is enabled for your Google Cloud project.

  4. Enable the Error Reporting API .

    Roles required to enable APIs

    To enable APIs, you need the Service Usage Admin IAM role (roles/serviceusage.serviceUsageAdmin), which contains the serviceusage.services.enable permission. Learn how to grant roles.

    Enable the API

  5. In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

    Roles required to select or create a project

    • Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
    • Create a project: To create a project, you need the Project Creator (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

    Go to project selector

  6. Verify that billing is enabled for your Google Cloud project.

  7. Enable the Error Reporting API .

    Roles required to enable APIs

    To enable APIs, you need the Service Usage Admin IAM role (roles/serviceusage.serviceUsageAdmin), which contains the serviceusage.services.enable permission. Learn how to grant roles.

    Enable the API

    8.
  8. Prepare o seu ambiente para o desenvolvimento em Python.

    Aceda ao guia de configuração do Python

    9. Instale a biblioteca de cliente

    A biblioteca Error Reporting para Python permite-lhe monitorizar e ver erros comunicados por aplicações Python executadas em praticamente qualquer lugar.

    1. Instancie um ambiente virtual e use pip para instalar o pacote:

      pip install google-cloud-error-reporting --upgrade

    2. Importe a biblioteca e instancie um cliente para começar a comunicar erros:

      Python

      Para se autenticar no Relatório de erros, configure as Credenciais padrão da aplicação. Para mais informações, consulte o artigo Configure a autenticação para um ambiente de desenvolvimento local. 

      #!/usr/bin/env python
#
# Copyright 2022 Google, Inc.
#
# Licensed under the Apache License, Version 2.0 (the "License");
# you may not use this file except in compliance with the License.
# You may obtain a copy of the License at
#
#    http://www.apache.org/licenses/LICENSE-2.0
#
# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS,
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
# See the License for the specific language governing permissions and
# limitations under the License.


def report_exception():
    from google.cloud import error_reporting

    client = error_reporting.Client()
    try:
        raise Exception("Something went wrong")
    except Exception:
        client.report_exception()




def report_manual_error():
    from google.cloud import error_reporting

    client = error_reporting.Client()
    client.report("An error has occurred.")




if __name__ == "__main__":
    report_exception()
    report_manual_error()

    Para mais informações sobre a instalação, leia a documentação da biblioteca Error Reporting para Python. Também pode comunicar problemas através do relatório de erros.

    Configure a biblioteca de cliente

    Pode personalizar o comportamento da biblioteca Error Reporting para Python. Consulte a documentação da biblioteca de cliente para ver exemplos de configuração.

    Execute apps no Google Cloud

    Para criar grupos de erros através de projects.events.report, a sua conta de serviço requer a função de escritor do Error Reporting (roles/errorreporting.writer).

    Alguns Google Cloud serviços concedem automaticamente a função de autor de relatórios de erros (roles/errorreporting.writer) à conta de serviço adequada. No entanto, tem de conceder esta função à conta de serviço adequada para alguns serviços.

    Cloud Run e funções do Cloud Run

    A conta de serviço predefinida usada pelo Cloud Run tem as autorizações da função de escritor do Error Reporting (roles/errorreporting.writer).

    A biblioteca Error Reporting para Python pode ser usada sem ter de fornecer explicitamente credenciais.

    O Cloud Run está configurado para usar o Error Reporting automaticamente. As exceções de JavaScript não processadas aparecem no registo e são processadas pelo Error Reporting sem necessidade de usar a biblioteca Error Reporting para Python.

    Ambiente flexível do App Engine

    O App Engine concede automaticamente o papel de escritor do Error Reporting (roles/errorreporting.writer) à sua conta de serviço predefinida.

    A biblioteca Error Reporting para Python pode ser usada sem ter de fornecer explicitamente credenciais.

    Os relatórios de erros são ativados automaticamente para aplicações do ambiente flexível do App Engine. Não é necessária nenhuma configuração adicional.

    Google Kubernetes Engine

    Para usar o Error Reporting com o Google Kubernetes Engine, faça o seguinte:

    1. Certifique-se de que a conta de serviço a ser usada pelo seu contentor tem a função Escritor de relatórios de erros (roles/errorreporting.writer).

      Pode usar a conta de serviço predefinida do Compute Engine ou uma conta de serviço personalizada.

      Para obter informações sobre a concessão de funções, consulte o artigo Faça a gestão do acesso a projetos, pastas e organizações.

    2. Crie o cluster e conceda ao cluster o cloud-platform âmbito de acesso.

      Por exemplo, o seguinte comando create especifica o cloud-platform âmbito de acesso e uma conta de serviço:

      gcloud container clusters create CLUSTER_NAME --service-account  SERVICE_ACCT_NAME --scopes=cloud-platform

    Compute Engine

    Para usar o Error Reporting com instâncias de VM do Compute Engine, faça o seguinte:

    1. Certifique-se de que a conta de serviço a ser usada pela sua instância de VM tem a função de escritor de relatórios de erros (roles/errorreporting.writer).

      Pode usar a conta de serviço predefinida do Compute Engine ou uma conta de serviço personalizada.

      Para obter informações sobre a concessão de funções, consulte o artigo Faça a gestão do acesso a projetos, pastas e organizações.

    2. Na Google Cloud consola, aceda à página Instâncias de VM:

      Aceda a Instâncias de VM

      Se usar a barra de pesquisa para encontrar esta página, selecione o resultado cuja legenda seja Compute Engine.

    3. Selecione a instância de VM que quer receber o cloud-platform âmbito de acesso.

    4. Clique em Parar e, de seguida, em Editar.

    5. Na secção Identidade e acesso à API, selecione uma conta de serviço que tenha a função de escritor do Error Reporting (roles/errorreporting.writer).

    6. Na secção Âmbitos de acesso, selecione Permitir acesso total a todas as APIs Cloud e, de seguida, guarde as alterações.

    7. Clique em Iniciar/Retomar.

    Exemplo

    Pode comunicar manualmente um erro chamando o método report, como se vê no exemplo seguinte:

    Python

    Para se autenticar no Relatório de erros, configure as Credenciais padrão da aplicação. Para mais informações, consulte o artigo Configure a autenticação. 

    #!/usr/bin/env python
#
# Copyright 2022 Google, Inc.
#
# Licensed under the Apache License, Version 2.0 (the "License");
# you may not use this file except in compliance with the License.
# You may obtain a copy of the License at
#
#    http://www.apache.org/licenses/LICENSE-2.0
#
# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS,
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
# See the License for the specific language governing permissions and
# limitations under the License.


def report_exception():
    from google.cloud import error_reporting

    client = error_reporting.Client()
    try:
        raise Exception("Something went wrong")
    except Exception:
        client.report_exception()




def report_manual_error():
    from google.cloud import error_reporting

    client = error_reporting.Client()
    client.report("An error has occurred.")




if __name__ == "__main__":
    report_exception()
    report_manual_error()

    Execute apps num ambiente de programação local

    Para usar a biblioteca Error Reporting para Python num ambiente de desenvolvimento local, como executar a biblioteca na sua própria estação de trabalho, tem de fornecer à biblioteca Error Reporting para Python as credenciais predefinidas da aplicação local. Para mais informações, consulte o artigo Autentique-se no Relatório de erros.

    Para usar os Python exemplos nesta página num ambiente de desenvolvimento local, instale e inicialize a CLI gcloud e, em seguida, configure as Credenciais predefinidas da aplicação com as suas credenciais de utilizador.

      Instale a CLI Google Cloud.

      Se estiver a usar um fornecedor de identidade (IdP) externo, primeiro tem de iniciar sessão na CLI gcloud com a sua identidade federada.

      If you're using a local shell, then create local authentication credentials for your user account: 

      gcloud auth application-default login

      You don't need to do this if you're using Cloud Shell.

      If an authentication error is returned, and you are using an external identity provider (IdP), confirm that you have signed in to the gcloud CLI with your federated identity.

    Para mais informações, consulte Set up authentication for a local development environment.

    O método projects.events.report também suporta chaves da API. Se quiser usar chaves de API para autenticação, não precisa de configurar um ficheiro de Credenciais padrão da aplicação local. Para mais informações, consulte Crie uma chave da API na Google Cloud documentação de autenticação.

    Visualizar relatórios de erros

    Na Google Cloud consola, aceda à página Error Reporting:

    Aceda a Error Reporting

    Também pode encontrar esta página através da barra de pesquisa.

    Para mais informações, consulte o artigo Ver erros.