La DevGuide de ExeWatch

Una cláusula uses y una línea de inicialización. Todo el resto de la guía no hace más que refinar esas dos cosas.

1. Añade el SDK a tu cláusula uses. En una app VCL, es decir la inmensa mayoría de las apps Delphi, son dos units: la segunda es la que captura las excepciones de la GUI.

De las dos units de hook pones una sola, la del framework que estés usando. Si la app no tiene GUI, por ejemplo un servicio de Windows o una utilidad de línea de comandos, no añadas ni la .VCL ni la .FMX: no hay message loop que enganchar y con ExeWatchSDKv1 a secas te basta.

2. Inicializa una sola vez, temprano (en el .dpr antes de Application.Run, o en el evento OnCreate del formulario principal):

Dos argumentos: el API key que copias de la consola y el id del customer al que pertenece esta instalación. Listo, la app está monitorizada.

Lo que te has llevado con esas dos líneas. A partir de este momento los crashes quedan registrados con su stack trace sin que escribas nada más, y las dos units se reparten el trabajo. ExeWatchSDKv1 engancha System.ExceptProc, donde acaban las excepciones no controladas del código normal. ExeWatchSDKv1.VCL (o .FMX) recoge en cambio las que se escapan dentro de un evento, un OnClick o un OnCreate: las intercepta el message loop del framework y las entrega a Application.OnException, y ahí termina el recorrido, a System.ExceptProc no llegan nunca. En una app de escritorio son la categoría de crash más frecuente, y por eso cuenta la segunda unit.

Arranca también un log automático Application started, la confirmación de que la integración está viva, y la información del dispositivo (sistema operativo, máquina, versión del binario) se envía y queda asociada al customer. Nada de esto viaja por el hilo de tu aplicación: los eventos van a una cola en disco y un hilo en segundo plano los envía, así que una red lenta o un servidor inalcanzable no ralentizan ni bloquean la app.

La unit de hook no te quita el handler que ya tenías: si ya habías puesto tu propio Application.OnException, el hook registra el log y luego lo llama; si no lo tenías, llama a Application.ShowException. La ventana de error que veía tu usuario sigue apareciendo igual. Y si el día de mañana te olvidas de ella en otro proyecto no te quedas a ciegas: el SDK detecta que corre en una app con GUI sin hook instalado y escribe él mismo un Warning con tag exewatch, que te encuentras en el dashboard.

3. Registra lo que te interesa. De aquí en adelante registras, cuentas y mides tiempos cada vez que tengas algo que merezca quedar guardado:

Abre el dashboard y los eventos están ahí. De aquí en adelante la guía sirve para que se te ocurra todo lo que merece acabar dentro, porque la lista es más larga que la que se te ocurriría ahora mismo.

El Quickstart era Delphi, el SDK insignia. El qué y el por qué del resto de la guía valen idénticos para cada SDK: solo cambia cómo integrarlo e inicializarlo. Aquí tienes la configuración de cada uno. En todos ellos el último argumento es la etiqueta de release (AppVersion), y el API key lleva el prefijo de la plataforma (ew_win_, ew_lin_, ew_web_, y así sucesivamente).

Delphi (nativo). Como en el Quickstart: ExeWatchSDKv1 en la cláusula uses, más ExeWatchSDKv1.VCL (o .FMX) si la app tiene GUI, y luego InitializeExeWatch(ApiKey, CustomerId, '4.2.0'). La unit VCL/FMX captura por ti las excepciones de GUI no controladas.

.NET. Referencia el paquete ExeWatch (añade ExeWatch.WinForms para una app WinForms), y luego inicializa una vez al arrancar:

Una app de consola o de servicio se salta la línea Install: el cliente engancha AppDomain.UnhandledException por su cuenta. WinForms necesita en cambio la llamada Install explícita antes de Application.Run.

Python. Instala el SDK, inicializa el singleton y usa el objeto ew a nivel de módulo a partir de entonces:

Python no tiene GUI que enganchar, así que captura los fallos donde los manejes con ew.error_with_exception(exc, "tag"), o apunta sys.excepthook al SDK para tener una red global.

JavaScript (navegador). Declaras la configuración en window.ewConfig y luego cargas el script desde exewatch.com. El key es un key ew_web_, y el SDK captura automáticamente window.onerror:

El orden importa: el SDK se inicializa solo en el DOMContentLoaded leyendo window.ewConfig, así que la configuración tiene que estar ya en la página cuando se carga el script. El script lo sirves desde exewatch.com, no desde una copia tuya, así las correcciones llegan a tus usuarios sin que tengas que redistribuir nada.

Este SDK es solo para navegador, no hay build para Node. Los errores no capturados se recogen por ti, junto con los fallos de fetch y XHR y las console.error. En una página que carga scripts de terceros, ignoreUrls dentro de la misma ewConfig descarta los errores que llegan de dominios que no controlas, como publicidad y analítica: es ruido que no te dice nada sobre tu aplicación.

DLL (C, C++, VB, .NET antiguo, cualquier cosa con un C ABI). Carga ExeWatchSDKv1DLL.dll y llama a los exports planos. Las cadenas son wide (PWideChar), toda función es stdcall, y los resultados vuelven como códigos de retorno:

Como un C ABI plano no puede recorrer la pila del host ni ejecutar un callback, dos tareas recaen sobre el host: pasar una cadena de stack ya resuelta a ew_ErrorWithStackTrace, y accionar los gauges periódicos desde tu propio timer (no hay callback de gauge periódico). Un host Delphi que prefiera la DLL sobre las units nativas puede usar la import unit ExeWatchSDKv1Imports y llamar a EWInitialize(…​) en lugar de InitializeExeWatch.

Lo mismo, entero, con MSVC. Ninguna import library y ningún runtime de Embarcadero: define EW_DYNAMIC_LOAD antes del header y cada ew_* se convierte en un puntero a función, que ExeWatchSDKv1.dynload.c resuelve en tiempo de ejecución con LoadLibrary y GetProcAddress. Esto es un programa completo, no un fragmento:

Se compila en un solo comando, desde un prompt "x64 Native Tools Command Prompt for VS 2022", pasando la carpeta que contiene el header y el loader:

La única línea que aquí no es ceremonia es ew_WaitForSending. Una utilidad de línea de comandos puede terminar antes de que el hilo shipper haya vaciado la cola, y esa llamada escribe el buffer en disco y espera a que la cola se vacíe, devolviendo cuántos eventos siguen pendientes. No es un problema de pérdida de datos, porque la cola está en disco y arranca de nuevo en la siguiente ejecución, pero sin la espera tus eventos aparecen en el dashboard con una vuelta de retraso. El sample compilable con todo lo demás, identidad de usuario, tags globales, breadcrumbs, timings anidados y gauges, está en ExeWatchSamples/MSVCWithDLLSDK.

La misma DLL desde una consola Delphi. Un host Delphi también puede usar la DLL en lugar de las units nativas, y en dos casos es la elección correcta: cuando estás en un Delphi más antiguo que XE8, que es el mínimo del SDK nativo, y cuando tienes varias aplicaciones que actualizar distribuyendo un solo binario. La import unit ExeWatchSDKv1Imports llega hasta Delphi 5. Esto también es un programa entero:

Los wrappers con el prefijo EW aceptan string y la conversión a PWideChar la hacen ellos, así que en tu código no aparece ningún cast. Al tratarse de una consola, valen las mismas dos líneas de antes: ew_WaitForSending antes de salir, y ew_Shutdown para cerrar limpio.

Una cosa que conviene saber antes de distribuir. Por defecto la unit enlaza la DLL de forma estática, así que ExeWatchSDKv1DLL_x64.dll tiene que estar junto al ejecutable en el momento del arranque: si falta, el proceso no arranca en absoluto, lo bloquea Windows con un error de DLL ausente antes incluso de tu primera línea de código. Si prefieres que la aplicación arranque igualmente y renuncie solo a la telemetría, define EW_DYNAMIC_LOAD en las opciones de proyecto: la unit pasa a LoadLibrary, y llamas a EWLoadDLL al arrancar comprobando su resultado, como hace el ejemplo de MSVC de arriba.

Y con Free Pascal. La DLL no tiene nada específico de Delphi: es un C ABI plano, stdcall, cadenas wide. En Windows la misma ExeWatchSDKv1Imports compila con FPC, que la unit reconoce y pone en {$MODE DELPHI} por sí sola. Donde string no es Unicode el alias interno pasa a WideString y los wrappers EW* convierten por ti, así que el código que escribes sigue siendo el del ejemplo de arriba.

La llamada única a InitializeExeWatch del Quickstart es todo lo que la mayoría de las apps van a necesitar. Ese tercer argumento es AppVersion, tu etiqueta de release ('4.2.0', '2026-Q1', 'v2-beta'); la versión del binario es en cambio un campo separado, autodetectado del ejecutable, así que obtienes ambos con esa única línea. Aquí tienes a qué recurrir cuando esa línea no basta.

Es un flujo deliberado y soportado, no un apaño. Mientras el customer id está vacío el SDK retiene el registro de device-info, porque necesita el id para asociar el dispositivo al customer correcto, y lo envía en el momento en que llamas a SetCustomerId. Si el id cambia más tarde (un customer distinto en la misma máquina) el SDK reenvía la device info bajo el nuevo customer, para que el dispositivo aparezca correctamente en ambos. La regla es simple: inicializa primero, identifica en cuanto puedas.

El customer y el user son dos identidades distintas, que se establecen con dos llamadas distintas. SetCustomerId establece el customer: la cuenta o el tenant al que pertenece esta instalación, que es el criterio por el que el dashboard agrupa dispositivos y alertas. Quién está usando realmente la app es otra cosa, el user, y eso lo estableces con SetUser:

El id, el email y el nombre viajan luego con cada evento como user_id, así que un crash muestra qué customer se lo encontró y también qué persona. Usa SetCustomerId para la cuenta y SetUser para la persona: son independientes, y puedes establecer uno, otro, ambos o ninguno de los dos.

Cuando la llamada de tres argumentos no basta, construye un TExeWatchConfig y pásalo en su lugar. Cada campo tiene un valor por defecto sensato, así que configura solo lo que necesites:

Los ajustes que vale la pena conocer:

Los otros SDKs adoptan los mismos conceptos bajo nombres de campo muy parecidos; la referencia tiene la firma exacta para cada uno.

Un dashboard vacío impone, y la primera pregunta es siempre la misma: ¿por dónde empiezo? La respuesta corta es que si algo te interesa, hay que registrarlo. ¿Te interesa saber si esa función falla? Registra. ¿Cuántas veces se usa? Cuenta. ¿Si es lenta y cuánto? Mide. El error que se paga caro no es haber enviado algún evento de más, es encontrarte delante de un problema en producción y descubrir que justo ese trozo de código no cuenta nada.

Ese momento llega siempre, y llega un martes por la tarde con un cliente al teléfono. Tienes el stack trace del crash pero no sabes qué estaba haciendo el usuario un instante antes, porque ese paso no lo habías registrado. Sabes que la sincronización tarda una eternidad pero no qué fase se la come, porque solo habías medido el total. En esos veinte minutos nunca echas de menos las líneas que enviaste de más. Echas de menos las tres que no escribiste.

Así que empieza generoso. Si algo puede fallar, si puede volverse lento, si necesitas saber cuánto se usa, si explica por qué la app se comportó de cierta manera, mándalo. Añadirlo es fácil mientras estás escribiendo el código; añadirlo después, cuando la build en cuestión ya está instalada en trescientos clientes, significa una release y semanas de espera. Y el ruido, si el día de mañana hubiera demasiado, lo quitas cuando quieras: el nivel mínimo y el muestreo de cada aplicación se cambian desde la consola, sin recompilar nada.

