Início Rápido

Instale, instrumente, valide e rode Obtrace em produção em menos de 30 minutos

Este guia é intencionalmente opinativo: ele entrega o caminho mais curto para valor real em produção, não apenas uma demo local.

Ao final, você terá:

  • Um serviço backend instrumentado e enviando dados.
  • Instrumentação opcional de frontend ligada ao mesmo modelo de contexto.
  • Contexto de runtime e CI/CD disponível na investigação.
  • Interfaces prontas para IA (Ask AI, llm.txt, mcp.json).

Pré-requisitos

  • Conta Obtrace com chave de API.
  • Acesso a um serviço relevante de produção.
  • Acesso à configuração de deploy (env vars/secrets).
  • Acesso ao pipeline de CI/CD (recomendado para correlação com release).

Como Saber se Deu Certo

Antes de começar, defina critérios de aceite:

  1. Telemetria chega continuamente para o serviço alvo.
  2. Você consegue filtrar por service, env e version sem ambiguidade.
  3. Pelo menos um erro/trace tem contexto suficiente para diagnóstico.
  4. Picos de telemetria podem ser associados a release/deploy.

Passo 1: Configure Autenticação Corretamente

Siga Autenticação e crie credenciais por ambiente.

Estratégia recomendada de chaves:

  • Uma chave por ambiente (dev, staging, prod).
  • Opcionalmente, uma por serviço para reduzir blast radius.
  • Chaves privilegiadas apenas no servidor.

Passo 2: Instrumente Primeiro o Serviço Backend Mais Crítico

Escolha o serviço com maior risco operacional (checkout, auth, billing, API gateway).

  1. Selecione runtime no Catálogo de SDKs.
  2. Instale e inicialize SDK.
  3. Adicione atributos canônicos em todo evento/span:
    • service
    • env
    • version
    • region (se multi-região)

Essa ordem gera maior valor diagnóstico por minuto investido.

Passo 3: Adicione Instrumentação de Frontend (Se Impacto no Usuário For Relevante)

  • Use SDK JavaScript Browser.
  • Capture contexto de página/rota/interação quando fizer sentido.
  • Correlacione falhas de frontend com requisições backend.

Isso transforma “backend lento” em “qual fluxo de usuário degradou e por quê”.

Passo 4: Valide Ingestão e Qualidade dos Dados

Não avance rollout sem passar nesse gate.

Checklist de validação:

  • Fluxo contínuo, sem comportamento muito em rajadas.
  • Timestamps corretos (sem drift severo).
  • Sampling intencional e documentado.
  • Sem frequência alta de 401/403 ou retries de transporte.
  • Tags estáveis e padronizadas.

Passo 5: Adicione Integração de Runtime

Conecte cedo o ambiente real de execução:

Objetivo: contexto do incidente precisa incluir onde a carga rodou.

Passo 6: Anexe Contexto de CI/CD

Integre GitHub Actions para ler telemetria junto com eventos de release.

Campos mínimos de contexto de release:

  • commit SHA
  • build ID
  • timestamp de deploy
  • ambiente

Sem contexto de release, a análise de causa raiz sempre perde tempo.

Passo 7: Ative Fluxos de IA (Depois do Baseline Limpo)

  • Use botão flutuante Pergunte à IA nas docs.
  • Publique contexto legível por máquina em /llm.txt e /mcp.json.
  • Revise MCP para integração com agentes.

Fluxo de IA só funciona bem com telemetria de qualidade.

Erros Comuns

  1. Começar por serviços demais ao mesmo tempo.
  2. Falta de tags service/env/version.
  3. Reutilizar uma única chave em todos os ambientes.
  4. Rollout sem validar qualidade de ingestão.
  5. Tratar docs como referência passiva em vez de manual operacional.

Próximos Caminhos

Nesta página