Solução de problemas de uma aplicação OpenNext

Aprenda como solucionar problemas de apps OpenNext na Azion: execute localmente com o Azion CLI, monitore logs, use APIs de Eventos em Tempo Real, Metadados e GraphQL, corrija limites de tamanho e variáveis de ambiente.

Ver como Markdown

1. Desenvolvimento local e depuração com o Azion CLI

O primeiro e mais crucial passo de solução de problemas é realizado antes mesmo do deployment. O Azion CLI permite que você execute sua função em um ambiente local que simula a plataforma Azion.

Comando Chave:

azion dev

Quando você executa esse comando na raiz do seu projeto, o CLI inicia um servidor local. Qualquer solicitação feita a esse servidor executará sua função, e saídas de console.log, bem como quaisquer erros, serão exibidas diretamente em seu terminal.

Benefícios:

  • Feedback imediato: Veja os resultados das suas alterações de código instantaneamente.
  • Economia de tempo: Evita a necessidade de deployment para cada pequena alteração.
  • Ambiente controlado: Depure a lógica da sua aplicação sem afetar o ambiente de produção.

Exemplo:

// main.js
export default function myWorker(event) {
console.log("Função executada com sucesso!");
return new Response('Olá Mundo');
}

Depois de executar azion dev e acessar o servidor local, seu terminal exibirá:

Função executada com sucesso!

2. Monitoramento de logs em produção

Quando sua aplicação estiver em produção, você precisará de ferramentas para observar seu comportamento em tempo real e analisar eventos passados.

Acesso em tempo real (Tailing)

Para monitorar logs à medida que acontecem, use o argumento --tail com o Azion CLI. Isso cria uma sessão contínua que exibe novos logs à medida que são gerados.

Comando chave:

azion logs cells --tail

Este comando é ideal para depurar problemas que estão acontecendo atualmente ou para monitorar o comportamento da aplicação durante um novo deployment.

Visualização via Console da Azion (Eventos em Tempo Real)

Para uma análise mais visual com mais opções de filtro, o Console da Azion é a ferramenta ideal.

  1. Acesse o Gerenciador em Tempo Real.
  2. No menu, vá para Observar > Eventos em Tempo Real.
  3. Selecione a guia do Console Functions.

Nessa tela, você pode:

  • Visualizar todos os logs gerados por console.log em suas funções.
  • Filtrar eventos por períodos de tempo (últimos 15 minutos, última hora, intervalo personalizado).
  • Pesquisar mensagens de log específicas.
  • Analisar informações detalhadas para cada evento, como ID da Função e Timestamp.

3. Análise avançada com a API de metadados

Frequentemente, o problema não está apenas no código, mas no contexto da solicitação (origem, cabeçalhos, etc.). A API de Metadados da Azion permite que suas funções acessem esses dados. Você pode registrar esses metadados para entender melhor o comportamento da sua aplicação.

Exemplo prático:

Imagine que você queira verificar de qual continente uma solicitação está vindo.

// main.js
export default function myWorker(event) {
const request = event.request;
const continentCode = request.metadata['geoip_continent_code'];
console.log(`Solicitação recebida do continente: ${continentCode}`);
// Lógica adicional baseada no continente...
return new Response(`Olá, ${continentCode}!`);
}

Ao implementar este código e monitorar os logs com azion logs cells --tail, você verá mensagens como:

Solicitação recebida do continente: SA

Isso permite que você depure lógica de roteamento, segurança (e.g., bloqueio por região) e personalização de conteúdo.

4. Coleta estruturada de logs com a API GraphQL

Para automação, integração com sistemas de monitoramento externos (como Datadog ou New Relic), ou para realizar análises complexas, a Azion fornece uma API GraphQL.

Com ela, você pode executar consultas para buscar logs em um formato estruturado.

Ferramenta Chave: O GraphQL Playground, disponível no Console da Azion, permite que você construa e teste suas consultas antes de integrá-las aos seus sistemas.

Exemplo de Consulta: Esta consulta obtém os 10 eventos de console mais recentes contendo uma linha de log específica.

query getConsoleEvents {
functionConsoleEvents(
limit: 10,
filter: {
tsRange: {begin: "2024-09-28T12:00:00", end: "2024-09-28T13:00:00"},
line: {contains: "Function failed"}
},
orderBy: [ts_ASC]
) {
ts
configurationId
functionId
line
}
}

5. O tamanho da função excede o limite

A Azion impõe limites no tamanho das funções, o limite padrão é de 20MB. Se seu deployment falhar com um erro sobre o tamanho da função, normalmente significa que seu código empacotado é muito grande para a plataforma.

Para resolver isso:

  1. Analise seu pacote: Use ferramentas como Webpack Bundle Analyzer ou ESBuild Analyzer para identificar dependências grandes.
  2. Remova dependências não usadas: Audite seu package.json e código para pacotes desnecessários.
  3. Otimize importações: Prefira importar funções específicas em vez de bibliotecas inteiras (por exemplo, import { parse } from "date-fns" em vez de import * as dateFns from "date-fns").
  4. Aproveite o cache da Azion: Mova ativos estáticos e arquivos grandes para o Armazenamento de Objetos ou CDN da Azion e faça referência a eles via URLs em vez de empacotá-los.

Consulte a documentação da Azion sobre limites de função para restrições de tamanho atualizadas.

6. Minhas variáveis de ambiente não estão disponíveis na Função

A Azion permite que você defina variáveis de ambiente para suas funções, mas elas devem ser configuradas explicitamente no console da Azion ou via API.

Se seu código não consegue acessar uma variável de ambiente esperada:

  1. Verifique o console da Azion: Vá para sua Aplicação > Funções > Variáveis de Ambiente e assegure-se de que a variável esteja definida.
  2. Refaça o deployment após alterações: Qualquer alteração nas variáveis de ambiente requer um novo deployment da sua função para entrar em vigor.
  3. Acesse as variáveis corretamente: No seu código, use process.env.MY_VARIABLE (para compatibilidade com Node.js) ou a API específica da plataforma se estiver usando outro runtime.

Se você estiver usando um framework como o Next.js, assegure-se de que seu processo de build não sobrescreva ou ignore essas variáveis. Para mais informações, veja o guia da Azion sobre variáveis de ambiente.