Solucionar problemas de Applications

Use esta página quando uma aplicação não trata as requisições da forma como você a configurou, ou quando a Azion API recusa um objeto que pertence a ela. Cada seção nomeia um sintoma, a sua causa e a sua correção, e pode ser lida sozinha. Os sintomas da própria aplicação vêm primeiro, depois os de Cache, Application Accelerator e Image Processor, os Produtos habilitados em uma aplicação.

As requisições nunca chegam à origem

Os clientes enviam requisições ao domínio de um workload, e a sua origem não registra nenhuma delas.

Dois vínculos ligam uma requisição a uma origem. O deployment do workload nomeia a aplicação, e uma regra da Request Phase com Set Connector nomeia o connector que guarda o endereço da origem, já que o registro da aplicação não tem campo para uma origem.

• Nomeie a aplicação no deployment do workload: no Azion Console, selecione-a no campo Application da seção Deployment Settings do workload, ou passe o ID dela à Azion CLI em --application-id:

A CLI imprime Created Workload Deployment with ID <deployment-id>.

• Adicione uma regra que envia as requisições ao connector: uma aplicação nova não tem regras. Crie uma com Set Connector no Azion Console, como mostra Primeiros passos com Applications, ou com set_connector pela API.
• Dê tempo para a mudança se propagar: envie a requisição de novo até a origem recebê-la, pelos tempos que Propagação informa.

As requisições que correspondem à regra então chegam à origem pelo connector, e as respostas da origem voltam ao cliente.

A origem retorna um erro

A sua origem responde a uma requisição com um status 4xx ou 5xx, e o cliente recebe uma página de erro.

O connector que uma regra com Set Connector nomeia recebe o erro da origem. A página de erro é definida no workload, não na aplicação: o deployment dele seleciona a página ao lado da aplicação e do firewall.

• Sirva a sua própria página de erro: crie-a em Custom Pages e selecione-a no campo Custom Page das Deployment Settings do workload, strategy.attributes.custom_page na API.
• Sirva a última cópia armazenada no lugar de um 5xx: ative o Stale cache no cache setting que uma regra com Set Cache Policy aplica ao path.

O cliente então recebe a sua página para um erro da origem, ou a cópia expirada de um objeto em cache dentro da janela de stale.

Uma regra não age sobre as requisições que você espera

Uma regra está salva, e as requisições que ela deveria pegar mantêm o comportamento anterior.

Uma regra age apenas sobre as requisições que correspondem aos seus critérios, e apenas depois que a mudança se propaga. Verifique três causas:

• A regra ainda não se propagou: a API aceita uma regra com 202 e state igual a pending. Envie a requisição de novo antes de alterar a regra, pelo tempo que Propagação descreve.
• Os critérios não correspondem à requisição: Critérios lista cada variável, operador e condicional.
• Uma regra anterior encerrou o processamento: um behavior como Finish Request Phase interrompe os behaviors e as regras depois dele, como explica Como as regras são executadas.

Para distinguir as três, verifique quais regras rodaram na requisição. Debug Rules registra as regras do Rules Engine que rodam em cada requisição, e ele vem desativado em uma aplicação nova.

• Ative Debug Rules: na aba Main Settings da aplicação, ative Debug Rules e selecione Save.
• Leia as regras que rodaram: Debug Rules nomeia o campo que as lista em cada log. Uma regra ausente do log de uma requisição não rodou nela: refaça os critérios dela, ou mova-a para antes da regra que encerrou o processamento.

A regra então aparece no log de cada requisição a que ela corresponde, e os seus behaviors rodam.

Um problema aparece no tráfego, mas não nas respostas que você solicita

Os usuários relatam erros ou respostas lentas, mas cada requisição que você envia à aplicação retorna o que você espera.

Uma requisição que você envia mostra uma resposta, de um servidor, em um momento, como mostra Headers de debug. Um problema que afeta alguns servidores, alguns paths ou algumas horas não aparece em uma única resposta.

• Leia métricas agregadas: Real-Time Metrics mostra em gráficos os dados agregados das suas aplicações e os mantém por períodos de armazenamento mais longos.
• Leia o log bruto de cada requisição: o Real-Time Events guarda os dados brutos de cada requisição.
• Consulte apenas os dados de que você precisa: a GraphQL API retorna dados agregados e brutos, limitados aos campos que uma consulta pede, como mostra Consulte os dados de uso de Applications.
• Rastreie as regras que rodaram: Debug Rules as registra por requisição.

As métricas e os logs então mostram quais requisições, paths ou períodos carregam o problema.

Uma regra é recusada com Missing Required Modules

Salvar uma regra de requisição que lê ${request_uri} falha com 400 e o código 25047 enquanto Application Accelerator está desativado, como Erros mostra por completo.

Algumas variáveis e alguns behaviors pertencem a um Produto, e a API recusa uma regra que use um deles enquanto esse Produto estiver desativado: meta.missing_required_modules nomeia o Produto.

• Use ${uri} no critério em vez disso: ele não exige nenhum Produto, então a mesma regra retorna 202, como Variáveis lista para cada variável.
• Ative o Produto que o erro nomeia: o switch dele fica na seção Modules da aba Main Settings da aplicação, e Save o aplica. Produtos informa a flag da Azion CLI e a key da API dele.

Com Application Accelerator ativado, a regra com ${request_uri} é aceita.

Um behavior é recusado com Invalid Choice

O corpo de uma regra copiado de um exemplo mais antigo falha com 400, o código 10039 e Invalid Choice, que Erros lista com o detalhe e o ponteiro.

A API aceita apenas os tipos de behavior que ela define. O que adiciona um header à requisição é add_request_header, Add Request Header no Azion Console, e não add_header.

• Envie add_request_header: leve o header como name: value em attributes.value, como em { "type": "add_request_header", "attributes": { "value": "Accept: image/webp" } }.
• Procure os outros tipos: Behaviors lista cada behavior e o seu tipo.

A regra então é aceita e, lida de volta, traz o tipo add_request_header.

Uma conexão WebSocket não retorna 101 Switching Protocols

Uma conexão WebSocket pela aplicação retorna um status diferente de 101 Switching Protocols, mesmo um 2xx ou um 3xx.

Apenas 101 significa uma conexão com upgrade: qualquer outro status significa que o cliente, a aplicação ou a origem não a completou.

• Confirme o suporte nativo a WebSocket: o cliente e a origem precisam dele, como exige Suporte no cliente e na origem.
• Envie os dois headers de upgrade: Upgrade: websocket e Connection: upgrade, como exige Headers de upgrade.
• Confirme que a conta pode usar WebSocket Proxy: Disponibilidade informa quem tem acesso.

A conexão então retorna 101 Switching Protocols.

Cache

Toda aplicação nova tem Cache ativado, mas um cache setting altera apenas as requisições às quais uma regra o aplica. Para saber como Cache responde a uma requisição, consulte Como Applications funciona.

Um cache setting salvo não tem efeito e as respostas continuam MISS

x-cache mostra MISS em cada resposta para o path, e a sua origem recebe tantas requisições quanto antes.

Um cache setting salvo age apenas sobre as requisições às quais uma regra da Request Phase já propagada o aplica por meio de Set Cache Policy.

• Aplique o setting com uma regra: adicione Set Cache Policy com o setting a uma regra da Request Phase que cubra o path, como mostra Crie um cache setting.
• Aguarde a propagação da regra: Propagação informa o tempo que ela leva.
• Leia o status de várias requisições: cada uma pode vir de um servidor diferente. Verifique o status de cache de uma resposta mostra como lê-lo.

Com a regra em vigor, a requisição que armazena a cópia informa MISS, e as respostas seguintes, entregues a partir dessa cópia, informam HIT.

O header x-cache informa um traço em cada resposta de um path

Os dois headers de debug trazem um traço, x-cache: - e x-cache-key: -, então a resposta não tem nem status de cache nem key.

O traço marca conteúdo restrito de cache, como lista Status de cache. As respostas GET e HEAD são armazenadas em cache nativamente, enquanto as respostas POST e OPTIONS exigem Application Accelerator e um cache setting que varie pelo seu método.

• Ative Application Accelerator primeiro: com ele desativado, a API recusa o campo do método com o erro 21013. Produtos tem o switch.
• Armazene o método em cache: selecione-o em Cache vary by Method, na seção Application Accelerator do cache setting, que então é lido de volta com "cache_vary_by_method":["post"] para POST. Armazene em cache respostas de POST e OPTIONS tem os passos.
• Distinga os casos pelo método: em um GET ou em um HEAD, o traço vem de outro lugar, como de uma resposta que uma função constrói.

As respostas ao método armazenado em cache então trazem um status, e uma key que termina com um hash MD5 do corpo da requisição.

O conteúdo continua sendo entregue do cache depois de uma regra com Bypass Cache

As requisições que uma regra com Bypass Cache corresponde continuam recebendo uma cópia armazenada, e a origem não as vê.

Bypass Cache alcança o cache da Azion, mas não a camada do Tiered Cache, que mantém os objetos pelo TTL mínimo, então a primeira camada ainda pode responder a partir dela.

• Desative Tiered Cache: na seção Cache do cache setting que atende o path.
• Purgue as duas camadas, a do Tiered Cache primeiro: purgue Tiered Cache por cache key e depois Cache, para que a primeira camada não se encha de novo com uma cópia desatualizada, como mostra Purgue conteúdo em cache.

As requisições que a regra envia à origem então trazem x-cache: BYPASS.

Um purge não expirou uma variação do objeto

O purge foi aceito, mas alguns visitantes, ou algumas query strings, continuam recebendo o conteúdo antigo.

Um purge por URL mapeia cada URL para uma única cache key sem variação, então as cópias que variam por cookie, device group ou formato de imagem sobrevivem a ele, por mais que você o repita. Ele alcança uma variação por query string apenas quando a URL lista os argumentos na ordem em que a key os armazena, alfabética quando Sort está ativado.

• Purgue por cache key: liste cada variação do objeto, no máximo 50 keys em uma requisição, cada uma copiada do header x-cache-key da sua resposta.
• Purgue por wildcard: termine a expressão com @@* para as variações que acrescentam o separador @@, como as por cookie e por device group, ou com ?* para as variações por query string.

Na sua requisição seguinte, cada variação purgada informa x-cache: MISS, como Purgue conteúdo que varia mostra para cada tipo de variação.

Um Max Age menor que 60 segundos é recusado com o erro 21021

Criar ou atualizar um cache setting com um Max Age menor que 60 segundos retorna 400 e o código 21021, como Erros detalha.

Sem Application Accelerator, o piso é de 60 segundos, com Tiered Cache ativado ou desativado. Com ele, um Max Age de 30 ou de 0 é salvo, a menos que Tiered Cache esteja ativado, cujo piso é de 3 segundos.

• Ative Application Accelerator: o switch fica em Main Settings › Modules.
• Mantenha-o desativado e aumente o valor: um Max Age de 60 segundos ou mais é salvo sem ele.

O cache setting então é aceito, dentro dos limites que Limites de Applications lista.

Tiered Cache não pode ser ativado e a API retorna 21001 ou 21020

Um cache setting que envia tiered_cache.enabled como true é recusado com 400: o código 21001 responde ao comportamento de cache honor, e o código 21020 a um Max Age menor que 3 segundos, como Erros detalha para cada um.

Tiered Cache exige o Override cache behavior, override na API, e um Max Age de pelo menos 3 segundos. Com Application Accelerator desativado, o piso de 60 segundos do erro 21021 se aplica primeiro, então de 3 a 59 segundos continua sendo recusado.

• Envie o comportamento e o Max Age em uma requisição: modules.cache.behavior igual a override, com um max_age de pelo menos 3, ou de pelo menos 60 com Application Accelerator desativado.
• Use --file na Azion CLI: nenhuma flag da CLI define o comportamento de cache, então --tiered-caching-enabled sozinho sempre termina em 21001. Este comando grava o corpo em um arquivo e cria o setting a partir dele:

A CLI imprime Created Cache Settings configuration with ID <cache-setting-id>, e o setting é lido de volta com enabled igual a true em tiered_cache. Para as topologias, consulte Tiered Cache.

Um cache setting não pode ser excluído e a API retorna 21014

Um DELETE em um cache setting responde 400 e o código 21014, que Erros lista com o detalhe.

O behavior Set Cache Policy de alguma regra ainda nomeia o setting, e um setting em uso não pode ser removido.

• Libere o setting: na aba Rules Engine, aponte o Set Cache Policy dessa regra para outro setting, ou exclua a regra.
• Exclua-o de novo: com Azion CLI, a exclusão recebe o ID da aplicação e o ID do setting:

Sem nenhuma regra que nomeie o setting, a CLI imprime {"message": "Caches settings configuration <cache-setting-id> was successfully deleted"}, e o setting sai da lista de Cache Settings.

Uma requisição de purge é rejeitada com 30001, 30003 ou 30005

Um purge volta com 400 em vez de 201, com um de três códigos que Erros lista com o detalhe:

Azion CLI informa 30001 com o detalhe da API, como mostra este purge por URL na camada do Tiered Cache:

O comando imprime Error: ["Invalid purge layer for purge type \"url\"."]. Um purge por cache key na mesma camada imprime Purge carried out successfully, e os purges aceitos retornam 201 com state igual a executed, como mostra Corpo da requisição.

