Frontend Instrumentation – JavaScript

Guia completo para instrumentar aplicações front-end com Faro SDK, enviando dados para o collector-fe da Elven.

Visão Geral

Este guia tem como objetivo instruir a instrumentação de aplicações front-end com o Faro SDK da Grafana, utilizando o collector-fe, um componente exclusivo da Elven Observability.

Você poderá rastrear:

• Sessões e navegação dos usuários.

• Eventos personalizados.

• Logs estruturados.

• Medidas de performance (como tempo de carregamento).

Instalação

Usando NPM:

npm install @grafana/faro-web-sdk
npm install @grafana/faro-web-tracing

Usando Yarn:

yarn add @grafana/faro-web-sdk
yarn add @grafana/faro-web-tracing

Se estiver usando React com React Router:

yarn add @grafana/faro-react

Uso básico

Boa prática: crie um arquivo separado como faro.ts para configurar o SDK e importe no entry point (index.tsx ou App.tsx).

// faro.ts
import { initializeFaro, getWebInstrumentations } from '@grafana/faro-web-sdk';
import { TracingInstrumentation } from '@grafana/faro-web-tracing';

initializeFaro({
  url: 'https://seu_collector-fe.com/collect/<TENANT>/<TOKEN>',
  app: {
    name: 'my-app', # Nome da sua aplicação
    version: '1.0.0', # Versão da sua aplicação
    environment: 'production', # Ambiente da sua aplicação
  },
  consoleInstrumentation: {
    disabledLevels: [],
  },
  sessionTracking: {
    samplingRate: 1,
    persistent: true,
  },
  instrumentations: [
    ...getWebInstrumentations(),
    new TracingInstrumentation(),
  ],
});

Configuração com React Router (opcional)

import {
  initializeFaro,
  createReactRouterV6DataOptions,
  ReactIntegration,
  getWebInstrumentations,
} from '@grafana/faro-react';
import { TracingInstrumentation } from '@grafana/faro-web-tracing';
  app: {
    name: 'my-app', # Nome da sua aplicação
    version: '1.0.0', # Versão da sua aplicação
    environment: 'production', # Ambiente da sua aplicação
  },
  sessionTracking: {
    samplingRate: 1,
    persistent: true,
  },
  instrumentations: [
    ...getWebInstrumentations(),
    new TracingInstrumentation(),
    new ReactIntegration({
      router: createReactRouterV6DataOptions({
        matchRoutes,
      }),
    }),
  ],
});

Sincronização de usuário logado

export const FaroUserSync = () => {
  const { user } = useAuth();

  useEffect(() => {
    if (user) {
      faro.api.setUser({
        id: user.uid,
        username: user.displayName ?? 'no-logged',
        email: user.email ?? 'no-logged',
      });
    }
  }, [user]);

  return null;
};

Exemplo com Next.js

Ao usar o Faro SDK em aplicações Next.js, é necessário garantir que a instrumentação aconteça somente no lado do cliente, pois o window não está disponível durante a renderização no servidor.

A forma ideal de configurar é dentro do arquivo especial do Next, o _app.tsx.

Exemplo de uso em pages/_app.tsx

// pages/_app.tsx
import type { AppProps } from 'next/app';
import { useEffect } from 'react';
import { initializeFaro, getWebInstrumentations } from '@grafana/faro-web-sdk';
import { TracingInstrumentation } from '@grafana/faro-web-tracing';

function MyApp({ Component, pageProps }: AppProps) {
  useEffect(() => {
    initializeFaro({
      url: process.env.NEXT_PUBLIC_FARO_URL!,
      app: {
        name: 'next-app',
        version: '1.0.0',
        environment: process.env.NODE_ENV,
      },
      sessionTracking: {
        samplingRate: 1,
        persistent: true,
      },
      instrumentations: [
        ...getWebInstrumentations(),
        new TracingInstrumentation(),
      ],
    });
  }, []);

  return <Component {...pageProps} />;
}

export default MyApp;

Dica: Utilize variáveis como NEXT_PUBLIC_FARO_URL no .env.local para manter o token e tenant fora do código-fonte.

Eventos, Logs e Medidas personalizadas

Eventos personalizados:

faro.api.pushEvent('click_cta', {
  label: 'Começar Agora',
  category: 'CTA',
  page: '/home',
});

Logs personalizados:

faro.api.pushLog(['debug'], 'Usuário clicou no botão de cadastro', {
  location: '/signup',
  component: 'SignupCTA',
});

Medidas personalizadas:

faro.api.pushMeasurement('search_time', {
  value: 273,
  unit: 'ms',
  attributes: {
    page: '/search',
    query: 'observability',
  },
});

Boas práticas

• Armazene FARO_URL no .env (REACT_APP_FARO_URL).

• Nunca envie dados sensíveis nos eventos ou logs.

• Prefira importar o faro.ts no início da aplicação.

• Utilize samplingRate de acordo com o volume do seu app (ex: 0.1 em produção).

Troubleshooting

Problema	Causa Provável	Solução
Eventos não chegam	Token inválido ou expirado	Verifique o JWT
Nada aparece no dashboard	URL incorreta ou CORS bloqueado	Verifique a URL e CORS do collector-fe
Sessão não persiste	Cookies bloqueados ou persistent: false	Ative persistent: true
Logs duplicados	initializeFaro sendo chamado múltiplas vezes	Mova para arquivo único e importe uma vez

Autenticação e URL do coletor

A URL de envio segue o formato:

https://seu_collector-fe.com/collect/<tenant>/<token>

Exemplo real:

https://seu_collector-fe.com/collect/elven/eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

Consulte: collector-fe – Guia de Instalação

Testando sua instrumentação

1. Acesse o app com o navegador.

2. Verifique no DevTools se a chamada para collector-fe retorna 2xx.

3. Acesse o dashboard Grafana e filtre pelos eventos do seu tenant.

Feito com amor pela Elven Observability

Se tiver dúvidas ou sugestões, fale com a gente: elven.works.