> ## Documentation Index > Fetch the complete documentation index at: https://docs.orquena.com/llms.txt > Use this file to discover all available pages before exploring further. # Observabilidade > OpenTelemetry, Grafana Alloy, Prometheus, Loki, Tempo, Grafana e GlitchTip. # Observabilidade A Nuvexa seguirá uma estratégia **OpenTelemetry-first**, mantendo a instrumentação independente do backend de observabilidade. ## Stack inicial ```text theme={null} Apps, workers, AI Runtime e providers ↓ OTLP, Prometheus e logs estruturados Grafana Alloy ├── Prometheus — metrics ├── Loki — logs └── Tempo — traces ↓ Grafana — dashboards e exploração Error events opcionais ↓ GlitchTip ``` ## Por que OpenTelemetry * Padrão aberto e vendor-neutral. * Propagação de contexto entre HTTP, events e jobs. * SDK JavaScript ativo. * Exportação OTLP para backends self-hosted ou gerenciados. * Correlação entre API, worker, WAHA e agentes de IA. ## Grafana Alloy Alloy será o collector inicial. Ele recebe, processa e encaminha metrics, logs, traces e profiles através de pipelines compatíveis com OpenTelemetry e Prometheus. ## Prometheus Armazena metrics operacionais e avalia alert rules. Exemplos: * Request rate, errors e latency. * Queue depth e oldest job. * Sessions WAHA por estado. * Appointment confirmations e conflitos. * AI token, cost e tool failures. IDs de message, appointment, contact, email e telefone não podem ser labels do Prometheus. Isso geraria cardinalidade não limitada. ## Loki Centraliza logs estruturados. Loki não oferece autenticação própria por padrão; seus endpoints permanecerão privados e protegidos por proxy autenticado. Logs comuns não armazenam texto completo de conversa, prompts, tokens ou secrets. ## Tempo Armazena traces distribuídos para acompanhar uma operação através de: ```text theme={null} API → PostgreSQL outbox → Valkey/BullMQ → Worker → AI Runtime → Provider externo ``` Sampling e retention serão ajustados por ambiente e risco. ## Grafana Exibe dashboards, alerts e navegação entre metrics, logs e traces. Dashboards operacionais são internos. Eles não substituem analytics de produto e não expõem dados de tenants indiscriminadamente. ## Error tracking ### GlitchTip Opção open source MIT para agrupamento de erros, performance e uptime. É compatível com eventos gerados por SDKs Sentry. ### Sentry SDKs e serviço hospedado poderão ser providers opcionais. O backend self-hosted não é default porque suas versões atuais utilizam FSL com futura conversão para Apache 2.0 e possuem operação mais pesada. ## AI observability Cada run registra: * Agent/template version. * Modelo e provider. * Token e custo. * Latência. * Tool calls e outcome. * Policy decisions. * Approval ou handoff. * Evaluation result. Detalhes de prompts e outputs usam acesso e retenção restritos. ## Contexto ```text theme={null} traceId spanId correlationId causationId organizationId técnico quando necessário service plugin/provider job/event type ``` Nenhum contexto deve conter credential ou PII desnecessária. ## Alertas * Alertar sintomas visíveis e capacidade esgotada. * Evitar alerta para cada exception individual. * Linkar todo alerta a um runbook. * Testar routing periodicamente. * Utilizar SLO e burn rate quando aplicável. ## Falha da observabilidade Telemetry export é assíncrono e bounded. Uma queda do collector não pode bloquear appointments, mensagens ou pagamentos. ## Links oficiais SDK e releases para JavaScript. Collector de metrics, logs e traces. Metrics e alerting. Logs centralizados. Distributed tracing. Error tracking open source.