Azion CLI imprime um objeto de erro vazio

Um create ou update de cache setting falha, e com --format json a Azion CLI imprime apenas {"error": {}}.

Com saída JSON, Azion CLI 4.23.0 perde o código e o título com que a API respondeu.

• Repita o comando sem --format json: a saída simples traz a mensagem da API, como Error: Failed to create the Cache Settings configuration: ["It's not possible to use this edge cache behavior while using Tiered Cache."] para Tiered Cache com honor.
• Procure a mensagem: nesta página, ou em Erros, que lista todos os códigos do endpoint de cache settings.

Corrija a requisição com esse motivo e envie-a de novo.

Application Accelerator

Application Accelerator decide três coisas em uma aplicação: o que entra em uma cache key, quais métodos HTTP são armazenados em cache e quais behaviors do Rules Engine uma regra pode usar. Ele vem desativado em uma aplicação nova. Para saber como uma variação altera a key, consulte Como Applications funciona.

Uma requisição POST não informa status de cache

Um POST informa - em X-Cache até que Application Accelerator esteja ativado e o cache setting nomeie POST em Cache vary by Method, um campo que HTTP methods lista para cada interface. Para a correção, consulte O header x-cache informa um traço em cada resposta de um path.

Variações por cookie e por device group sobrevivem a um purge

Essas variações vêm da seção Application Accelerator do cache setting, e cada uma é um objeto sob a sua própria key, que um purge por URL nunca alcança. Para o purge por cache key ou pelo wildcard @@* que a alcança, consulte Um purge não expirou uma variação do objeto.

Um purge por URL não alcança uma variação por query string

Um purge por URL alcança uma variação por query string apenas quando lista os argumentos pelos quais a key varia, na ordem em que a key os armazena, que é alfabética quando Sort está ativado em Cache vary by Query String. Para esse purge e o wildcard ?*, consulte Um purge não expirou uma variação do objeto.

Um behavior ou uma variável não pode ser selecionado no Rules Engine

Na aba Rules Engine de uma aplicação, um behavior como Bypass Cache, Forward Cookies ou Rewrite Request não pode ser adicionado a uma regra, e a variável ${device_group} não está disponível nos critérios.

Sete behaviors e a variável ${device_group} ficam bloqueados enquanto Application Accelerator está desativado na aplicação.

• Ative Application Accelerator: o switch fica em Main Settings › Modules.
• Ative Functions para Run Function: Run Function também exige Functions ativado na aplicação, como explica Run Function não aparece na lista de comportamentos.

Uma regra então pode receber os sete behaviors, e os critérios dela podem usar ${device_group}, como Behaviors do Rules Engine lista por fase.

O conteúdo é entregue do cache com Bypass Cache configurado

Bypass Cache exige Application Accelerator, e uma regra que o aplica ainda pode ser respondida pela camada do Tiered Cache, que Bypass Cache não alcança. A regra funciona, então alterá-la não corrige nada: desative Tiered Cache e purgue as duas camadas, como descreve O conteúdo continua sendo entregue do cache depois de uma regra com Bypass Cache.

Uma variação de cache é recusada com o erro 21013

Salvar um cache setting que define um campo da sua seção Application Accelerator retorna 400 e o código 21013, como Erros detalha.

Esses campos, em modules.application_accelerator, variam o cache por método, query string, cookie e device group, e cada um exige Application Accelerator.

• Ative Application Accelerator e depois salve o setting de novo: o switch fica em Main Settings › Modules.
• Leia o motivo quando Azion CLI o esconde: com --format json, Azion CLI 4.23.0 imprime essa recusa como {"error": {}} para um setting com um allowlist de query string, como explica Azion CLI imprime um objeto de erro vazio.

O setting então é salvo, e a sua variação é lida de volta como foi enviada.

Uma variação por query string é recusada com o erro 21018

Um cache setting cujo comportamento de query string é Allowlist ou Denylist, enviado com uma lista de campos vazia, retorna 400 e o código 21018, como Erros detalha.

Esses comportamentos nomeiam os campos pelos quais a key varia, então cada um precisa de pelo menos um, e o Azion Console torna Fields obrigatório.

• Liste os campos: insira pelo menos um parâmetro de query string em Fields, um por linha, ou envie-os em fields pela API.
• Mantenha o padrão quando a key não deve variar: Ignore, o comportamento padrão, é salvo com uma lista fields vazia.

