OpenTelemetry (OTEL)

Este módulo implementa a observabilidade completa do frontend da Smart NX, utilizando OpenTelemetry para coletar traces, métricas de performance (Web Vitals) e interações do usuário de forma segura, escalável e configurável via .env.

Estrutura de Diretórios

src/services/observability/
│
├── context/
│   └── userContext.ts
│
├── core/
│   ├── config.ts
│   ├── logger.ts
│   └── provider.ts
│
├── hooks/
│   └── useRouteTracing.ts
│
├── instrumentations/
│   ├── rest.ts
│   └── userInteraction.ts
│
├── metrics/
│   └── webVitals.ts
│
└── index.ts

Cada módulo tem uma responsabilidade específica dentro do ecossistema OTEL — desde a configuração, até o registro e exportação dos dados de telemetria.

Configuração via `.env`

A observabilidade é controlada 100% por variáveis de ambiente, permitindo ativar, ajustar o sampling e definir o endpoint OTLP de exportação.

Variável	Tipo	Descrição	Exemplo
`VITE_ENVIRONMENT`	string	Define o ambiente atual	`"local"`
`VITE_OTEL_EXPORTER_OTLP_TRACES_ENDPOINT`	string	Endpoint OTLP (SigNoz ou outro coletor)	`"https://signoz.smartnx.io/v1/traces"`
`VITE_OTEL_ENABLED`	boolean	Habilita ou desabilita completamente a observabilidade	`"true"`
`VITE_OTEL_DEBUG`	boolean	Exibe logs detalhados no console	`"true"`
`VITE_OTEL_USER_INTERACTIONS`	boolean	Ativa a instrumentação de UI (cliques, inputs, submits)	`"true"`
`VITE_OTEL_SAMPLING_ENABLED`	boolean	Controla se o sampling está ativo	`"true"`
`VITE_OTEL_SAMPLING_RATIO`	number	Percentual de amostragem (0.0 a 1.0)	`"0.1"`
`VITE_OTEL_BATCH_DELAY_MS`	number	Intervalo (ms) entre os envios de lote	`"7000"`
`VITE_OTEL_BATCH_SIZE`	number	Máximo de spans por lote	`"256"`
`VITE_OTEL_QUEUE_SIZE`	number	Tamanho máximo da fila local	`"1024"`

💡 Exemplo completo

VITE_ENVIRONMENT="local"
VITE_OTEL_EXPORTER_OTLP_TRACES_ENDPOINT="https://signoz.smartnx.io/v1/traces"
VITE_OTEL_ENABLED="true"
VITE_OTEL_DEBUG="true"
VITE_OTEL_USER_INTERACTIONS="true"
VITE_OTEL_SAMPLING_ENABLED="true"
VITE_OTEL_SAMPLING_RATIO="1.0"
VITE_OTEL_BATCH_DELAY_MS="7000"
VITE_OTEL_BATCH_SIZE="256"
VITE_OTEL_QUEUE_SIZE="1024"

Inicialização

A inicialização ocorre logo na montagem do app:

import { initObservability } from "@services/observability";

initObservability();

Isso cria o TracerProvider, registra instrumentações automáticas e configura o exportador OTLP.

Instrumentações registradas

FetchInstrumentation → chamadas HTTP (fetch, XMLHttpRequest)
UserInteractionInstrumentation → cliques, inputs e submits
useRouteTracing → mudanças de rota (React Router / TanStack Router)
WebVitals → métricas de UX (LCP, CLS, INP, TTFB)

Contexto de Usuário

O módulo context/userContext.ts cria um span chamado user.session com atributos seguros do usuário autenticado:

{
  "user.id": "4",
  "user.email": "matheus.telles@smartnx.com",
  "user.name": "Matheus Telles",
  "user.role": "Smart NX",
  "user.type_id": 1,
  "tenant.id": 2000,
  "tenant.name": "SmartNX",
  "session.license_type": 3
}

⚠️ Privacidade

Nenhum dado sensível (como CPF, senha ou token) é enviado — apenas identificadores públicos e metadados operacionais.

Tracing de Rotas

O hook useRouteTracing cria spans automáticos de navegação:

"route.path": "/dashboard",
"route.action": "PUSH",
"screen.size": "1920x1080",
"device.type": "desktop",
"route.duration_ms": 245.37

Use-o no componente raiz da aplicação:

function App() {
  useRouteTracing();
  return <RouterProvider router={router} />;
}

Métricas — Web Vitals

O módulo metrics/webVitals.ts coleta métricas UX via Web Vitals:

Métrica	Descrição
LCP	Tempo para renderizar o maior elemento visível
CLS	Estabilidade visual da interface
INP	Tempo de resposta às interações
TTFB	Tempo para o primeiro byte do servidor

Cada métrica é registrada como um span e também como um gauge no meter web-vitals.

Sampling e Batch

Essas configurações controlam o volume e o custo do tracing:

Sampling (VITE_OTEL_SAMPLING_RATIO) Define o percentual de spans coletados.
- 1.0 → coleta 100% dos traces (ideal em homolog/local)
- 0.1 → coleta 10% (recomendado em produção)
Batch Export (VITE_OTEL_BATCH_DELAY_MS) Define a frequência de envio em lote ao coletor (ex: SigNoz).

Logs de Diagnóstico

Todos os logs do OTEL passam por um logger central (core/logger.ts):

otelLog("TracerProvider registrado → env=local, sampling=1.0, batchDelay=7000ms");

Logs só são exibidos se VITE_OTEL_DEBUG="true".

Integração com SigNoz

Os spans são exportados via OTLP/HTTP para o SigNoz:

Endpoint padrão: https://signoz.smartnx.io/v1/traces
Protocolo: OTLP/HTTP
Envio em lote: a cada VITE_OTEL_BATCH_DELAY_MS ms

No painel do SigNoz, filtre por:

service.name = smartnx-web-local

E visualize spans de:

router → navegação
fetch → requisições API
user.session → contexto do usuário
webvitals → performance UX

Boas Práticas

Use apenas atributos genéricos e seguros no contexto de usuário.
Mantenha sampling reduzido em produção.
Habilite logs apenas em ambientes locais/homolog.
Nunca logue headers, tokens ou payloads sensíveis.
Centralize toda instrumentação no initObservability.

Resumo

Componente	Função
provider.ts	Cria o TracerProvider e configura sampling/batch
config.ts	Define parâmetros e variáveis de ambiente OTEL
rest.ts	Instrumenta chamadas HTTP
userInteraction.ts	Captura eventos de interação da UI
webVitals.ts	Coleta métricas de performance
userContext.ts	Registra contexto seguro do usuário autenticado
useRouteTracing.ts	Rastreia troca de rotas
index.ts	Inicializa a observabilidade globalmente

Referências

🕓 Histórico de Versões

Data	Versão	Autor / Revisor	Alterações
30/10/2025	`v1.0.0`	@Matheus Telles	Criação inicial e estrutura base do documento

Estrutura de Diretórios​

Configuração via .env​

Inicialização​

Contexto de Usuário​

Tracing de Rotas​

Métricas — Web Vitals​

Sampling e Batch​

Logs de Diagnóstico​

Integração com SigNoz​

Boas Práticas​

Resumo​

Referências​

🕓 Histórico de Versões​