Solução de problemas do framework de extensões do Looker

O framework de extensões do Looker permite criar aplicativos e visualizações personalizados em JavaScript e TypeScript que são executados no Looker. As extensões são executadas em um iframe de sandbox e interagem com sua instância do Looker pelo SDK de extensão. Se você tiver problemas com uma extensão personalizada, como uma página em branco ou uma mensagem de erro no iframe, erros de JavaScript no console do navegador ou de compartilhamento de recursos entre origens (CORS), solicitações de API Looker com falha (códigos de status 4xx ou 5xx) ou erros de configuração do manifest.lkml, este documento ajuda a resolver esses problemas.

Pré-requisitos e requisitos de configuração comuns

Antes de começar a solução de problemas, verifique se o ambiente, o projeto do LookML e a conta de usuário atendem aos requisitos para executar uma extensão do Looker:

  • Framework de extensão ativado: um administrador do Looker precisa ativar a configuração Framework de extensão em Administrador > Plataforma > Framework de extensão.
  • Configuração do projeto e do modelo do LookML: cada extensão requer um projeto do LookML que inclua os seguintes componentes:
  • Direitos do manifesto: a declaração application no arquivo manifest.lkml precisa definir explicitamente todos os entitlements que a extensão exige, como core_api_methods para chamadas de API Looker ou external_api_urls para solicitações a domínios externos. Uma extensão não será executada sem um bloco entitlements.
  • Permissões do usuário: os usuários precisam ter permissões de extensão (como access_data, explore ou develop) para um conjunto de modelos que inclua o modelo LookML da extensão. Para criar uma extensão, os desenvolvedores precisam de permissões develop do LookML.
  • Ferramentas de diagnóstico e detalhes do ambiente: tenha os seguintes detalhes e ferramentas prontos antes de começar a solução de problemas:
    • O URL da instância do Looker, o nome do projeto do LookML e o nome de application declarado em manifest.lkml.
    • Acesso às ferramentas para desenvolvedores do navegador da Web (guias Console e Rede) na máquina cliente.
    • Durante o desenvolvimento local, acesso ao terminal que executa o servidor de desenvolvimento local.
    • Para erros de servidor 5xx em chamadas de API Looker, acesso aos registros da instância do Looker (looker.log em instâncias hospedadas pelo cliente ou Análise de Registros no Cloud Logging no console do Google Cloud para instâncias do Looker (Google Cloud Core)).

Árvore de depuração

Use a árvore de decisão a seguir para começar a resolver problemas do framework de extensões do Looker:

As seções a seguir descrevem os cenários na árvore em mais detalhes.

Inspecionar o console do navegador e os registros de rede

Como as extensões do Looker são executadas no lado do cliente no navegador, comece a solução de problemas inspecionando as ferramentas para desenvolvedores do navegador em busca de erros de JavaScript, violações de políticas de segurança e solicitações HTTP com falha.

Verificar se há erros no console do navegador

Para identificar erros do lado do cliente que impedem o carregamento ou a execução da extensão:

  1. No Looker, abra a página em que a extensão é carregada.
  2. Clique com o botão direito do mouse em qualquer lugar da página e selecione Inspecionar (ou pressione Control+Shift+I no Windows e no Linux ou Command+Option+I no macOS).
  3. No painel de ferramentas para desenvolvedores, selecione a guia Console.
  4. Atualize a página para capturar erros que ocorrem durante o carregamento inicial.
  5. Inspecione as mensagens de erro em vermelho no console:

Inspecionar a guia "Rede" para solicitações com falha

Para analisar as solicitações HTTP feitas pela extensão para pacotes JavaScript, recursos ou endpoints de API, siga estas etapas:

  1. No painel de ferramentas para desenvolvedores do navegador, selecione a guia Rede.
  2. Marque a caixa de seleção Desativar cache para que o navegador não carregue recursos desatualizados em cache.
  3. Atualize a página em que a extensão é carregada.
  4. Verifique a lista de solicitações de rede para encontrar códigos de status 4xx ou 5xx e selecione uma solicitação com falha para inspecionar as guias Cabeçalhos, Payload e Resposta:
    • 404 no pacote de extensão (como bundle.js): verifique se o servidor de desenvolvimento está em execução e se o parâmetro url ou file em manifest.lkml está correto.
    • 401 ou 403 em uma solicitação de API Looker: investigue autenticação, permissões e direitos.
    • 400 ou 422 em uma solicitação de API: inspecione as guias Payload e Resposta para identificar JSONs malformados ou parâmetros de solicitação inválidos.
    • Erros de servidor 5xx: indicam erros do lado do servidor na instância do Looker. Verifique looker.log em instâncias hospedadas pelo cliente ou a Análise de registros no console para instâncias do Looker (Google Cloud Core) para encontrar entradas com carimbos de data/hora correspondentes.