Lo único que no merece la pena enviar es lo que no te dice nada ni a ti: un Debug('estoy aquí'), un Info('paso 1'), un mensaje sin contexto que solo entiendes mientras lo escribes. El resto de la guía sirve para que se te ocurra qué sí merece estar ahí, y para elegir la herramienta adecuada a cada cosa, ya que un crash, un recuento de uso y una duración se registran de tres maneras distintas.

Antes de las recetas, el mapa. ExeWatch te pone a disposición cinco herramientas, y cada una existe para responder una pregunta distinta. Casi toda decisión de "¿qué mido aquí?" se vuelve obvia una vez que sabes qué pregunta te estás haciendo.

Dos cosas son fáciles de pasar por alto, y ambas te ahorran trabajo real más adelante.

Los tags son la sexta herramienta silenciosa. Cada llamada de log, counter, gauge y timing acepta un tag, y existe un SetTag a nivel de proceso para el contexto que viaja junto a todo. Los tags son cómo recortas el dashboard en "payment" frente a "sync" frente a "ui" sin inventar una métrica separada para cada funcionalidad. Aciértalos y cada gráfico se puede filtrar exactamente como razonas tú; erra con ellos y el dashboard se convierte en ruido. La sección de higiene de tags viene a continuación, y es corta.

La device info es automática y gratis. Versión de la app, versión del binario, SO y hardware viajan con cada lote sin una sola llamada tuya. No los vuelvas a registrar. El único campo que pones a mano es AppVersion, la etiqueta de release, y eso es justo lo que hace posible comparar versiones más tarde.

Un tag sirve para filtrar, no para transportar datos. Mantenlos cortos, pocos y estables en el tiempo, y el dashboard sigue siendo legible incluso después de unos cuantos años de añadidos.

En la práctica:

Configura una sola vez, al arrancar, el contexto que nunca cambia, así no lo repites en cada llamada:

A partir de ahí cada evento lleva ese contexto, y puedes filtrar todo el dashboard hasta, por ejemplo, solo la edición Pro en el canal stable sin tocar otra línea de código.

Los tags que estableces con SetTag (o con GlobalTags en el init) se convierten en un filtro de Global Tags en la consola, así que puedes segmentar cada vista por entorno, edición, feature flag y lo que sea que hayas etiquetado.

Las recetas que siguen usan Delphi. Los conceptos son idénticos entre SDKs; solo cambia la forma de escribirlo. Esta tabla es el mapa, para que un lector de .NET o Python pueda traducir cualquier snippet de un vistazo. La referencia de la consola tiene las firmas completas.

Dos hechos específicos de cada SDK que vale la pena llevar a cada receta: la DLL no tiene callback de gauge periódico, así que la accionas desde tu propio timer, y JavaScript es solo para navegador. Todo lo demás es un renombrado uno a uno.

Cada receta parte de una situación en la que ya has estado, o estarás, y remonta hasta la única cosa que vale la pena instrumentar. Un snippet Delphi canónico por receta; usa la tabla de arriba para traducirlo a tu SDK. Donde el comportamiento cambia de verdad, se indica.

Estas tres herramientas se confunden constantemente, y confundirlas no lanza un error, registra en silencio datos que no significan nada, lo cual es peor. La distinción es simple una vez que la dices en voz alta:

En caso de duda, prueba a sumar dos lecturas. Si la suma tiene sentido, 12 exportaciones más 8 exportaciones son 20 exportaciones, es un counter. Si no tiene sentido, una cola de 12 más una cola de 8 no es una cola de 20, es un gauge. Si lo que te importa es el tiempo transcurrido, es un timing.

Una alerta es lo que te permite dejar de vigilar el dashboard. En vez de asomarte de vez en cuando con la esperanza de pillar un problema, describes el problema una vez y ExeWatch te envía un email cuando ocurre. Hoy existen dos tipos, y conviene saber con precisión sobre qué se dispara cada uno, porque los límites honestos del alerting condicionan cómo usas todo lo de arriba.

Las alertas de volumen de logs se disparan cuando el recuento de eventos de log iguales o superiores a un nivel cruza un umbral dentro de una ventana. Configuras threshold (un recuento), window_minutes, min_level (por defecto error), un filtro tags opcional, un customer_external_id opcional, y cooldown_minutes (por defecto 60) para que un solo incidente no te avise cincuenta veces. Una típica dice: "más de 20 eventos fatal en 15 minutos para el cliente Acme".

La misma alerta como formulario en la consola: un umbral sobre una ventana temporal a un nivel mínimo, con un cooldown, si hace falta estrechada por tag y por cliente. Acotar "Filter by Customer" a Acme es como consigues que te avisen de los errores de Acme sin enterarte de los de nadie más.

Tasa de error a lo largo del tiempo. Un pico como los de aquí es exactamente lo que vigila una alerta de volumen de logs, para que te llegue por email en el momento en que empieza en vez de cuando por casualidad abres este gráfico.

Las alertas de timing se disparan cuando operaciones que coinciden con un patrón de id de timing corren más lentas que un umbral de duración, con la frecuencia suficiente para cruzar un umbral de recuento dentro de una ventana. Los campos son un timing_id_pattern, un umbral de duración en milisegundos, un threshold de ocurrencias (por defecto 5), window_minutes, un customer_external_id opcional, y cooldown_minutes (por defecto 240). Así es como te enteras de que "report.render está corriendo lento en el campo" sin tener que vigilarlo.

La forma de mantener las alertas útiles en vez de ignoradas: mantén honestos tus niveles de log (ver anti-patrones, o tu umbral de error se dispara con cosas que no son errores), da a cada alerta un ámbito por tag o por cliente para que tenga un dueño claro, y pon un cooldown lo bastante largo para que un incidente real llegue como un solo email.

Sacas una versión y quieres saber si se volvió más lenta o más ruidosa que la anterior. Hoy esa comparación pasa por la exportación CSV, y vale la pena explicitar el flujo porque responde a una pregunta que los clientes plantean constantemente.

La misma exportación existe en las páginas de Logs y Métricas, así que puedes comparar volumen de errores o niveles de métrica entre versiones de la misma forma. Un filtro de timing por versión dentro de la interfaz está en el backlog; cuando llegue, esto pasa a ser un par de clics en vez de un pivote. Hasta entonces, la vía del CSV es la forma soportada de hacer comparación versión a versión, y funciona lo bastante bien como para que bastantes equipos se queden aquí.

Como cada evento lleva su AppVersion, la consola ya sabe cómo están repartidas tus releases en el campo. Esa misma etiqueta de versión es sobre la que creas la pivot del timing exportado.

Las llamadas sueltas son fáciles de aprobar con un gesto y difíciles de ubicar. Así que aquí tienes instrumentación metida en código ordinario: un método de sync en un data module, del tipo que tiene toda app Delphi de gestión. Primero la versión desnuda, que hace su trabajo sin telemetría:

Ahora el mismo método instrumentado, cada añadido haciendo exactamente un trabajo:

Qué fue dónde, y por qué:

Fíjate en la forma: la instrumentación enmarca el código real, no lo reemplaza. Borra cada línea EW. y el método sigue funcionando exactamente igual que antes. La instrumentación se limita a observar.

Ninguno de estos es "has registrado demasiado". Son los casos en los que lo que envías te despista en lugar de ayudarte, y la corrección está junto a cada uno.

Repetir la misma línea dentro de un bucle. Una llamada Debug en un bucle caliente, o un IncrementCounter en cada iteración. El asunto no es la cantidad: es que quinientas líneas idénticas responden todas a la misma pregunta que ya había respondido la primera, y mientras tanto consumen la quota que hacía falta para los eventos de verdad. Registra la operación, no sus iteraciones: una línea cuando arranca, otra cuando termina o falla, y un solo incremento de counter por operación lógica. Si el detalle por iteración te hace falta de verdad durante un diagnóstico, mantenlo a nivel Debug y sube el nivel mínimo de la aplicación desde la consola cuando hayas acabado.

Datos personales en los logs. Emails, nombres, tokens o contenidos de fichero en un mensaje o un tag. Los logs se conservan y se exportan a CSV, y los tags son dimensiones de baja cardinalidad, no cargas útiles, así que esto es a la vez un problema de privacidad y un lío. Registra ids y categorías; usa el campo de customer id para la identidad.

Niveles que mienten. Todo registrado como Error, o fallos genuinos registrados como Info. Las alertas usan por defecto min_level = error, así que si tus niveles están mal tus alertas están mal con ellos, y o te avisan por nada o nunca te avisan. La escala que los mantiene honestos: Fatal significa que la app no puede continuar, Error que una operación falló, Warning degradado pero funcionando, Info un cambio de estado notable, Debug detalle solo para desarrolladores.

Gauge y counter, intercambiados. Un counter para "profundidad de cola actual" suma niveles en un total sin sentido; un gauge para "número de exportaciones" tira el total a la basura. Aplica la prueba de la suma de la tabla de arriba antes de elegir.

Tags que explotan. Un id, un timestamp, o cualquier valor por petición en un tag. Los tags son dimensiones con un conjunto pequeño y fijo de valores; los valores no acotados se multiplican en miles de dimensiones de un solo uso y dejan el dashboard inservible. Mantén el vocabulario pequeño.

Volver a registrar lo que ya tienes gratis. Registrar a mano SO, versión o hardware que ya viajan en el snapshot de dispositivo con cada lote. No lo hagas. El único campo que pones a mano es AppVersion, la etiqueta de release.

Las apps de escritorio corren en portátiles que se meten en túneles, en máquinas detrás de VPNs caprichosas, en un PC que alguien desenchufa de la red a la hora de cerrar. Así que la pregunta es legítima: ¿qué le pasa a tu telemetría cuando el SDK no puede alcanzar el servidor?

No se pierde nada. El SDK no envía los eventos directamente desde el punto en el que los llamas. Los acumula en un buffer, los escribe a disco, y de enviarlos se encarga un hilo shipper en segundo plano. Cuando la red está caída el envío simplemente falla, los ficheros se quedan en disco, y el shipper reintenta a intervalos. En el momento en que vuelve la conectividad, los ficheros en cola se envían en orden. Un crash registrado en un avión aparece en tu dashboard la primera vez que el portátil vuelve a estar online.

Lo gobiernan cuatro ajustes de TExeWatchConfig:

El atraso puedes vigilarlo tú mismo: GetPendingCount devuelve cuántos eventos siguen esperando a enviarse.

Un hecho técnico que conviene conocer, y llega al final de la guía a propósito: la quota mensual es un recuento vivo de las filas que envías en el mes. Cuentan juntos los logs y las actualizaciones de métricas, es decir counters, gauges y timings, no solo los logs. Los mensajes internos del SDK, los que llevan tag ew.system, no entran en el recuento.

No es una invitación a instrumentar menos. El orden correcto es el que has seguido hasta aquí: primero decides qué quieres ver, y luego, si el volumen llega a ser un tema, lo gobiernas. Las herramientas para gobernarlo existen y nadie te pide renunciar a un dato que te interesa.

Si estás de forma estable cerca del techo con una instrumentación que necesitas entera, no hay nada que recortar: estás siguiendo más aplicaciones o más clientes que cuando elegiste el plan, y llegado ese punto conviene pasar al siguiente nivel.

Algunas cosas que la gente pide están planeadas pero todavía no lanzadas. Se listan aquí, con honestidad, para que sepas dónde están hoy los bordes y no vayas buscando una funcionalidad que todavía no está.

Para todo lo que hoy existe, la referencia del SDK en la consola tiene las firmas exactas, las claves de configuración y los pasos de instalación. Esta guía es el qué y el porqué; esa es el cómo.