Tracking Plan -- Pilot Status

Status

Draft

Objetivo

Definir todos os eventos, métricas e propriedades que devem ser coletados para monitorar comportamento de usuários, uso da API, performance, conversão e saúde operacional da plataforma Pilot Status.

1. Princípios

• Todos os eventos devem conter tenant_id
• Todos os eventos devem conter environment (test | live)
• Todos os eventos devem conter timestamp
• Sempre incluir correlation_id quando relacionado a envio de mensagem
• Eventos de produto separados de eventos técnicos

2. Eventos de Autenticação

user_signed_up

Quando um usuário cria conta.

Propriedades: - user_id - provider (google | github)

user_logged_in

Quando usuário faz login.

Propriedades: - user_id - provider

3. Eventos de API Key

api_key_created

Quando nova API key é criada.

Propriedades: - tenant_id - environment - key_prefix (ps_test | ps_live)

api_key_deleted

Propriedades: - tenant_id - environment

4. Eventos de Template

template_created

Propriedades: - tenant_id - environment - template_id - version_number

template_submitted_for_approval

Propriedades: - tenant_id - template_id - version_number

template_approved

Propriedades: - tenant_id - template_id - version_number - admin_id

template_rejected

Propriedades: - tenant_id - template_id - version_number - admin_id - rejection_reason

5. Eventos de Mensagem

message_requested

Disparado quando cliente chama endpoint de envio.

Propriedades: - tenant_id - environment - template_version_id - api_key_id - destination_number

message_queued

Quando job é enviado para fila.

Propriedades: - tenant_id - queue_name - job_id

message_sent

Quando Evolution API confirma envio.

Propriedades: - tenant_id - template_version_id - latency_ms

message_failed

Propriedades: - tenant_id - template_version_id - failure_reason

message_read

Propriedades: - tenant_id - template_version_id

6. Rate Limiting

rate_limit_exceeded

Propriedades: - tenant_id - api_key_id - environment - plan_type (free | basic | pro) - limit_type (monthly | daily), para derivar se o limite foi mensal ou diário

7. Eventos de Admin

user_approved_for_production

Propriedades: - tenant_id - admin_id

production_request_submitted

Propriedades: - tenant_id - video_uploaded (true | false)

8. Eventos de Planos e Assinatura

plan_subscribed

Quando tenant assina ou está em um plano pago.

Propriedades: - tenant_id - plan (free | basic | pro) - provider (stripe | pague_dev) - amount

plan_changed

Quando plano é alterado (upgrade ou downgrade).

Propriedades: - tenant_id - previous_plan - new_plan

subscription_cancelled

Quando assinatura é cancelada.

Propriedades: - tenant_id - plan

9. Eventos de Pacotes

package_purchased

Quando pacote de mensagens adicionais é comprado.

Propriedades: - tenant_id - package (1 | 2) - messages_added (300 | 1000) - amount - provider (stripe | pague_dev) - payment_method (card | pix)

10. Eventos de Pagamento

payment_completed

Quando pagamento é confirmado.

Propriedades: - tenant_id - type (subscription | package) - provider - amount - payment_method

payment_failed

Quando tentativa de pagamento falha.

Propriedades: - tenant_id - type - provider - reason (opcional)

11. Métricas Derivadas (KPIs)

Essas métricas não são eventos, mas derivadas dos dados:

Produto

• Total de mensagens enviadas por dia
• Taxa de falha (%)
• Tempo médio de envio
• Conversão test → live
• Templates criados por tenant
• Templates aprovados vs rejeitados

Negócio

• Mensagens por plano
• Uso médio por tenant
• Uso médio por plano
• Receita por tenant (quando aplicável)
• Receita por plano (Basic, Pro)
• Receita por pacotes (Pacote 1, Pacote 2)
• Conversão free → Basic/Pro
• Crescimento semanal de tenants

Operacional

• Jobs ativos por fila
• Tempo médio na fila
• Falhas por tenant
• Uso de Redis (memória)
• Latência média da Evolution API

12. Armazenamento

Eventos podem ser armazenados:

• Banco relacional (tabela de eventos) OU
• Umami como ferramenta de analytics para eventos de frontend e backend

Logs estruturados devem ser separados de eventos de produto.

13. Observabilidade Técnica

Implementar:

• Correlation ID por mensagem
• Logs estruturados (JSON)
• Monitoramento de filas
• Umami para analytics de frontend e backend
• Alertas internos para:
  • Alta taxa de falha
  • Fila acumulando
  • Rate limit excessivo

14. Eventos Futuramente Planejados

• retry_triggered (quando retry for implementado)
• dlq_message_created (quando DLQ for implementado)
• api_key_rotated
• backup_completed
• invoice_paid (Stripe), pix_paid (Pague Dev) para auditoria de pagamentos

Conclusão

Este Tracking Plan garante:

• Visibilidade completa do comportamento do produto
• Base para métricas de negócio
• Monitoramento técnico robusto
• Capacidade futura de crescimento orientado por dados