Se nenhum erro aparecer nas guias Console ou Rede, ou se você precisar verificar como o Looker carrega a extensão, prossiga para a próxima seção.

Verificar o manifesto e a configuração do projeto

A declaração application no arquivo manifest.lkml do projeto controla como o Looker carrega a extensão e quais recursos ela pode usar. Configurações incorretas em manifest.lkml são uma causa comum de falhas de carregamento e de API:

  • Verifique o parâmetro url ou file: no ambiente de desenvolvimento integrado do Looker, abra o arquivo manifest.lkml do projeto e inspecione a declaração application:
    • Uma declaração application precisa incluir um parâmetro url ou um parâmetro file, mas não ambos.
    • Durante o desenvolvimento local: verifique se o parâmetro url corresponde exatamente ao protocolo (http ou https), ao nome do host, à porta e ao caminho que são disponibilizados pelo servidor de desenvolvimento local (por exemplo, https://localhost:8080/bundle.js).
    • Em produção: verifique se você atualizou a declaração application do desenvolvimento local url para o caminho de produção file no seu projeto do LookML (por exemplo, file: "apps/bundle.js") ou URL do pacote de produção.
  • Verifique os direitos de manifest.lkml: revise o bloco entitlements na declaração application. Uma extensão não pode usar um recurso do Looker ou um domínio externo, a menos que esse direito seja declarado explicitamente, da seguinte maneira:
    • core_api_methods: precisa listar todos os métodos da API Looker que sua extensão chama (por exemplo, core_api_methods: ["me", "all_looks", "run_inline_query"]).
    • external_api_urls: precisa listar todos os domínios externos que não são do Looker que a extensão solicita diretamente ou pelo proxy.
    • Direitos adicionais: verifique se a extensão requer local_storage, navigation, new_window, new_window_external_urls, use_form_submit, use_embeds, use_downloads, use_iframes, use_clipboard, oauth2_urls, global_user_attributes ou scoped_user_attributes.
  • Validar, confirmar e implantar: depois de editar manifest.lkml, clique em Validar LookML, confirme as mudanças e clique em Implantar na produção para que a configuração atualizada entre em vigor.

Resolver problemas do servidor e do ambiente de desenvolvimento local

Ao desenvolver uma extensão localmente usando o parâmetro url em manifest.lkml, o servidor de desenvolvimento local precisa estar em execução e acessível no navegador:

  • Confirme se o servidor de desenvolvimento está em execução: verifique a janela do terminal em que você iniciou o servidor de desenvolvimento (por exemplo, usando yarn develop ou npm start):
    • Verifique se o build foi compilado sem erros e se exibe uma mensagem de escuta (como webpack compiled successfully ou listening on localhost:8080).
    • Se o servidor não estiver em execução, inicie-o com yarn develop ou npm start.
    • Se o servidor tiver sido encerrado com um erro de sintaxe ou de dependência ausente, resolva o erro de código ou execute yarn install (ou npm install) para instalar os pacotes ausentes.
    • Se o servidor falhar com um conflito de porta (EADDRINUSE), interrompa o outro processo que está usando essa porta ou configure o servidor de desenvolvimento e o parâmetro manifest.lkml url para usar uma porta diferente.
  • Abra o URL da extensão diretamente no navegador: copie o valor url de manifest.lkml (por exemplo, https://localhost:8080/bundle.js) e abra-o em uma nova guia do navegador:
    • Certificado SSL autoassinado não confiável: os servidores de desenvolvimento local costumam usar certificados SSL autoassinados. Se o navegador exibir um aviso de segurança de certificado, selecione Avançado e prossiga para localhost para confiar no certificado da sessão do navegador. Até que o certificado seja confiável, o navegador vai impedir que o pacote seja carregado no iframe do Looker.
    • Conexão recusada ou bloqueada: se o navegador não conseguir acessar o URL, verifique se nenhum firewall local ou software de segurança de endpoint está bloqueando as conexões com localhost na porta de configuração.

Resolver problemas de rede, CORS e política de segurança

Os navegadores da Web aplicam a política de mesma origem, que impede que o Looker carregue recursos de extensão ou chame servidores externos em uma origem diferente, a menos que os cabeçalhos e as políticas de segurança de compartilhamento de recursos entre origens (CORS) estejam configurados:

  • Identifique erros de CORS no console do navegador: procure mensagens de erro na guia Console que contenham Cross-Origin Resource Sharing, CORS, has been blocked by CORS policy ou cabeçalhos Access-Control-Allow-Origin ausentes.
  • Configure os cabeçalhos CORS do servidor de desenvolvimento local: se você usar webpack-dev-server (ou um bundler semelhante), verifique se a configuração devServer em webpack.config.js inclui o cabeçalho Access-Control-Allow-Origin: javascript devServer: { headers: { "Access-Control-Allow-Origin": "*" } }
  • Configure a hospedagem de produção e os cabeçalhos CORS da API externa: se a extensão carregar recursos ou solicitar dados de um serviço externo (como Cloud Storage, Amazon S3 ou um servidor de back-end personalizado), configure o serviço de hospedagem para retornar o cabeçalho Access-Control-Allow-Origin que permite o domínio da instância do Looker. Verifique também se nenhum proxy de rede ou firewall está removendo os cabeçalhos CORS da resposta e se o domínio externo está listado em external_api_urls em manifest.lkml.
  • Verifique a Política de Segurança de Conteúdo (CSP) e o carregamento de extensões aprimorado: se você encontrar violações de CSP ao carregar uma extensão, verifique a configuração Carregamento de extensões aprimorado em Administrador > Plataforma > Framework de extensões.

Resolver problemas de autenticação e acesso à API

As extensões interagem com a API Looker em nome do usuário conectado pelo SDK de extensão. Se as chamadas de API falharem com os códigos de status 401 Unauthorized ou 403 Forbidden na guia Rede, investigue o seguinte:

  • Diferencie os erros 401 e 403:
    • 401 Unauthorized: a solicitação não foi autenticada. Esse erro geralmente ocorre se o SDK de extensão não foi inicializado corretamente ou se a extensão tentou uma chamada de API antes que o SDK concluísse o handshake de autenticação.
    • 403 Forbidden: a solicitação foi autenticada, mas o usuário conectado não tem as permissões necessárias do Looker ou o manifest.lkml da extensão não inclui o método chamado em core_api_methods.
  • Verifique as funções e permissões do usuário: em Administrador > Usuários e Administrador > Funções, verifique as funções atribuídas, os conjuntos de permissões e os conjuntos de modelos do usuário conectado:
    • Confirme se o usuário tem permissões para usar a extensão, incluindo access_data (e explore ou develop, conforme necessário) para um conjunto de modelos que contém o modelo LookML da extensão e todos os modelos consultados pela extensão.
    • Confirme se o papel do usuário inclui as permissões específicas exigidas por cada endpoint de API Looker que a extensão chama.
  • Verifique se o contexto do SDK está pronto antes de chamar a API: confira se o código da extensão aguarda a inicialização do contexto do SDK de extensão antes de invocar métodos de API.

Resolver problemas do SDK de extensão e das dependências

Problemas com a instalação do pacote npm ou Yarn ou componentes ausentes do provedor de SDK podem impedir que uma extensão seja compilada ou se conecte ao Looker:

  • Verifique a instalação do módulo Node.js: no terminal, acesse o diretório raiz do projeto da extensão e verifique o diretório node_modules:
    1. Se node_modules estiver ausente ou as dependências parecerem corrompidas, exclua o diretório node_modules e o arquivo de bloqueio (yarn.lock ou package-lock.json).
    2. Opcional: se a instalação do pacote falhar repetidamente, limpe o cache do gerenciador de pacotes (por exemplo, execute npm cache clean --force).
    3. Verifique se a versão do Node.js instalada é compatível com os requisitos do projeto e execute yarn install ou npm install para fazer uma instalação limpa.
  • Verifique a inicialização de ExtensionProvider: abra o arquivo de entrada principal da extensão (como App.js ou index.js) e confirme se <ExtensionProvider> (importado de @looker/extension-sdk-react) envolve os componentes do aplicativo que precisam do contexto do SDK do Looker: javascript ReactDOM.render( <ExtensionProvider> <App /> </ExtensionProvider>, document.getElementById('root') ); Se <ExtensionProvider> estiver ausente ou se você o tiver colocado após os componentes que chamam o SDK, os componentes filhos não poderão acessar o contexto do SDK.

Resolver problemas de lógica e de JavaScript no ambiente de execução

Se a configuração, o servidor de desenvolvimento, as permissões e a configuração do SDK da extensão forem válidos, o problema pode ser um erro de tempo de execução no código JavaScript ou TypeScript personalizado da extensão:

  • Analisar stack traces do console: na guia Console do navegador, localize a mensagem de erro vermelha e clique na seta de expansão para ver o stack trace completo. As linhas superiores do stack trace identificam o arquivo e o número da linha no código-fonte em que o erro ocorreu. Clique no link do arquivo (por exemplo, MyComponent.js:42) para acessar diretamente essa linha na guia Origens.
  • Verifique se há valores indefinidos ou nulos: para erros como TypeError: Cannot read properties of undefined, verifique se as respostas da API ou propriedades assíncronas terminaram de carregar antes que o código leia as propriedades aninhadas. Adicione verificações defensivas (como if (myObject && myObject.property) ou encadeamento opcional myObject?.property).
  • Verifique os formatos de resposta da API: confirme se o código processa a estrutura de dados real retornada pelas chamadas da API Looker. Por exemplo, verifique se um payload de resposta é um objeto ou uma matriz antes de chamar métodos de matriz.
  • Depurar com pontos de interrupção e geração de registros: na guia Origens do navegador, defina pontos de interrupção antes da linha com falha para pausar a execução e inspecionar os valores das variáveis em tempo real ou adicione instruções console.log() para rastrear o fluxo de execução.

Verificar a compatibilidade da versão do Looker

As atualizações ou mudanças de recursos principais no Looker podem exigir uma versão compatível do SDK de extensão do Looker:

  1. Verifique a versão de @looker/extension-sdk (e @looker/extension-sdk-react, se usado) no arquivo package.json do projeto de extensão.
  2. Na interface da Web do Looker, verifique a versão de lançamento atual da instância em Ajuda > Sobre ou Administrador > Geral > Configurações.
  3. Compare sua versão de lançamento do Looker com as notas de compatibilidade na documentação do @looker/extension-sdk.
  4. Se a instância do Looker foi atualizada recentemente e a extensão usa um SDK desatualizado ou se a extensão usa um recurso mais recente do SDK que não é compatível com uma versão anterior do Looker, atualize o pacote do SDK para uma versão compatível: bash npm install @looker/extension-sdk@latest Depois de atualizar o pacote, reinstale as dependências e reinicie o servidor de desenvolvimento.

Coletar informações de diagnóstico

Se não for possível resolver o problema depois de seguir as etapas de solução de problemas, reúna as seguintes informações antes de entrar em contato com o suporte:

  1. Informações sobre a instância e o projeto do Looker:
    • URL da instância do Looker (por exemplo, instance_name.looker.com).
    • Versão de lançamento do Looker.
    • Nome do projeto do LookML que contém a extensão e o nome de application em manifest.lkml.
  2. Configuração da extensão e detalhes do SDK:
    • Uma cópia ou captura de tela da declaração application no arquivo manifest.lkml.
    • A versão de @looker/extension-sdk especificada em package.json.
    • Se a extensão está sendo executada em um servidor de desenvolvimento local (url) ou implantada em produção (file).
  3. Registros de erros e capturas de tela:
    • Capturas de tela ou texto completo de erros das guias Console e Rede do navegador (incluindo cabeçalhos da solicitação e payloads de resposta para solicitações 4xx ou 5xx com falha).
    • Se as chamadas de API retornarem consistentemente erros de servidor 5xx, trechos de registro correspondentes de looker.log (para instâncias hospedadas pelo cliente) ou da Análise de Registros no Logging (para instâncias do Looker (Google Cloud Core)).
  4. Resumo da solução de problemas e etapas de reprodução:
    • Um resumo das etapas de solução de problemas que você já realizou e os resultados delas.
    • Etapas exatas para reproduzir o problema ou um exemplo mínimo reproduzível se você suspeitar de um problema no framework de extensões do Looker ou no SDK de extensão.

Entrar em contato com o suporte

Se você seguiu todas as etapas anteriores e o problema ainda não foi resolvido: