As traduções são geradas por tradução automática. Em caso de conflito entre o conteúdo da tradução e da versão original em inglês, a versão em inglês prevalecerá.
# Encontre a causa de uma falha na criação de imagem com contexto de falha
Quando a criação de uma imagem falha, o Image Builder relata a falha na imagem`state`. O estado carrega uma mensagem que descreve a falha e o **contexto estruturado da falha** em`failureContext`. `reason`
O contexto de falha é um conjunto de campos que nomeia o fluxo de trabalho, a etapa do fluxo de trabalho, a etapa do componente e as regiões de destino envolvidas na falha. Como os campos são estruturados, sua automação pode se ramificar diretamente neles e você pode passar seus valores para outras operações da API Image Builder para obter mais detalhes.
O Image Builder retorna o contexto de falha das operações de [GetImage[ListImageBuildVersions](https://docs.aws.amazon.com/imagebuilder/latest/APIReference/API_ListImageBuildVersions.html)](https://docs.aws.amazon.com/imagebuilder/latest/APIReference/API_GetImage.html), e [ListImagePipelineImages](https://docs.aws.amazon.com/imagebuilder/latest/APIReference/API_ListImagePipelineImages.html)da API e o exibe no Image Builder Console de gerenciamento da AWS.
**Topics**
+ [O que o contexto de falha contém](#image-failure-context-fields)
+ [Exibir o contexto de falha de uma imagem com falha](#image-failure-context-view)
+ [Rastreie uma falha até sua causa raiz](#image-failure-context-rca)
+ [Use o contexto de falha com agentes de IA](#image-failure-context-ai)
+ [Considerações](#image-failure-context-considerations)
## O que o contexto de falha contém
O contexto de falha descreve uma falha em três níveis. Cada membro é opcional, e o Image Builder retorna somente os membros que se aplicam à falha. Para os membros, seus tipos e suas restrições, consulte [ImageState](https://docs.aws.amazon.com/imagebuilder/latest/APIReference/API_ImageState.html)a Referência da API *EC2 Image* Builder.
A imagem
Em qual estágio a imagem estava quando falhou e em qual fluxo de trabalho e etapa do fluxo de trabalho estavam em execução. Os identificadores do fluxo de trabalho e da execução da etapa têm os mesmos valores que [ListWorkflowStepExecutions](https://docs.aws.amazon.com/imagebuilder/latest/APIReference/API_ListWorkflowStepExecutions.html)e [GetWorkflowStepExecution](https://docs.aws.amazon.com/imagebuilder/latest/APIReference/API_GetWorkflowStepExecution.html)assumem, então você pode passá-los diretamente para essas operações.
A etapa do componente
Para uma falha de compilação ou teste causada por um componente, o componente executado, a fase e a etapa em seu documento, o módulo de AWSTOE ação que a etapa executou e o erro relatado pela etapa. O Image Builder identifica o componente por versão de compilação, então ele nomeia a revisão exata que foi executada mesmo quando sua receita faz referência a uma versão curinga. Para os módulos de ação, consulte[Módulos de ação suportados por AWSTOE gerenciador de componentes](toe-action-modules.md).
As regiões de destino
Para uma falha de distribuição ou integração, um erro resumido para a distribuição como um todo e uma entrada para cada destino que falhou. Cada entrada contém a forma como a distribuição terminou ali, o erro do serviço que o Image Builder chamou e, para uma distribuição entre contas, o destino para o Conta da AWS qual o Image Builder distribuiu. Quando a cópia da AMI foi bem-sucedida, mas uma etapa posterior não foi bem-sucedida, a entrada também nomeia essa etapa — associar configurações de licença, atualizar modelos de execução, colocar parâmetros de SSM, atualizar as configurações do Amazon EC2 Fast Launch ou exportar a AMI. Os destinos bem-sucedidos são omitidos.
**nota**
Os membros retornados pelo Image Builder dependem do progresso da construção. Uma falha que ocorre antes do Image Builder iniciar um fluxo de trabalho não tem um fluxo de trabalho para nomear. Por exemplo, se a imagem principal em sua receita não existir mais, o contexto de falha identifica o estágio e nada mais.
Os exemplos [Exibir o contexto de falha de uma imagem com falha](#image-failure-context-view) mostram os membros que o Image Builder retorna em caso de falha de componente e falha de distribuição.
## Exibir o contexto de falha de uma imagem com falha
**Visualize o contexto da falha no console do Image Builder**
O Image Builder exibe os detalhes da falha de uma imagem sempre que exibe o status `Failed` da imagem.
1. Abra o console [https://console.aws.amazon.com/imagebuilder/](https://console.aws.amazon.com/imagebuilder/)do EC2 Image Builder em.
1. Escolha **Imagens** no painel de navegação e, em seguida, escolha a versão de criação da imagem com falha. Você também pode abrir a lista **de imagens de saída** para um pipeline.
1. Escolha o status `Failed` da imagem. O Image Builder exibe os detalhes da falha da imagem e vincula a etapa do fluxo de trabalho com falha aos detalhes do tempo de execução.
**Obtenha o contexto da falha com o AWS CLI**
Execute o **get-image** comando com o ARN da versão de compilação da imagem com falha.
```
aws imagebuilder get-image \
--image-build-version-arn arn:aws:imagebuilder:{{us-west-2}}:{{123456789012}}:image/{{my-example-recipe}}/1.0.0/1 \
--query "image.state"
```
O exemplo de saída a seguir mostra uma compilação que falhou porque uma etapa do componente executou um script que saiu com um status diferente de zero.
```
{
"status": "FAILED",
"reason": "Workflow Execution ID: 'wf-a1b2c3d4-5678-90ab-cdef-EXAMPLE11111' failed with reason: Document arn:aws:imagebuilder:us-west-2:123456789012:component/my-example-component/1.0.0/1 failed!",
"failureContext": {
"imageStatus": "BUILDING",
"workflowExecutionId": "wf-a1b2c3d4-5678-90ab-cdef-EXAMPLE11111",
"workflowArn": "arn:aws:imagebuilder:us-west-2:aws:workflow/build/build-image/{{x.x.x/x}}",
"stepExecutionId": "step-a1b2c3d4-5678-90ab-cdef-EXAMPLE22222",
"failedStep": "ApplyBuildComponents",
"componentFailure": {
"componentArn": "arn:aws:imagebuilder:us-west-2:123456789012:component/my-example-component/1.0.0/1",
"phaseName": "build",
"stepName": "InstallPackages",
"action": "ExecuteBash",
"errorMessage": "exit status 1"
}
}
}
```
O próximo exemplo de saída mostra uma imagem que foi criada e testada com sucesso e, em seguida, falhou enquanto o Image Builder atualizava os modelos de execução em três regiões de destino. A construção foi bem-sucedida em todos os outros destinos, então somente as três regiões que falharam aparecem.
```
{
"status": "FAILED",
"reason": "Integration failed with JobId 'a1b2c3d4-5678-90ab-cdef-EXAMPLE33333', status = 'Failed' for ARN 'arn:aws:imagebuilder:us-west-2:123456789012:image/my-example-recipe/1.0.0/1'. …",
"failureContext": {
"imageStatus": "INTEGRATING",
"distributionFailure": {
"errorMessage": "In region 'eu-west-1' - 'EC2 Client Error: 'The launch-template ID 'lt-0a1b2c3d4EXAMPLE' does not exist'' …",
"regionFailures": [
{
"region": "eu-west-1",
"status": "FAILED",
"imageConfigurationStep": "UPDATE_LAUNCH_TEMPLATES",
"errorMessage": "EC2 Client Error: 'The launch-template ID 'lt-0a1b2c3d4EXAMPLE' does not exist'"
},
{
"region": "us-east-1",
"status": "FAILED",
"imageConfigurationStep": "UPDATE_LAUNCH_TEMPLATES",
"errorMessage": "EC2 Client Error: 'The launch-template ID 'lt-1a2b3c4d5EXAMPLE' does not exist'"
},
{
"region": "us-east-2",
"status": "FAILED",
"imageConfigurationStep": "UPDATE_LAUNCH_TEMPLATES",
"errorMessage": "EC2 Client Error: 'The launch-template ID 'lt-2a3b4c5d6EXAMPLE' does not exist'"
}
]
}
}
}
```
Para encontrar as compilações com falha em uma conta sem inspecionar cada uma, liste as versões de compilação da imagem e filtre o status da imagem. O exemplo a seguir retorna as compilações com falha de uma imagem, com o contexto de falha de cada uma.
```
aws imagebuilder list-image-build-versions \
--image-version-arn arn:aws:imagebuilder:{{us-west-2}}:{{123456789012}}:image/{{my-example-recipe}}/1.0.0 \
--query "imageSummaryList[?state.status=='FAILED'].[arn, state.failureContext]"
```
## Rastreie uma falha até sua causa raiz
O contexto de falha reduz a falha a uma única etapa. Use as etapas a seguir para ir dessa etapa até a evidência que a explica.
1. **Leia `imageStatus` para encontrar o estágio que falhou.** Um valor de `BUILDING` ou `TESTING` significa que a falha ocorreu na instância do Amazon EC2 que o Image Builder lançou, portanto, os registros do componente são o próximo local a ser examinado. Um valor de `DISTRIBUTING` ou `INTEGRATING` significa que a imagem foi criada e a falha está em suas configurações de distribuição ou em uma conta de destino ou.
1. **Leia o membro que descreve a falha específica.** Se `componentFailure` estiver presente, ele identifica a etapa com falha no documento do componente, junto com a ação que a etapa executou e o erro relatado. Se `distributionFailure` estiver presente, cada entrada `regionFailures` fornece um destino e seu próprio erro.
1. **Inspecione os detalhes do tempo de execução do fluxo de trabalho.** Ligue `workflowExecutionId` para ver cada etapa do fluxo de trabalho e onde a etapa [ListWorkflowStepExecutions](https://docs.aws.amazon.com/imagebuilder/latest/APIReference/API_ListWorkflowStepExecutions.html)com falha se enquadra na sequência. Ligue [GetWorkflowStepExecution](https://docs.aws.amazon.com/imagebuilder/latest/APIReference/API_GetWorkflowStepExecution.html)`stepExecutionId`para saber as entradas, saídas e o status de reversão da própria etapa com falha.
O exemplo a seguir lista as etapas de uma falha na execução do fluxo de trabalho.
```
aws imagebuilder list-workflow-step-executions \
--workflow-execution-id wf-{{a1b2c3d4-5678-90ab-cdef-EXAMPLE11111}}
```
1. **Leia os registros da etapa que falhou.** Use `workflowExecutionId` e `failedStep` para ir diretamente para o caminho de registro dessa etapa. Para obter mais informações, consulte [Obtenha a saída completa do componente a partir dos registros](#image-failure-context-logs).
1. **Reproduza a falha, se necessário.** Para manter a instância de compilação em execução para que você possa se conectar a ela, limpe a configuração **Encerrar instância em caso de falha** na configuração de infraestrutura que seu pipeline usa. Para obter mais informações, consulte [Solucionar problemas em compilação de pipelines](troubleshooting.md#troubleshooting-pipelines).
### Obtenha a saída completa do componente a partir dos registros
O contexto de falha relata o erro que uma etapa do componente gerou, mas não a saída padrão e o erro padrão do script que a etapa executou. O Image Builder mantém essa saída nos registros do componente.
Quando um componente falha, AWSTOE grava os detalhes da primeira etapa com falha no log do console, seguido pela saída de erro padrão completa dessa etapa.
```
Document: MyExampleDocument
ComponentArn: arn:aws:imagebuilder:us-west-2:123456789012:component/my-example-component/1.0.0/1
Phase: build
Step: InstallPackages
Action: ExecuteBash
ErrorMessage: exit status 1
Stderr: {{the full standard error output of the step}}
```
`ComponentArn`é o mesmo valor que `componentFailure.componentArn` relata, então use-o para combinar o bloco de log com o contexto de falha de uma imagem. `Document`é o `name` que o documento do componente declara, que o autor escolhe independentemente do recurso do componente, para que os dois possam diferir e, por `Document` si só, não identifique qual componente falhou.
AWSTOE grava `ErrorMessage` e `Stderr` somente quando a etapa falhada as produziu.
O Image Builder transmite os registros do componente para o Amazon CloudWatch Logs quando a compilação é concluída. Se você especificou um bucket do Amazon S3 em sua configuração de infraestrutura, o Image Builder também os grava lá. Para os nomes do grupo de registros e do stream, consulte[Monitore os registros do Image Builder com o Amazon CloudWatch Logs](monitor-cwlogs.md). Para os arquivos que AWSTOE produz e o que cada um contém, consulte[Registro em log do componente](toe-use-documents.md#component-logging).
## Use o contexto de falha com agentes de IA
O contexto de falha foi projetado para ser lido pela automação e também pelas pessoas. Um agente de IA que soluciona problemas de uma compilação com falha lê os campos nomeados e usa seus valores como argumentos para a próxima chamada de API que fizer. Isso torna o diagnóstico repetível e impede o agente de adivinhar qual componente ou investigar.
Você pode usar o contexto de falha de uma das seguintes formas:
+ **Solução de problemas no Image Builder Console de gerenciamento da AWS** — O recurso de solução de problemas, desenvolvido pelo AWS DevOps Agent, usa o contexto de falha para direcionar sua investigação até a etapa e o componente do fluxo de trabalho que falharam antes de examinar os registros e os recursos relacionados. Para obter mais informações, consulte [Solucione problemas de compilações com falha com IA - Pré-visualização](devops-agent-troubleshooting.md).
+ **Seu próprio agente de codificação de IA** — Um agente que liga `GetImage` recebe o contexto de falha na resposta e pode segui-la da mesma maneira. Para dar ao seu agente o conhecimento mais amplo do Image Builder de que ele precisa para agir de acordo com o que encontra, consulte[Solucione problemas de compilações com um agente de codificação de IA](agent-toolkit-skill.md).
Se você criar sua própria automação no contexto de falha, trate cada membro como opcional e verifique os membros que você usa, e não a presença de `failureContext` si mesmo. Os membros retornados pelo Image Builder dependem da falha, e o Image Builder pode adicionar membros ao longo do tempo.
## Considerações
Observe o seguinte ao usar o contexto de falha:
+ O Image Builder retorna o contexto de falha somente para imagens que falharam. Uma imagem bem-sucedida e uma imagem que você cancelou não a têm.
+ Uma imagem com falha carrega `reason` os dois`failureContext`. Use `reason` para obter um resumo legível da falha e `failureContext` localizá-la.
+ Se um componente usa a `ExecuteDocument` ação para executar um documento aninhado, o contexto de falha identifica o componente que o Image Builder executou a partir da sua receita, não o documento aninhado.
+ As mensagens de erro no contexto de falha são limitadas em comprimento e podem ser truncadas. Os registros do componente contêm a saída completa.
+ O contexto da falha relata a primeira etapa que falhou. Se mais de uma etapa falhar, revise as execuções das etapas do fluxo de trabalho e os registros dos componentes para o restante.
+ As mensagens de erro podem conter texto produzido por um componente ou outro AWS serviço. Trate-os como entrada não confiável se você os renderizar ou passá-los para outro sistema.