Diagnosticar o ambiente (novo ou atualizado)

Vários fatores podem criar problemas ao trabalhar com o serviço de agregação, incluindo formatação de relatórios, problemas de domínio de saída e problemas do coordenador. É importante entender a origem do erro e os metadados que ele contém para diagnosticar o problema com precisão.

Tópicos do guia:

• Verificar a configuração da API de medição do cliente
• Resolver problemas na configuração da origem de relatórios
• Resolver problemas com seus relatórios agregados
• Inspecionar a versão da implantação

Verificar a configuração da API Client Measurement

Depois de verificar se o servidor de origem foi registrado corretamente, siga estas etapas:

1. Verifique como você está acionando os relatórios. Confirme se você está recebendo o formato de relatório correto de acordo com a API usada:

   • API Attribution Reporting
     • Para a API Attribution Reporting, verifique se você registrou a origem (Evento e Resumo). Para realizar o registro de acionadores (Evento e Resumo), verifique se o JSON transmitido para Attribution-Reporting-Register-Trigger está correto usando a ferramenta de validação de cabeçalho. (Leia mais sobre os relatórios de resumo da API Attribution Reporting)
   • API Private Aggregation
     • A geração de relatórios na API Private Aggregation pode ser concluída usando a função contributeToHistogram. Verifique se você está transmitindo a chave e o valor do bucket. A chave do bucket precisa estar no formato BigInt. Saiba mais sobre a API Private Aggregation.

2. Se você estiver acionando os relatórios conforme recomendado, mas o problema persistir, verifique se há erros no console para desenvolvedores do Chrome nas guias "Console" e "Rede".

Se você precisar de mais suporte para solução de problemas dessas APIs de cliente, consulte nossas orientações de depuração para a API Attribution Reporting e a API Private Aggregation + armazenamento compartilhado.

Resolver problemas de configuração da origem de relatórios

O servidor de origem de relatórios é onde você declarou os endpoints .well-known correspondentes corretos para onde os relatórios agregáveis serão enviados. Verifique se o servidor de origem de relatórios implantado foi registrado e inscrito corretamente.

Sua origem de relatórios está recebendo relatórios?

Verifique se o servidor de origem de relatórios implantado foi registrado e inscrito corretamente. É nesse servidor que você declarou os endpoints .well-known correspondentes corretos para onde os relatórios agregáveis serão enviados.

Depois de verificar se o servidor de origem foi registrado corretamente, siga estas etapas:

1. Verifique como você está acionando os relatórios. Confirme se você está recebendo o formato de relatório correto de acordo com a API usada:

   • Relatórios de resumo da API Attribution Reporting
   • API Private Aggregation

2. Se você estiver acionando os relatórios conforme recomendado, mas o problema persistir, verifique se há erros no console para desenvolvedores do Chrome nas guias "Console" e "Rede".

Se você precisar de mais suporte para resolver problemas com essas APIs de cliente , siga as orientações de depuração para a API Attribution Reporting e API Private Aggregation + armazenamento compartilhado.

Resolver problemas com seus relatórios agregados

Os relatórios agregados são gerados pelas APIs de medição do lado do cliente e enviados para sua origem de relatórios. Esses relatórios precisam ser convertidos para o formato AVRO pelo endpoint de relatórios. Se houver problemas com essa conversão ou se os relatórios não estiverem intactos, você poderá encontrar erros no serviço de agregação.

Seus relatórios agregáveis estão convertendo corretamente?

Verifique se o endpoint de relatórios (.well-known/…) está convertendo corretamente o relatório JSON agregável em AVRO.

Os erros de API que surgem devido a esse problema são os seguintes:

                "result_info": {
                    "return_code": "REPORTS_WITH_ERRORS_EXCEEDED_THRESHOLD",
                    "return_message": "Aggregation job failed early because the number of reports excluded from aggregation exceeded threshold.",
                    "error_summary": {
                        "error_counts": [
                            {
                                "category": "DECRYPTION_ERROR",
                                "count": 1,
                                "description": "Unable to decrypt the report. This may be caused by: tampered aggregatable report shared info, corrupt encrypted report, or other such issues."
                            },
                            {
                                "category": "NUM_REPORTS_WITH_ERRORS",
                                "count": 1,
                                "description": "Total number of reports that had an error. These reports were not considered in aggregation. See additional error messages for details on specific reasons."
                            }
                        ],
                        "error_messages": []
                    }
                }
            

                "result_info": {
                    "return_code": "REPORTS_WITH_ERRORS_EXCEEDED_THRESHOLD",
                    "return_message": "Aggregation job failed early because the number of reports excluded from aggregation exceeded threshold.",
                    "error_summary": {
                        "error_counts": [{
                            "category": "DECRYPTION_KEY_NOT_FOUND",
                            "count": 1,
                            "description": "Could not find decryption key on private key endpoint."
                        }, {
                            "category": "NUM_REPORTS_WITH_ERRORS",
                            "count": 1,
                            "description": "Total number of reports that had an error. These reports were not considered in aggregation. See additional error messages for details on specific reasons."
                        }],
                        "error_messages": []
                    }
                }
            

                sharedStorage.run('someOperation', {'privateAggregationConfig':
                {'aggregationCoordinatorOrigin': ' https://publickeyservice.msmt.gcp.privacysandboxservices.com'}});

            

                "result_info": {
                        "return_code": "REPORTS_WITH_ERRORS_EXCEEDED_THRESHOLD",
                        "return_message": "Aggregation job failed early because the number of reports excluded from aggregation exceeded threshold.",
                        "error_summary": {
                            "error_counts": [
                                {
                                    "category": "DECRYPTION_KEY_FETCH_ERROR",
                                    "count": 1,
                                    "description": "Fetching the decryption key for report decryption failed. This can happen using an unapproved aggregation service binary, running the aggregation service binary in debug mode, key corruption or service availability issues."
                                },
                                {
                                    "category": "NUM_REPORTS_WITH_ERRORS",
                                    "count": 1,
                                    "description": "Total number of reports that had an error. These reports were not considered in aggregation. See additional error messages for details on specific reasons."
                                }
                            ]
                        }
                }
            

Siga estas etapas para verificar:

1. Use a ferramenta aggregatable_report_converter para converter os relatórios agregáveis coletados do endpoint .well-known para AVRO e criar as chaves de domínio de saída. Observação: os arquivos de domínio de saída precisam ser uma bytestring big-endian de 16 bytes.

2. Siga as etapas do codelab para seu provedor de nuvem pública e colete os relatórios de depuração. Em seguida, execute um job do Serviço de agregação usando as chaves de domínio de saída: a. Google Cloud: siga as etapas 3.1.2 a 3.2.3 do Codelab do serviço de agregação do Google Cloud b. Amazon Web Services: siga as etapas de 4.2 a 5.3 do Codelab do serviço de agregação da AWS.

Se isso retornar uma resposta SUCCESS, sua conversão estará funcionando.

Seus relatórios agregáveis estão intactos?

Verifique se o relatório agregado, as chaves de domínio de saída e as informações compartilhadas estão intactos. Consulte os códigos de amostra para converter relatórios agregáveis e criar arquivos de domínio se quiser mais informações.

Estes são os erros da API que podem aparecer e correspondem a esse problema:

Siga estas etapas para verificar:

1. Verifique o relatório agregado:

   • Gere relatórios agregados e use a ferramenta aggregatable_report_converter para converter o domínio de saída no formato AVRO.
   • Execute uma solicitação createJob com esse relatório agregável e o arquivo de domínio de saída.
   • Se isso retornar SUCCESS, significa que o relatório agregável está intacto. Se isso retornar um erro, você terá um problema com o relatório agregável ou com o relatório e o domínio.
   • Prossiga para verificar o arquivo de domínio na próxima etapa.

2. Verifique o arquivo de domínio de saída:

   • Gere o arquivo de domínio de saída e use a ferramenta aggregatable_report_converter para criar o relatório agregável.
   • Execute uma solicitação createJob com esse relatório agregável e o arquivo de domínio de saída.
   • Se isso retornar SUCCESS, significa que o domínio de saída está intacto e há um problema com seu código para criar o relatório agregável.
   • Continue para a próxima etapa e confira o shared_info.

3. Verifique as informações compartilhadas:

   • Verifique se você ativou os relatórios de depuração. Os relatórios com depuração ativada terão um campo debug_cleartext_payload disponível.
   • Crie um relatório de depuração para uso com a ferramenta de teste local e use debug_cleartext_payload como o payload.
   • Execute a ferramenta de teste local com o arquivo de domínio. Se for um SUCCESS, isso significa que seu arquivo shared_info foi adulterado.

Se você suspeitar de mais erros ou adulterações, colete o relatório agregado JSON, a chave de domínio, o relatório agregado AVRO gerado e o domínio de saída. Em seguida, siga as próximas etapas.

Inspecionar a nova versão de implantação

Verifique se a versão do Serviço de agregação ainda tem suporte. Depois de determinar qual versão você está usando, confira a lista de lançamentos do Serviço de agregação e confirme se a sua versão não tem o aviso de fim do suporte: This release has reached its end of support on { date }. As instruções a seguir para determinar qual versão você implantou são para as nuvens públicas compatíveis.

Etapas para o Google Cloud

1. Acesse Compute Engine > Instâncias de VM.
2. Clique na instância de máquina virtual com -worker- no nome.
3. Encontre a seção Custom Metadata e localize a chave tee-image-reference.
   • Observação: todas as VMs provisionadas no Google Cloud pelo Terraform precisam ter esses metadados (metadados tee-image-reference no módulo de worker).
4. O valor de tee-image-reference vai conter o número da versão. Por exemplo, o número da versão do caminho a seguir é v2.9.1. São imagens pré-criadas que ficam no Artifact Registry de um projeto do Google Cloud.
   • Observação: isso é relevante se você estiver usando os recursos pré-criados. Caso contrário, o nome e as tags da imagem devem corresponder ao que você definiu pessoalmente. Exemplo: us.docker.pkg.dev/<gcp_project_name>/artifacts:aggregation-service- container-artifacts-worker_mp_go_prod:2.9.1

Etapas para o Amazon Web Services

1. Acesse Instâncias do EC2 no console da Amazon Web Services.
2. Clique na instância com o nome aggregation-service-operator-dev-env.
3. Na página da instância, encontre Detalhes > AMI (Amazon Machine Image).
4. O nome da versão precisa estar incluído no caminho da imagem. Por exemplo, o número da versão do caminho a seguir é v2.9.1.
   • Observação: isso é relevante se você estiver usando os recursos pré-criados. Caso contrário, o nome e as tags da imagem devem corresponder ao que você definiu pessoalmente. Exemplo: aggregation-service-enclave_2.9.1--2024-10-03T01-24-25Z

Próximas etapas

Se você não encontrar uma solução para seu problema com o Serviço de agregação, notifique-nos ao registrar um problema no GitHub ou enviar o formulário de suporte técnico.