As anotações em gráficos permitem marcar eventos importantes - deploys, releases, campanhas de marketing, incidentes, marcos personalizados - em cada gráfico de série temporal do Zenovay. Quando o tráfego ou a receita variam, você vê o que mudou no mesmo momento sem sair do painel.
Por que anotações importam
A maioria das perguntas de analytics se reduzem a "o que mudou?". Uma queda inesperada na terça à tarde é muito mais fácil de triar quando você vê "deploy: release v2.5" marcado às 14:32. As anotações transformam o painel em uma única linha temporal onde métricas de negócio e eventos operacionais convivem.
Os cinco tipos de anotação
| Tipo | Cor | Uso típico |
|---|---|---|
deploy | Azul | Deploys de código, mudanças de infraestrutura, push de configuração |
release | Esmeralda | Anúncios públicos de release, cortes de versão |
campaign | Âmbar | Campanhas de marketing, lançamentos de anúncios, envio de emails |
incident | Vermelho | Incidentes que impactam clientes, indisponibilidades |
custom | Violeta | Qualquer outra coisa - reuniões, integrações de parceiros, auditorias |
Cada tipo tem um ícone e cor distintos para identificar de relance o que mudou.
Três formas de criar anotações
Opção 1 - No painel
Abra o painel do seu site e selecione a aba Analytics, depois clique no ícone de nota em qualquer ponto do gráfico de visitantes. A caixa de diálogo de detalhes do dia se abre com três abas: Notes, Annotations e Commits. Na aba Annotations, escolha um tipo (deploy, release, campaign, incident ou custom), digite uma mensagem e adicione-a. O marcador aparece imediatamente no gráfico.
Essa é a forma mais rápida de marcar um evento pontual. Para deploys que você realiza regularmente, a CLI abaixo é mais apropriada.
Opção 2 - CLI da Zenovay (recomendada para CI)
A CLI é o caminho canônico para marcar deploys a partir de um pipeline de CI. Cuida da autenticação via login da sua conta e funciona em macOS, Linux e Windows.
zenovay annotation create --type=deploy --message="release v2.5"
Adicione como último passo do seu pipeline de deploy para que cada
release se marque automaticamente. O comando sai com um código distinto
em erros de limite de plano (4) ou duplicado (5) para que seu
pipeline possa lidar com cada caso. Veja o
guia de integração da CLI
para todos os flags e um exemplo de GitHub Actions.
Opção 3 - API REST
Há também um endpoint /api/annotations que o painel utiliza. Ele
se autentica com sua sessão de painel (o mesmo login que você usa no
navegador), então é apenas prático para um servidor que já possui uma
sessão válida. Chaves de API externas zv_* não são aceitas neste
endpoint atualmente, então para CI e outros ambientes automatizados,
a CLI acima é a ferramenta correta - ela cuida da autenticação para você.
Veja a referência da API de Anotações em gráficos
para a forma completa de requisição e resposta.
Limites do plano e comportamento
- Gratuito: 10 anotações por time por mês.
- Pro e superior: ilimitado.
Uma anotação do mesmo type e a mesma mensagem dentro de 5
minutos de uma existente é rejeitada para evitar que um pipeline
mal configurado inunde a linha temporal com duplicatas. Duas anotações
do mesmo tipo com mensagens diferentes (por exemplo, "checkout quebrado"
e depois "checkout corrigido") são ambas permitidas.
Onde as anotações aparecem
- Abaixo de cada gráfico de analytics voltado ao cliente como uma faixa de chips coloridos. Passe o mouse para ver a mensagem completa e o horário exato.
- No painel de triagem de incidentes de conversão como "mudança suspeita" quando a anotação cai dentro de ±2 horas do início do incidente.
- Na posição do ícone de notas legado do gráfico de visitantes do domínio, se você já usa o recurso anterior. As duas superfícies ficam sincronizadas automaticamente.
Lendo a faixa de chips
Cada chip abaixo de um gráfico é codificado por cor de acordo com o tipo, com o ícone à esquerda. As cinco cores se mantêm consistentes em todos os gráficos e páginas: depois de aprendê-las, você consegue escanear a faixa de relance. Um grupo azul = deploys, âmbar = campanhas, vermelho = incidentes. O chip mostra sua mensagem e o horário de criação; passe o mouse para ver o timestamp completo.
Privacidade: painéis públicos NUNCA mostram anotações
Se você compartilhar um link público com alguém fora do seu time, as anotações ficam ocultas. Mensagens de deploy e release são para o time que opera o site, não para os visitantes. Não há como expor mensagens de anotação publicamente.
Padrões comuns
Marcar todo deploy de produção automaticamente: adicione o comando da CLI como passo pós-deploy. Zero trabalho manual após o cabeamento inicial.
Marcar o lançamento de uma campanha:
zenovay annotation create --type=campaign --message="Promoção de outono"
no momento do go-live. Quando revisar o lift de tráfego depois, o
marcador já estará no gráfico.
Marcar um incidente conhecido: poste uma anotação de incidente para que o gráfico explique visivelmente a queda. Combina naturalmente com a triagem de incidentes de conversão.
Solução de problemas
- "Annotation limit reached": limite mensal do plano Gratuito atingido. Faça upgrade para Pro para ter ilimitado.
- Erro HTTP 409 (dedup): você está tentando postar uma anotação do mesmo tipo e a mesma mensagem dentro de 5 minutos de uma existente. Aguarde, mude o tipo, ou aceite que o primeiro marcador já representa o evento. (A CLI retorna código de saída 5 para este caso.)
- A faixa de chips não aparece: confirme que existe pelo menos uma anotação para aquele site. A faixa permanece oculta quando não há nada para mostrar.
- O chip está no idioma ou tema errado: tema segue o tema do painel; idioma segue a localidade do navegador. Ambos mudam automaticamente.