JS para navegador

SDK de navegador para ClickStack - a stack de observabilidade do ClickHouse

O SDK de navegador do ClickStack permite instrumentar sua aplicação de frontend para enviar eventos ao ClickStack. Com isso, você pode visualizar solicitações de rede e exceções junto com eventos de backend em uma única linha do tempo.

Além disso, ele captura e correlaciona automaticamente dados de replay de sessão, para que você possa acompanhar visualmente e depurar o que um usuário estava vendo enquanto usava sua aplicação.

Este guia integra o seguinte:

• Logs do Console
• Replays de Sessão
• Solicitações XHR/Fetch/WebSocket
• Exceções

​

Primeiros passos

Importação de pacote

Instale por importação de pacote (recomendado)

Use o comando a seguir para instalar o pacote do navegador.

npm install @hyperdx/browser

Inicialize o ClickStack

import HyperDX from '@hyperdx/browser';

HyperDX.init({
    url: 'http://your-otel-collector:4318',
    apiKey: 'YOUR_INGESTION_API_KEY', //omita para Managed ClickStack
    service: 'my-frontend-app',
    tracePropagationTargets: [/api.myapp.domain/i], // Defina para vincular traces do frontend a requisições de backend
    consoleCapture: true, // Captura logs do console (padrão: false)
    advancedNetworkCapture: true, // Captura cabeçalhos e corpos completos de requisição/resposta HTTP (padrão: false)
});

Tag de script

Instale via tag de script (alternativa)

Você também pode incluir e instalar o script por meio de uma tag de script, em vez de instalá-lo via NPM. Isso expõe a variável global HyperDX e pode ser usada da mesma forma que o pacote NPM.

Isso é recomendado se o seu site não usa um bundler no momento.

<script src="//www.unpkg.com/@hyperdx/browser@0.21.0/build/index.js"></script>
<script>
  window.HyperDX.init({
    url: 'http://localhost:4318',
    apiKey: 'YOUR_INGESTION_API_KEY', //omita para Managed ClickStack
    service: 'my-frontend-app',
    tracePropagationTargets: [/api.myapp.domain/i], // Defina para vincular traces do frontend a requisições de backend
  });
</script>

​

Opções

• apiKey - Sua API key de ingestão do ClickStack.
• service - O nome do serviço com que os eventos aparecerão na UI do HyperDX.
• tracePropagationTargets - Uma lista de padrões regex para corresponder a requisições HTTP e vincular traces de frontend e backend; isso adicionará um cabeçalho traceparent adicional a todas as requisições que correspondam a qualquer um dos padrões. Isso deve ser definido como o domínio da API do seu backend (ex.: api.yoursite.com).
• consoleCapture - (Opcional) Captura todos os logs do console (padrão false).
• advancedNetworkCapture - (Opcional) Captura cabeçalhos e corpos completos de requisições e respostas (padrão false).
• url - (Opcional) A URL do OpenTelemetry Collector, necessária apenas para instâncias self-hosted.
• maskAllInputs - (Opcional) Se deve mascarar todos os campos de entrada no replay de sessão (padrão false).
• maskAllText - (Opcional) Se deve mascarar todo o texto no replay de sessão (padrão false).
• disableIntercom - (Opcional) Se deve desabilitar a integração com o Intercom (padrão false)
• disableReplay - (Opcional) Se deve desabilitar o replay de sessão (padrão false)

​

Configuração adicional

​

Associar informações ou metadados do usuário

Associar informações do usuário permitirá que você pesquise/filtre sessões e eventos na UI do HyperDX. Isso pode ser feito a qualquer momento durante a sessão do cliente. A sessão atual do cliente e todos os eventos enviados após essa chamada serão associados às informações do usuário.

userEmail, userName e teamName preencherão a UI de sessões com os valores correspondentes, mas podem ser omitidos. Quaisquer outros valores adicionais podem ser especificados e usados para pesquisar eventos.

HyperDX.setGlobalAttributes({
  userId: user.id,
  userEmail: user.email,
  userName: user.name,
  teamName: user.team.name,
  // Outras propriedades personalizadas...
});

​

Captura automática de erros em error boundaries do React

Se você estiver usando React, poderá capturar automaticamente erros que ocorram em error boundaries do React ao passar seu componente de error boundary para a função attachToReactErrorBoundary.

// Importe seu ErrorBoundary (estamos usando react-error-boundary como exemplo)
import { ErrorBoundary } from 'react-error-boundary';

// Isso se conectará ao componente ErrorBoundary e capturará quaisquer erros que ocorram
// em qualquer instância dele.
HyperDX.attachToReactErrorBoundary(ErrorBoundary);

​

Enviar ações personalizadas

Para rastrear explicitamente um evento específico da aplicação (ex.: cadastro, envio, etc.), você pode chamar a função addAction com o nome do evento e metadados opcionais do evento.

Exemplo:

HyperDX.addAction('Form-Completed', {
  formId: 'signup-form',
  formName: 'Signup Form',
  formType: 'signup',
});

​

Ativar a captura de rede dinamicamente

Para ativar ou desativar a captura de rede dinamicamente, basta chamar a função enableAdvancedNetworkCapture ou disableAdvancedNetworkCapture, conforme necessário.

HyperDX.enableAdvancedNetworkCapture();

​

Habilite a medição de tempo de recursos para solicitações CORS

Se o seu aplicativo frontend faz solicitações de API para um domínio diferente, você pode opcionalmente habilitar o cabeçalho Timing-Allow-Origin para ser enviado com a solicitação. Isso permitirá que o ClickStack capture informações detalhadas de tempo do recurso para a solicitação, como resolução de DNS, download da resposta etc., por meio de PerformanceResourceTiming.

Se você estiver usando express com os pacotes cors, poderá usar o snippet a seguir para habilitar o cabeçalho:

var cors = require('cors');
var onHeaders = require('on-headers');

// ... todo o seu código

app.use(function (req, res, next) {
  onHeaders(res, function () {
    var allowOrigin = res.getHeader('Access-Control-Allow-Origin');
    if (allowOrigin) {
      res.setHeader('Timing-Allow-Origin', allowOrigin);
    }
  });
  next();
});
app.use(cors());