A DevGuide do ExeWatch

Uma cláusula uses e uma linha de inicialização. Todo o resto do guia não faz nada além de refinar essas duas coisas.

1. Adicione o SDK à sua cláusula uses. Em um app VCL, ou seja, a esmagadora maioria dos apps Delphi, são duas units: a segunda é a que captura as exceções da GUI.

Das duas units de hook você coloca só uma, a do framework que está usando. Se o app não tem GUI, por exemplo um serviço Windows ou um utilitário de linha de comando, não adicione nem a .VCL nem a .FMX: não existe message loop nenhum onde instalar um hook e ExeWatchSDKv1 sozinho já basta.

2. Inicialize uma única vez, cedo (no .dpr antes de Application.Run, ou no evento OnCreate do formulário principal):

Dois argumentos: a API key que você copia do console e o id do cliente a que pertence esta instalação. Pronto, o app está monitorado.

O que você levou para casa com aquelas duas linhas. Deste momento em diante os crashes são registrados com o seu stack trace sem que você escreva mais nada, e as duas units dividem o trabalho. ExeWatchSDKv1 instala um hook em System.ExceptProc, onde vão parar as exceções não tratadas do código normal. ExeWatchSDKv1.VCL (ou .FMX) pega, em vez disso, as que escapam dentro de um evento, um OnClick ou um OnCreate: quem as intercepta é o message loop do framework, que as entrega a Application.OnException, e ali o percurso termina, em System.ExceptProc elas nunca chegam. Em um app desktop são a categoria de crash mais frequente, e é por isso que a segunda unit importa.

Sobe também um log automático Application started, a confirmação de que a integração está viva, e as informações do dispositivo (sistema operacional, máquina, versão do binário) são enviadas e ligadas ao cliente, para aparecer em "Devices" no console. Nada disso viaja na thread da sua aplicação: os eventos vão para uma fila em disco e uma thread em segundo plano os envia, então uma rede lenta ou um servidor inalcançável não deixam o app lento nem o travam.

A unit de hook não tira de você o handler que já tinha: se você já tinha o seu próprio Application.OnException, o hook registra o log e depois o chama; se não tinha, chama Application.ShowException. A janela de erro que o seu usuário via antes continua aparecendo igual. E se um dia você esquecer dela em outro projeto, não fica no escuro: o SDK percebe que está rodando em um app com GUI sem hook instalado e escreve ele mesmo um Warning com tag exewatch, que você encontra no dashboard.

3. Registre o que te interessa. Daqui em diante você registra, conta e cronometra toda vez que tiver algo digno de nota:

Abra o dashboard e os eventos estão lá. Daqui para a frente o guia serve para te fazer lembrar de tudo o que merece acabar lá dentro, porque a lista é mais longa do que a que te viria à cabeça agora.

O Quickstart era em Delphi, o SDK carro-chefe. O o quê e o por quê no resto do guia valem igualmente para cada SDK: muda apenas o modo de integrá-lo e inicializá-lo. Eis o setup de cada um. Em todos o último argumento é o rótulo de release (AppVersion), e a API key tem o prefixo da plataforma (ew_win_, ew_lin_, ew_web_ e assim por diante).

Delphi (nativo). Como no Quickstart: ExeWatchSDKv1 na cláusula uses, mais ExeWatchSDKv1.VCL (ou .FMX) se o app tem GUI, depois InitializeExeWatch(ApiKey, CustomerId, '4.2.0'). A unit VCL/FMX captura para você as exceções de GUI não tratadas.

.NET. Referencie o pacote ExeWatch (adicione ExeWatch.WinForms para um app WinForms), depois inicialize uma única vez ao iniciar:

Um app console ou um serviço pula a linha Install: o client instala sozinho um hook em AppDomain.UnhandledException. Já o WinForms exige a chamada Install explícita antes de Application.Run.

Python. Instale o SDK, inicialize o singleton e depois use o objeto ew em nível de módulo:

Python não tem uma GUI onde instalar um hook, então capture as falhas onde você as trata com ew.error_with_exception(exc, "tag"), ou aponte sys.excepthook para o SDK para ter uma rede de segurança global.

JavaScript (browser). Você declara a configuração em window.ewConfig e depois carrega o script de exewatch.com. A chave é uma chave ew_web_, e o SDK captura automaticamente window.onerror:

A ordem importa: o SDK se inicializa sozinho no DOMContentLoaded lendo window.ewConfig, portanto a configuração já deve estar na página quando o script for carregado. O script você serve de exewatch.com, não de uma cópia sua, assim as correções chegam aos seus usuários sem que você tenha que redistribuir nada.

Este SDK é só para browser, não existe uma build para Node. Os erros não capturados são coletados para você, junto com as falhas de fetch e XHR e os console.error. Em uma página que carrega scripts de terceiros, ignoreUrls na mesma ewConfig descarta os erros que vêm de domínios que você não controla, tipo publicidade e analytics: é ruído que não te diz nada sobre a sua aplicação.

DLL (C, C++, VB, .NET legado, qualquer coisa com uma ABI C). Carregue ExeWatchSDKv1DLL.dll e chame os exports flat. As strings são wide (PWideChar), cada função é stdcall e os resultados voltam como códigos de retorno:

Como uma ABI C flat não consegue percorrer o stack do host nem executar um callback, duas tarefas recaem sobre o host: passar uma string de stack já resolvida para ew_ErrorWithStackTrace, e disparar os gauges periódicos a partir de um timer seu (não existe callback para os gauges periódicos). Um host Delphi que prefira a DLL às units nativas pode usar a import unit ExeWatchSDKv1Imports e chamar EWInitialize(…​) no lugar de InitializeExeWatch.

O mesmo, por inteiro, com MSVC. Nenhuma import library e nenhum runtime Embarcadero: defina EW_DYNAMIC_LOAD antes do header e cada ew_* vira um ponteiro de função, que ExeWatchSDKv1.dynload.c resolve em runtime com LoadLibrary e GetProcAddress. Este é um programa completo, não um fragmento:

Compila-se em um comando só, a partir de um prompt "x64 Native Tools Command Prompt for VS 2022", passando a pasta que contém header e loader:

A única linha que aqui não é cerimônia é ew_WaitForSending. Um utilitário de linha de comando pode terminar antes que a thread de envio tenha esvaziado a fila, e aquela chamada escreve o buffer em disco e espera a fila esvaziar, retornando quantos eventos ainda estão aguardando. Não é um problema de perda de dados, porque a fila fica em disco e recomeça na execução seguinte, mas sem a espera os seus eventos aparecem no dashboard com uma rodada de atraso. O exemplo compilável com todo o resto, identidade do usuário, tags globais, breadcrumbs, timings aninhados e gauges, está em ExeWatchSamples/MSVCWithDLLSDK.

A mesma DLL a partir de um console Delphi. Um host Delphi também pode usar a DLL em vez das units nativas, e em dois casos é a escolha certa: quando você está em um Delphi mais antigo que o XE8, que é o mínimo do SDK nativo, e quando você tem várias aplicações que precisa atualizar distribuindo um binário só. A import unit ExeWatchSDKv1Imports chega até o Delphi 5. Este também é um programa inteiro:

Os wrappers com o prefixo EW aceitam string e a conversão para PWideChar eles fazem sozinhos, portanto no seu código não aparece nenhum cast. Por se tratar de um console, valem as mesmas duas linhas de antes: ew_WaitForSending antes de sair, e ew_Shutdown para fechar limpo.

Uma coisa para saber antes de distribuir. Por padrão a unit liga a DLL estaticamente, portanto ExeWatchSDKv1DLL_x64.dll precisa estar ao lado do executável no momento da inicialização: se faltar, o processo não sobe de jeito nenhum, o Windows o bloqueia com um erro de DLL ausente antes mesmo da sua primeira linha de código. Se você prefere que a aplicação suba de qualquer forma e abra mão apenas da telemetria, defina EW_DYNAMIC_LOAD nas opções de projeto: a unit passa a usar LoadLibrary, e você chama EWLoadDLL na inicialização verificando o resultado, como faz o exemplo MSVC aqui em cima.

E com Free Pascal. A DLL não tem nada de específico do Delphi: é uma ABI C flat, stdcall, strings wide. No Windows a mesma ExeWatchSDKv1Imports compila com o FPC, que a unit reconhece e coloca em {$MODE DELPHI} sozinha. Onde string não é Unicode o alias interno vira WideString e os wrappers EW* convertem para você, portanto o código que você escreve continua sendo o do exemplo aqui em cima.

A única chamada a InitializeExeWatch do Quickstart é tudo de que a maioria dos apps vai precisar algum dia. Aquele terceiro argumento é o AppVersion, o seu rótulo de release ('4.2.0', '2026-Q1', 'v2-beta'); a versão do binário, por sua vez, é um campo separado, detectado automaticamente a partir do executável, portanto daquela única linha você obtém as duas. Eis o que fazer quando aquela linha não bastar.

É um fluxo deliberado e suportado, não um improviso. Enquanto o id do cliente estiver vazio o SDK segura o registro com as informações do dispositivo, porque ele precisa do id para ligar o dispositivo ao cliente certo, e o envia no instante em que você chamar SetCustomerId. Se depois o id mudar (um cliente diferente na mesma máquina) o SDK reenvia as informações do dispositivo sob o novo cliente, assim o dispositivo aparece corretamente para os dois. A regra é simples: primeiro inicialize, depois identifique assim que puder.

Cliente e usuário são duas identidades diferentes, definidas com duas chamadas diferentes. SetCustomerId define o cliente: a conta ou tenant a que pertence esta instalação, ou seja, o critério com que o dashboard agrupa dispositivos e alertas. Quem está de fato usando o app é outra coisa, o usuário, e esse você define com SetUser:

Id, e-mail e nome viajam depois com cada evento como user_id, assim um crash mostra não só qual cliente o encontrou mas também qual pessoa. Use SetCustomerId para a conta e SetUser para a pessoa: são independentes, e você pode definir um, o outro, os dois ou nenhum dos dois.

Quando a chamada de três argumentos não bastar, construa um TExeWatchConfig e passe-o. Cada campo tem um padrão sensato, então defina só o que você precisa:

As configurações que vale a pena conhecer:

Os outros SDKs adotam os mesmos conceitos sob nomes de campo bem parecidos; a referência tem a assinatura exata de cada um.

Um dashboard vazio intimida, e a primeira pergunta é sempre a mesma: por onde eu começo? A resposta curta é que se uma coisa te interessa, ela precisa ser registrada. Te interessa saber se aquela função falha? Registre. Quantas vezes ela é usada? Conte. Se é lenta e quanto? Cronometre. O erro que se paga caro não é ter mandado alguns eventos a mais, é se ver diante de um problema em produção e descobrir que justamente aquele pedaço de código não conta nada.

Aquele momento sempre chega, e chega numa terça à tarde com um cliente no telefone. Você tem o stack trace do crash mas não sabe o que o usuário estava fazendo um instante antes, porque aquela passagem você não tinha registrado. Sabe que a sincronização demora uma eternidade mas não qual fase a devora, porque você tinha cronometrado só o total. Naqueles vinte minutos você nunca lamenta as linhas que mandou a mais. Você lamenta as três que não escreveu.

Portanto comece generoso. Se algo pode falhar, se pode ficar lento, se você precisa saber o quanto é usado, se explica por que o app se comportou de um certo jeito, mande. Acrescentar é fácil enquanto você está escrevendo o código; acrescentar depois, quando a build em questão já está instalada em trezentos clientes, significa um lançamento e semanas de espera. E o ruído, se um dia houver demais, você tira quando quiser: o nível mínimo e a amostragem de cada aplicação você muda pelo console, sem recompilar nada.

A única coisa que não vale a pena mandar é aquela que não diz nada nem para você: um Debug('estou aqui'), um Info('step 1'), uma mensagem que te parece útil enquanto você a escreve só porque naquele momento o contexto está na sua cabeça. Quando você a reencontra em uma lista de logs, meses depois, aquele contexto não existe mais e a linha perdeu todo o sentido. O resto do guia serve para te fazer lembrar do que, esse sim, merece estar ali, e para escolher a ferramenta adequada a cada coisa, visto que um crash, uma contagem de uso e uma duração se registram de três formas diferentes.

Antes das receitas, o mapa. O ExeWatch coloca à sua disposição cinco ferramentas, e cada uma existe para responder a uma pergunta diferente. Quase toda decisão do tipo "o que eu rastreio aqui?" fica óbvia assim que você sabe qual pergunta está se fazendo.

Duas coisas escapam com facilidade, e as duas te poupam trabalho de verdade mais adiante.

As tags são a sexta ferramenta silenciosa. Toda chamada de log, counter, gauge e timing aceita uma tag, e existe um SetTag válido para o processo inteiro, para o contexto que viaja com tudo. As tags são o modo como você fatia o dashboard em "payment" contra "sync" contra "ui" sem inventar uma métrica separada para cada funcionalidade. Acerte nelas e todo gráfico é filtrável exatamente como você raciocina; erre nelas e o dashboard vira ruído. A seção sobre higiene das tags é a próxima, e é curta.

As informações do dispositivo são automáticas e de graça. Versão do app, versão do binário, OS e hardware viajam com cada lote sem uma única chamada da sua parte. Não os registre de novo. O único campo que você define na mão é o AppVersion, o rótulo de release, e é justamente ele que mais adiante torna possível a comparação entre versões.

Uma tag serve para filtrar, não para transportar dados. Mantenha-as curtas, poucas e estáveis ao longo do tempo, e o dashboard continua legível mesmo depois de alguns anos de acréscimos.

Na prática:

Defina uma única vez, na inicialização, o contexto que nunca muda, assim você não o repete a cada chamada:

A partir daquele momento cada evento carrega consigo aquele contexto, e você pode filtrar o dashboard inteiro até chegar, por exemplo, apenas à edição Pro no canal stable sem tocar em outra linha de código.

As tags que você define com SetTag (ou com GlobalTags no init) viram um filtro "Global Tags" no console, assim você pode fatiar cada visão por ambiente, edição, feature flag e qualquer outra coisa que você tenha etiquetado.

As receitas que seguem usam Delphi. Os conceitos são idênticos entre os SDKs; muda só a grafia. Esta tabela é o mapa, assim um leitor .NET ou Python consegue traduzir qualquer snippet num relance. A referência no console tem as assinaturas completas.

Dois fatos específicos dos SDKs para levar consigo em cada receita: a DLL não tem callback para os gauges periódicos, então a amostragem você dispara a partir de um timer seu, e o JavaScript é só para browser. Todo o resto é uma simples reescrita um para um.

Cada receita parte de uma situação em que você já se viu, ou vai se ver, e sobe até a única coisa que vale a pena instrumentar. Um snippet Delphi canônico para cada uma; use a tabela aqui em cima para traduzi-lo para o seu SDK. Onde o comportamento muda de verdade, está sinalizado.

Estas três ferramentas são confundidas o tempo todo, e confundi-las não lança um erro, registra em silêncio dados que não significam nada, o que é pior. A distinção é simples, uma vez dita em voz alta:

Na dúvida, tente somar duas leituras. Se a soma faz sentido, 12 exports mais 8 exports dão 20 exports, é um counter. Se não faz sentido, uma fila de 12 mais uma fila de 8 não dá uma fila de 20, é um gauge. Se o que te interessa é o tempo decorrido, é um timing.

Um alerta é o que te permite parar de olhar o dashboard. Em vez de conferir de vez em quando torcendo para flagrar um problema, você descreve o problema uma vez e o ExeWatch te manda um e-mail quando ele acontece. Hoje existem dois tipos, e convém saber com precisão sobre o que cada um dispara, porque os limites honestos do alerting moldam o modo como você usa tudo o que vem acima.

Os alertas de volume de log disparam quando a contagem dos eventos de log iguais ou superiores a um nível ultrapassa um limiar dentro de uma janela. Você define threshold (uma contagem), window_minutes, min_level (padrão error), um filtro tags opcional, um customer_external_id opcional e cooldown_minutes (padrão 60) para que um único incidente não te notifique cinquenta vezes. Um típico diz: "mais de 20 eventos fatal em 15 minutos para o cliente Acme".

O mesmo alerta como formulário no console, em "Configure alerts": um limiar sobre uma janela temporal em um nível mínimo, com um cooldown, se necessário restrito por tag e por cliente. Colocar "Filter by Customer" em Acme é o jeito de ser avisado dos erros da Acme sem ouvir falar de mais ninguém.

Taxa de erro ao longo do tempo. Um pico como esses aqui é exatamente o que um alerta de volume de log vigia, assim ele te alcança por e-mail no instante em que começa, em vez de quando você por acaso abrir este gráfico.

Os alertas de timing disparam quando as operações que correspondem a um padrão de id de timing rodam mais lentas que um limiar de duração, com frequência suficiente para ultrapassar um limiar de contagem dentro de uma janela. Os campos são um timing_id_pattern, um limiar de duração em milissegundos, um limiar de ocorrências threshold (padrão 5), window_minutes, um customer_external_id opcional e cooldown_minutes (padrão 240). É assim que você garante ser avisado de que "report.render está rodando lento em campo" sem ter que ficar vigiando.

O jeito de manter os alertas úteis em vez de ignorados: mantenha honestos os seus níveis de log (veja anti-pattern, senão o seu limiar error dispara em coisas que erros não são), dê a cada alerta um escopo por tag ou por cliente para que ele tenha um dono claro, e coloque um cooldown longo o bastante para que um incidente de verdade chegue como um único e-mail.

Você lança uma versão e quer saber se ela ficou mais lenta ou mais barulhenta que a anterior. Hoje essa comparação passa pelo export CSV, e vale a pena explicitar o fluxo porque ele responde a uma pergunta que os clientes fazem o tempo todo.

O mesmo export existe nas páginas "Logs" e "Metrics", assim você pode comparar o volume de erros ou os níveis de métrica entre as versões do mesmo jeito. Um filtro de timing por versão dentro da interface está no backlog; quando chegar, isto vai virar um par de cliques em vez de uma tabela dinâmica. Até lá, o caminho do CSV é o modo suportado para a comparação versão a versão, e funciona bem o bastante para que vários times parem por aí.

Como cada evento carrega o seu AppVersion, o console já sabe como as suas releases estão distribuídas em campo. É sobre esse mesmo rótulo de versão que você cria a tabela dinâmica do timing exportado.

As chamadas isoladas são fáceis de aprovar com um aceno de cabeça e difíceis de posicionar. Eis então a instrumentação aplicada a código comum: um método de sync em um data module, do tipo que todo sistema de gestão em Delphi tem. Primeiro a versão nua, que faz o seu trabalho sem telemetria:

Agora o mesmo método instrumentado, cada acréscimo faz exatamente um trabalho:

O que foi parar onde, e por quê:

Note a forma: a instrumentação emoldura o código real, não o substitui. Apague cada linha EW. e o método continua funcionando exatamente como antes. A instrumentação se limita a observar.

Nenhum destes é "você registrou demais". São os casos em que o que você manda te engana em vez de te ajudar, e a correção está ao lado de cada um.

Repetir a mesma linha dentro de um laço. Uma chamada Debug em um laço quente, ou um IncrementCounter a cada iteração. A questão não é a quantidade: é que quinhentas linhas idênticas respondem todas à mesma pergunta que a primeira já tinha respondido, e nesse meio-tempo consomem a cota que servia aos eventos de verdade. Registre a operação, não as suas iterações: uma linha quando ela começa, uma quando termina ou falha, e um único incremento de counter por operação lógica. Se o detalhe por iteração te serve mesmo durante um diagnóstico, mantenha-o em nível Debug e suba o nível mínimo da aplicação pelo console quando terminar.

Dados pessoais nos logs. E-mails, nomes, tokens ou conteúdos de arquivos em uma mensagem ou em uma tag. Os logs são conservados e exportados em CSV, e as tags são dimensões de baixa cardinalidade, não payload, então isso é ao mesmo tempo um problema de privacidade e uma bagunça. Registre ids e categorias; use o campo id do cliente para a identidade.

Níveis que mentem. Tudo registrado em Error, ou falhas de verdade registradas em Info. Os alertas usam por padrão min_level = error, portanto se os seus níveis estão errados os seus alertas também estão, e ou você é notificado à toa ou nunca é notificado. A escala que os mantém honestos: Fatal significa que o app não pode continuar, Error que uma operação falhou, Warning degradado mas funcionando, Info uma mudança de estado notável, Debug detalhe só para desenvolvedores.

Gauge e counter, trocados. Um counter para "profundidade de fila atual" soma níveis em um total sem sentido; um gauge para "número de exports" joga fora o total. Aplique o teste da adição da tabela aqui em cima antes de escolher.

Tags que explodem. Um id, um timestamp, ou qualquer valor por requisição em uma tag. As tags são dimensões com um pequeno conjunto fixo de valores; valores ilimitados se multiplicam em milhares de dimensões descartáveis e tornam o dashboard inutilizável. Mantenha o vocabulário pequeno.

Registrar de novo o que você já ganha de graça. Registrar na mão OS, versão ou hardware que já viajam no snapshot do dispositivo a cada lote. Não faça isso. O único campo que você define na mão é o AppVersion, o rótulo de release.

Os apps desktop rodam em notebooks que entram em túneis, em máquinas atrás de VPNs caprichosas, em um PC que alguém desconecta da rede ao sair. Então a pergunta é legítima: o que acontece com a sua telemetria quando o SDK não consegue alcançar o servidor?

Não se perde nada. O SDK não envia os eventos direto do ponto em que você os chama. Ele os acumula em um buffer, escreve em disco, e quem cuida de enviá-los é uma thread de envio em segundo plano. Quando a rede está fora o envio simplesmente falha, os arquivos ficam em disco, e a thread tenta de novo em intervalos. No instante em que a conectividade volta, os arquivos na fila são enviados em ordem. Um crash registrado no avião aparece no seu dashboard na primeira vez que o notebook volta a ficar online.

Quem governa isso são quatro configurações do TExeWatchConfig:

O acúmulo você mesmo pode acompanhar: GetPendingCount retorna quantos eventos ainda estão esperando para ser enviados.

Um fato técnico para conhecer, e ele chega no fim do guia de propósito: a cota mensal conta os eventos que você nos manda, não os que ficam armazenados. Contam juntos os logs e as atualizações das métricas, ou seja, counters, gauges e timings, não só os logs. As mensagens internas do SDK, aquelas com tag ew.system, não entram na contagem. E como conta o que chegou, apagar dados libera espaço mas não devolve cota.

Não é um convite a instrumentar menos. A ordem certa é a que você seguiu até aqui: primeiro decida o que quer ver, depois, se e quando o volume virar um tema, você o governa. As ferramentas para governá-lo existem e ninguém está te pedindo para abrir mão de um dado que te interessa.

Se você está sempre perto do teto com uma instrumentação que te serve toda, não há nada a cortar: você está acompanhando mais aplicações ou mais clientes do que quando escolheu o plano, e a essa altura convém passar para o nível seguinte.

Algumas coisas que as pessoas pedem estão planejadas mas ainda não lançadas. Estão listadas aqui, honestamente, para que você saiba onde estão hoje as fronteiras e não vá procurar uma funcionalidade que ainda não existe.

Para tudo o que existe hoje, a referência do SDK no console tem as assinaturas exatas, as chaves de configuração e os passos de instalação. Este guia é o quê e o porquê; aquela é o como.