O setting então é salvo, com cache_vary_by_querystring guardando o que você enviou, como Cache variation lista.

Image Processor

Image Processor constrói uma imagem derivada a partir da imagem de origem quando uma regra aplica Optimize Images, e ele vem desativado em uma aplicação nova. Para o caminho da imagem de origem até a imagem derivada, consulte Como Applications funciona.

Um erro 504 em uma requisição cujo ims não é o último parâmetro

Uma requisição de uma imagem retorna um erro 504, e a URL dela tem outro parâmetro de query string depois de ims=.

ims= precisa vir por último entre os parâmetros da URL: um parâmetro depois dele pode fazer a requisição retornar um 504, embora nem toda requisição assim falhe.

• Coloque ims por último: mova os outros parâmetros para antes de ims=, como em example.com/image.jpeg?ts=1234&ims=1000x1000. Para a regra, consulte Posição do parâmetro ims.

Com ims= por último, a URL retorna a imagem derivada, e não um 504.

A imagem é entregue sem processamento e a sua query string ims é ignorada

A query string ims de uma requisição é válida, mas a imagem de origem volta como está, sem redimensionamento, recorte ou filtro.

Uma query string ims não inicia uma transformação sozinha: uma regra precisa corresponder à requisição e aplicar Optimize Images.

• Verifique a que a regra corresponde: na aba Rules Engine, compare o critério da regra com a requisição. Um critério para imagens compara ${uri}, ou ${request_uri} com Application Accelerator ativado, por meio de matches com um argumento como \.(jpg|jpeg|gif|bmp|png|ico|webp|avif).
• Verifique o behavior: Optimize Images precisa ser um behavior da Request Phase da regra, ao lado de Set Cache Policy quando a regra também armazena o resultado em cache, como descreve Behaviors do Rules Engine.
• Siga o guia: Configure Image Processor em uma aplicação constrói a regra passo a passo.

Uma requisição que corresponde à regra então recebe uma imagem derivada, com x-ims: Enabled nos headers de resposta.

A imagem não é convertida para WEBP

Você solicita uma conversão para WEBP, e a imagem chega em outro formato.

Uma conversão para WEBP acontece apenas para uma requisição cujo header Accept nomeia o formato, Accept: image/webp, como exige Conversão de formato.

• Defina o header a partir de uma regra: dê à regra um behavior Add Request Header na Request Phase dela, com o valor Accept: image/webp, add_request_header na API. Para o behavior, consulte Configurações do Image Processor.

As requisições correspondentes então recebem a imagem como image/webp.

Cada requisição para a mesma imagem derivada é processada de novo

Cada requisição para a mesma imagem com o mesmo valor de ims soma uma imagem processada ao medidor de Images da conta, em vez de vir do cache.

Optimize Images processa a imagem, e guardar o resultado exige um cache setting que uma regra aplica com Set Cache Policy. Variar esse setting por ims é uma variação por query string, então exige Application Accelerator, que o processamento não exige.

• Aplique um cache setting às requisições de imagens: adicione Set Cache Policy, com o cache setting que atende as imagens, à regra que aplica Optimize Images.
• Adicione ims ao allowlist de query string: em Cache vary by Query String, na seção Application Accelerator desse setting, escolha Allowlist como Behavior e insira ims em Fields, como descreve Cache variation.

Lido de volta, o cache setting então guarda { "behavior": "allowlist", "fields": ["ims"], "sort_enabled": false } em cache_vary_by_querystring.

Um redimensionamento maior que a original não amplia a imagem

Você pede fit-in/WidthxHeight, ou dimensões além das da imagem de origem, e a imagem derivada volta sem ser maior que a original.

O redimensionamento funciona como projetado, e nenhuma configuração o altera. fit-in não amplia uma imagem, e, sem fit-in, pedir mais resolução do que a original tem retorna a maior resolução que a imagem de origem permite.

O resultado mantém o tamanho da imagem de origem, ou assume o maior tamanho que cabe na caixa solicitada, como Redimensionamento mostra para cada forma.

Um valor de rotação não tem efeito

Com ?ims=filters:rotate(Angle) definido com um ângulo diferente de 0, 90, 180, 270 ou 360, a imagem derivada mantém a sua orientação.

A rotação aceita apenas esses cinco ângulos, e qualquer outro valor deixa a imagem sem rotação.

• Escolha um ângulo aceito: Rotação informa a sintaxe do filtro.

A imagem derivada então gira para a esquerda pelo ângulo que você solicitou.

Recursos relacionados