O replay de sessão no ClickStack captura e reconstrói as interações do usuário no seu aplicativo web, permitindo reproduzir visualmente exatamente o que ele viu e fez durante a sessão. Em vez de gravar um vídeo, o SDK registra alterações no DOM, movimentos do mouse, cliques, rolagens, entradas de teclado, logs do console, requisições de rede (XHR, Fetch, WebSocket) e exceções de JavaScript — e depois reconstrói a experiência no navegador.
Como os replays de sessão são armazenados no ClickHouse junto com seus logs, traces e métricas, você pode passar de assistir à experiência de um usuário para inspecionar os traces de backend e as consultas ao banco de dados que a viabilizaram — tudo em poucos cliques. Isso torna o replay de sessão útil para debugging de problemas em produção, entender o comportamento do usuário, identificar pontos de atrito na UX e confirmar visualmente problemas relatados ao suporte.
Instrumentando sua aplicação
@hyperdx/browser), que estende o SDK do OpenTelemetry com gravação de sessão, captura do console e captura de requisições de rede. Se você precisa apenas de traces sem replay de sessão, qualquer SDK de navegador compatível com OTel funcionará com o ClickStack.
Os exemplos abaixo usam o SDK do navegador do ClickStack. Adicionar replay de sessão à sua aplicação leva apenas três etapas: instalar o pacote, inicializar o SDK, e todas as interações do usuário são capturadas automaticamente — sem necessidade de outras alterações no código.
Inicialize o SDK em um local que certamente será carregado quando seu app iniciar. Por exemplo, em uma aplicação Next.js, isso pode ser o seu arquivo layout.js raiz. Isso garante que a gravação da sessão comece imediatamente e capture toda a experiência do usuário.
npm install @hyperdx/browser
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],
consoleCapture: true,
advancedNetworkCapture: true,
});
yarn add @hyperdx/browser
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],
consoleCapture: true,
advancedNetworkCapture: true,
});
Para aplicações que não usam um bundler, inclua o SDK diretamente por meio de uma tag de script. Isso expõe a variável global HyperDX, que pode ser usada da mesma forma que o pacote NPM.<script src="https://unpkg.com/@hyperdx/browser@0.21.0/build/index.js"></script>
<script>
window.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],
consoleCapture: true,
advancedNetworkCapture: true,
});
</script>
A opção tracePropagationTargets é fundamental para conectar replays de sessão aos traces de backend — defina-a com o domínio da sua API para habilitar o rastreamento distribuído completo do frontend ao backend. Para uma lista completa das opções do SDK, incluindo controles de privacidade, ações personalizadas, error boundaries do React e source maps, consulte a referência do SDK do navegador. Visualizando replays de sessão
tracePropagationTargets vincula spans do navegador a spans do servidor por meio do cabeçalho traceparent, criando um trace distribuído interligado desde o clique do usuário até o banco de dados. Para um passo a passo detalhado de como isso funciona na prática, incluindo a instrumentação do frontend e do backend, consulte Instrumenting your NextJS application with OpenTelemetry and ClickStack.
A correlação também funciona no sentido inverso. Ao visualizar um trace na exibição Search, clique nele para abrir os detalhes do trace e, em seguida, selecione a aba replay de sessão para ver exatamente o que o usuário estava fazendo no momento daquele trace. Isso é especialmente útil ao investigar erros ou requisições lentas — você pode começar pelo problema no backend e ver imediatamente a experiência do usuário.
Como os dados de sessão são armazenados
hyperdx_sessions no ClickHouse, separada de logs e traces. Cada evento de sessão é uma linha com um campo Body contendo o payload do evento e um map LogAttributes que armazena os metadados do evento. As colunas Body e LogAttributes, em conjunto, contêm os detalhes dos eventos reais da sessão usados para reconstruir a reprodução.
Para ver as informações completas sobre o esquema da tabela, consulte Tabelas e esquemas usados pelo ClickStack.
Há duas maneiras de ver o replay de sessão em ação:
