Der ExeWatch DevGuide

Eine uses-Klausel und eine Zeile Initialisierung. Der ganze Rest des Leitfadens ist Feinschliff an diesen beiden Dingen.

1. Füge das SDK deiner uses-Klausel hinzu. In einer VCL-Anwendung, also der großen Mehrheit der Delphi-Apps, sind es zwei Units: Die zweite fängt die Exceptions der GUI ab.

Von den beiden Hook-Units nimmst du genau eine, die des Frameworks, das du verwendest. Hat die App keine GUI, etwa ein Windows-Dienst oder ein Kommandozeilenwerkzeug, dann füge weder .VCL noch .FMX hinzu: Es gibt keine Message Loop zum Einhängen, und ExeWatchSDKv1 allein reicht dir.

2. Initialisiere einmal, früh (im .dpr vor Application.Run oder im OnCreate-Ereignis des Hauptformulars):

Zwei Argumente: der API-Key, den du aus der Konsole kopierst, und die ID des Kunden, zu dem diese Installation gehört. Fertig, die App wird überwacht.

Was dir diese zwei Zeilen gebracht haben. Ab jetzt werden Abstürze mit ihrem Stack Trace erfasst, ohne dass du weiteres schreibst, und die beiden Units teilen sich die Arbeit. ExeWatchSDKv1 hängt sich in System.ExceptProc ein, wo die unbehandelten Exceptions des normalen Codes landen. ExeWatchSDKv1.VCL (oder .FMX) nimmt dagegen die, die innerhalb eines Ereignisses entwischen, eines OnClick oder eines OnCreate: Die fängt die Message Loop des Frameworks ab und übergibt sie an Application.OnException, und dort endet der Weg, bei System.ExceptProc kommen sie nie an. In einer Desktop-Anwendung sind sie die häufigste Absturzkategorie, und deshalb zählt die zweite Unit.

Außerdem geht ein automatischer Log Application started raus, die Bestätigung, dass die Integration lebt, und die Geräteinformationen (Betriebssystem, Maschine, Version des Binaries) werden gesendet und dem Kunden zugeordnet. Nichts davon läuft auf dem Thread deiner Anwendung: Die Events landen in einer Warteschlange auf der Platte, und ein Hintergrund-Thread verschickt sie, ein langsames Netz oder ein nicht erreichbarer Server bremst oder blockiert die App also nicht.

Die Hook-Unit nimmt dir deinen bisherigen Handler nicht weg: Hattest du bereits ein eigenes Application.OnException, loggt der Hook und ruft es danach auf; hattest du keines, ruft er Application.ShowException. Das Fehlerfenster, das dein Benutzer vorher sah, erscheint unverändert weiter. Und wenn du sie irgendwann in einem anderen Projekt vergisst, stehst du nicht im Dunkeln: Das SDK merkt, dass es in einer GUI-Anwendung ohne installierten Hook läuft, und schreibt selbst ein Warning mit Tag exewatch, das du im Dashboard wiederfindest.

3. Logge, was dich interessiert. Ab hier loggst, zählst und misst du die Zeit, wann immer du etwas Aufzeichnenswertes hast:

Öffne das Dashboard und die Events sind da. Von hier an hilft dir der Leitfaden dabei, auf alles zu kommen, was dort hineingehört, denn die Liste ist länger als die, die dir jetzt spontan einfallen würde.

Der Schnellstart war Delphi, das Flaggschiff-SDK. Das Was und Warum im Rest des Leitfadens gilt für jedes SDK gleich: Nur das Einbinden und Initialisieren unterscheidet sich. Hier ist die Einrichtung für jedes. In allen ist das letzte Argument das Release-Label (AppVersion), und der API-Key trägt das Präfix der Plattform (ew_win_, ew_lin_, ew_web_ und so weiter).

Delphi (nativ). Wie im Schnellstart: ExeWatchSDKv1 in der uses-Klausel, dazu ExeWatchSDKv1.VCL (oder .FMX), wenn die App eine GUI hat, dann InitializeExeWatch(ApiKey, CustomerId, '4.2.0'). Die VCL/FMX-Unit erfasst unbehandelte GUI-Exceptions für dich.

.NET. Referenziere das ExeWatch-Paket (füge ExeWatch.WinForms für eine WinForms-Anwendung hinzu), dann initialisiere einmal beim Start:

Eine Konsolen- oder Service-Anwendung lässt die Install-Zeile weg: Der Client hängt sich selbst an AppDomain.UnhandledException. WinForms braucht dagegen den expliziten Install-Aufruf vor Application.Run.

Python. Installiere das SDK, initialisiere das Singleton und nutze danach das modulweite ew:

Python hat keine GUI zum Einhängen, also erfasse Fehler dort, wo du sie behandelst, mit ew.error_with_exception(exc, "tag"), oder richte sys.excepthook auf das SDK aus, um ein globales Netz zu spannen.

JavaScript (Browser). Du deklarierst die Konfiguration in window.ewConfig und lädst dann das Skript von exewatch.com. Der Key ist ein ew_web_-Key, und das SDK erfasst window.onerror automatisch:

Die Reihenfolge zählt: Das SDK initialisiert sich beim DOMContentLoaded selbst und liest dabei window.ewConfig, die Konfiguration muss also schon auf der Seite stehen, wenn das Skript geladen wird. Das Skript lieferst du von exewatch.com aus, nicht aus einer eigenen Kopie, so erreichen Korrekturen deine Benutzer, ohne dass du etwas neu verteilen musst.

Dieses SDK ist nur für den Browser, einen Node-Build gibt es nicht. Nicht abgefangene Fehler werden für dich erfasst, zusammen mit fehlgeschlagenen fetch- und XHR-Aufrufen und den console.error-Ausgaben. Auf einer Seite, die Skripte von Dritten lädt, verwirft ignoreUrls in derselben ewConfig die Fehler aus Domains, die du nicht kontrollierst, etwa Werbung und Analytics: Das ist Rauschen, das dir nichts über deine Anwendung sagt.

DLL (C, C++, VB, altes .NET, alles mit einem C-ABI). Lade ExeWatchSDKv1DLL.dll und rufe die flachen Exports auf. Strings sind Wide (PWideChar), jede Funktion ist stdcall, und Ergebnisse kommen als Rückgabecodes zurück:

Weil ein flaches C-ABI weder den Stack des Hosts durchlaufen noch einen Callback ausführen kann, fallen dem Host zwei Aufgaben zu: einen bereits aufgelösten Stack-String an ew_ErrorWithStackTrace übergeben und periodische Gauges über deinen eigenen Timer ansteuern (es gibt keinen Callback für periodische Gauges). Ein Delphi-Host, der die DLL den nativen Units vorzieht, kann die Import-Unit ExeWatchSDKv1Imports verwenden und EWInitialize(…​) statt InitializeExeWatch aufrufen.

Dasselbe, vollständig, mit MSVC. Keine Import-Library und kein Embarcadero-Runtime: Definiere EW_DYNAMIC_LOAD vor dem Header, und jedes ew_* wird zu einem Funktionszeiger, den ExeWatchSDKv1.dynload.c zur Laufzeit mit LoadLibrary und GetProcAddress auflöst. Das hier ist ein vollständiges Programm, kein Ausschnitt:

Kompiliert wird mit einem einzigen Befehl, aus einer "x64 Native Tools Command Prompt for VS 2022", unter Angabe des Ordners mit Header und Loader:

Die einzige Zeile, die hier keine Zeremonie ist, ist ew_WaitForSending. Ein Kommandozeilenwerkzeug kann enden, bevor der Shipper-Thread die Queue geleert hat, und dieser Aufruf schreibt den Puffer auf die Platte und wartet, bis die Queue leer ist, wobei er zurückgibt, wie viele Events noch warten. Ein Datenverlust ist das nicht, denn die Queue liegt auf der Platte und läuft beim nächsten Lauf weiter, aber ohne das Warten erscheinen deine Events erst eine Runde später im Dashboard. Das kompilierbare Sample mit allem Übrigen, Benutzeridentität, globale Tags, Breadcrumbs, verschachtelte Timings und Gauges, liegt in ExeWatchSamples/MSVCWithDLLSDK.

Dieselbe DLL aus einer Delphi-Konsole. Auch ein Delphi-Host kann statt der nativen Units die DLL verwenden, und in zwei Fällen ist das die richtige Wahl: wenn du auf einem Delphi älter als XE8 arbeitest, dem Minimum des nativen SDK, und wenn du mehrere Anwendungen aktualisieren musst, indem du ein einziges Binary verteilst. Die Import-Unit ExeWatchSDKv1Imports reicht zurück bis Delphi 5. Auch das hier ist ein ganzes Programm:

Die Wrapper mit dem Präfix EW nehmen string entgegen und erledigen die Umwandlung nach PWideChar selbst, in deinem Code steht also kein Cast. Weil es eine Konsole ist, gelten dieselben zwei Zeilen wie vorhin: ew_WaitForSending vor dem Beenden und ew_Shutdown zum sauberen Schließen.

Eine Sache solltest du vor dem Ausliefern wissen. Standardmäßig bindet die Unit die DLL statisch, ExeWatchSDKv1DLL_x64.dll muss beim Start also neben der ausführbaren Datei liegen: Fehlt sie, startet der Prozess überhaupt nicht, Windows bricht mit einem Fehler wegen fehlender DLL ab, noch vor deiner ersten Codezeile. Soll die Anwendung stattdessen trotzdem starten und nur auf die Telemetrie verzichten, definiere EW_DYNAMIC_LOAD in den Projektoptionen: Die Unit wechselt zu LoadLibrary, und du rufst beim Start EWLoadDLL auf und prüfst dessen Ergebnis, so wie es das MSVC-Beispiel weiter oben macht.

Und mit Free Pascal. Die DLL hat nichts Delphi-Spezifisches: ein flaches C-ABI, stdcall, Wide Strings. Unter Windows kompiliert dieselbe ExeWatchSDKv1Imports mit FPC, den die Unit erkennt und selbst in {$MODE DELPHI} versetzt. Wo string nicht Unicode ist, wird der interne Alias zu WideString, und die EW*-Wrapper konvertieren für dich, der Code, den du schreibst, bleibt also der aus dem Beispiel oben.

Der einzelne InitializeExeWatch-Aufruf aus dem Schnellstart ist alles, was die meisten Anwendungen je brauchen. Das dritte Argument ist AppVersion, dein eigenes Release-Label ('4.2.0', '2026-Q1', 'v2-beta'); die Binärversion ist ein separates, automatisch aus der ausführbaren Datei erkanntes Feld, du bekommst also beides aus der einen Zeile. Hier ist, wonach du greifst, wenn diese Zeile nicht ausreicht.

Das ist ein bewusster, unterstützter Ablauf, kein Workaround. Solange die Customer-ID leer ist, hält das SDK den Device-Info-Datensatz zurück, weil es die ID braucht, um das Gerät dem richtigen Kunden zuzuordnen, und sendet ihn in dem Moment, in dem du SetCustomerId aufrufst. Wenn sich die ID später ändert (ein anderer Kunde auf derselben Maschine), sendet das SDK die Device-Info erneut unter dem neuen Kunden, sodass das Gerät für beide korrekt auftaucht. Die Regel ist einfach: erst initialisieren, dann identifizieren, sobald du kannst.

Kunde und Benutzer sind zwei verschiedene Identitäten, gesetzt mit zwei verschiedenen Aufrufen. SetCustomerId setzt den Kunden: das Konto oder den Mandanten, zu dem diese Installation gehört, also das Kriterium, nach dem das Dashboard Geräte und Alerts gruppiert. Wer die Anwendung tatsächlich benutzt, ist eine andere Sache, der Benutzer, und den setzt du mit SetUser:

ID, E-Mail und Name reisen dann mit jedem Event als user_id mit, sodass ein Absturz zeigt, welcher Kunde ihn getroffen hat und welche Person. Verwende SetCustomerId für das Konto und SetUser für den Menschen: Sie sind unabhängig, und du kannst das eine, das andere, beide oder keines setzen.

Wenn der Drei-Argument-Aufruf nicht ausreicht, baue eine TExeWatchConfig und übergib die stattdessen. Jedes Feld hat einen sinnvollen Standardwert, setze also nur, was du brauchst:

Die Einstellungen, die man kennen sollte:

Die anderen SDKs übernehmen dieselben Konzepte unter sehr ähnlichen Feldnamen; die Referenz hat die genaue Signatur für jedes.

Ein leeres Dashboard ist einschüchternd, und die erste Frage ist immer dieselbe: Wo fange ich an? Die kurze Antwort: Wenn dich etwas interessiert, gehört es aufgezeichnet. Willst du wissen, ob diese Funktion fehlschlägt? Logge. Wie oft sie benutzt wird? Zähle. Ob sie langsam ist und wie sehr? Miss die Zeit. Der teure Fehler ist nicht, ein paar Events zu viel geschickt zu haben. Der teure Fehler ist, vor einem Problem in Produktion zu stehen und festzustellen, dass ausgerechnet dieses Stück Code nichts erzählt.

Dieser Moment kommt immer, und er kommt an einem Dienstagnachmittag mit einem Kunden am Telefon. Du hast den Stack Trace des Absturzes, aber du weißt nicht, was der Benutzer einen Augenblick vorher getan hat, weil du diesen Schritt nicht geloggt hattest. Du weißt, dass die Synchronisation ewig dauert, aber nicht, welche Phase sie frisst, weil du nur das Gesamt gemessen hattest. In diesen zwanzig Minuten bereust du nie die Zeilen, die du zu viel geschickt hast. Du bereust die drei, die du nicht geschrieben hast.

Fang also großzügig an. Wenn etwas fehlschlagen kann, wenn es langsam werden kann, wenn du wissen musst, wie oft es benutzt wird, wenn es erklärt, warum die App sich so verhalten hat, dann schick es. Solange du den Code schreibst, ist Hinzufügen leicht; später hinzufügen, wenn der fragliche Build schon bei dreihundert Kunden installiert ist, heißt ein Release und Wochen Wartezeit. Und das Rauschen, falls es irgendwann zu viel wird, nimmst du jederzeit weg: Mindest-Level und Sampling jeder Anwendung änderst du in der Konsole, ohne etwas neu zu kompilieren.

Nicht zu schicken lohnt sich nur, was nicht einmal dir etwas sagt: ein Debug('bin hier'), ein Info('step 1'), eine Nachricht ohne Kontext, die du nur in dem Moment verstehst, in dem du sie schreibst. Der Rest des Leitfadens hilft dir, darauf zu kommen, was stattdessen hineingehört, und für jede Sache das passende Werkzeug zu wählen, denn ein Absturz, eine Nutzungszählung und eine Dauer werden auf drei verschiedene Arten erfasst.

Vor den Rezepten die Landkarte. ExeWatch gibt dir fünf Werkzeuge, und jedes existiert, um eine andere Frage zu beantworten. Fast jede Entscheidung der Art "Was erfasse ich hier?" wird offensichtlich, sobald du weißt, welche Frage du stellst.

Zwei Dinge übersieht man leicht, und beide sparen dir später echte Arbeit.

Tags sind das stille sechste Werkzeug. Jeder Log-, Counter-, Gauge- und Timing-Aufruf nimmt einen tag, und es gibt ein prozessweites SetTag für Kontext, der mit allem mitläuft. Tags sind, wie du das Dashboard in "payment" gegen "sync" gegen "ui" zerschneidest, ohne für jedes Feature eine eigene Metrik zu erfinden. Mach sie richtig und jedes Diagramm lässt sich so filtern, wie du denkst; mach sie falsch und das Dashboard verkommt zu Rauschen. Der Abschnitt zur Tag-Hygiene kommt als Nächstes, und er ist kurz.

Device-Info ist automatisch und kostenlos. App-Version, Binärversion, Betriebssystem und Hardware werden mit jedem Batch mitgeschickt, ohne einen einzigen Aufruf von dir. Logge sie nicht erneut. Das eine Feld, das du von Hand setzt, ist AppVersion, das Release-Label, und genau das macht später Versionsvergleiche möglich.

Ein Tag dient zum Filtern, nicht zum Transportieren von Daten. Halte sie kurz, wenige und über die Zeit stabil, dann bleibt das Dashboard auch nach ein paar Jahren voller Ergänzungen lesbar.

In der Praxis:

Setze den Kontext, der sich nie ändert, einmal beim Start, damit du ihn nicht bei jedem Aufruf wiederholst:

Von da an trägt jedes Event diesen Kontext, und du kannst das ganze Dashboard filtern auf, sagen wir, die Pro-Edition auf dem Stable-Channel, ohne eine weitere Codezeile anzurühren.

Tags, die du mit SetTag (oder GlobalTags bei der Initialisierung) setzt, werden in der Konsole zu einem Global-Tags-Filter, sodass du jede Ansicht nach Umgebung, Edition, Feature-Flag und allem anderen, was du getaggt hast, aufschlüsseln kannst.

Die folgenden Rezepte nutzen Delphi. Die Konzepte sind über alle SDKs hinweg identisch; nur die Schreibweise ändert sich. Diese Tabelle ist die Landkarte, sodass ein .NET- oder Python-Leser jeden Ausschnitt auf einen Blick übersetzen kann. Die Konsolen-Referenz hat die vollständigen Signaturen.

Zwei SDK-spezifische Fakten, die man in jedes Rezept mitnehmen sollte: Die DLL hat keinen Callback für periodische Gauges, also steuerst du sie über deinen eigenen Timer an, und JavaScript läuft nur im Browser. Alles andere ist ein Eins-zu-eins-Umschreiben.

Jedes Rezept startet aus einer Situation, in der du warst oder noch sein wirst, und arbeitet zurück zu der einen Sache, die es zu instrumentieren lohnt. Jeweils ein kanonischer Delphi-Ausschnitt; nutze die Tabelle oben, um ihn in dein SDK zu übersetzen. Wo sich das Verhalten wirklich unterscheidet, ist es vermerkt.

Diese drei Werkzeuge werden ständig verwechselt, und sie zu verwechseln wirft keinen Fehler, es zeichnet still Daten auf, die nichts bedeuten, was schlimmer ist. Der Unterschied ist einfach, sobald man ihn ausspricht:

Im Zweifel addiere zwei Messwerte. Wenn die Summe Sinn ergibt, 12 Exporte plus 8 Exporte sind wirklich 20 Exporte, ist es ein Counter. Wenn sie keinen Sinn ergibt, eine Queue von 12 plus eine Queue von 8 ist keine Queue von 20, ist es ein Gauge. Wenn dich die verstrichene Zeit interessiert, ist es ein Timing.

Ein Alert ist das, was dir erlaubt, das Dashboard nicht mehr beobachten zu müssen. Statt reinzuschauen und zu hoffen, ein Problem zu erwischen, beschreibst du das Problem einmal und ExeWatch mailt dir, wenn es passiert. Zwei Arten gibt es heute, und es lohnt sich, genau zu wissen, worauf jede feuert, denn die ehrlichen Grenzen des Alertings prägen, wie du alles oben nutzt.

Log-Volumen-Alerts feuern, wenn die Anzahl der Log-Events auf oder über einem Level einen Schwellwert innerhalb eines Fensters überschreitet. Du setzt threshold (eine Anzahl), window_minutes, min_level (Standard error), einen optionalen tags-Filter, eine optionale customer_external_id und cooldown_minutes (Standard 60), damit ein Vorfall dich nicht fünfzigmal benachrichtigt. Ein typischer lautet: "mehr als 20 fatal-Events in 15 Minuten für Kunde Acme."

Derselbe Alert als Formular in der Konsole: ein Schwellwert über ein Zeitfenster auf einem Mindest-Level, mit einem Cooldown, optional eingegrenzt nach Tag und nach Kunde. "Filter by Customer" auf Acme zu scopen ist der Weg, um über Acmes Fehler benachrichtigt zu werden, ohne von irgendjemand anderem zu hören.

Fehlerrate über die Zeit. Ein Ausschlag wie die hier ist genau das, worauf ein Log-Volumen-Alert achtet, sodass er dich per E-Mail erreicht, sobald er beginnt, statt wenn du zufällig dieses Diagramm öffnest.

Timing-Alerts feuern, wenn Operationen, die auf ein Timing-ID-Muster passen, langsamer als ein Dauer-Schwellwert laufen, oft genug, um einen Anzahl-Schwellwert innerhalb eines Fensters zu überschreiten. Die Felder sind ein timing_id_pattern, ein Dauer-Schwellwert in Millisekunden, ein Vorkommen-threshold (Standard 5), window_minutes, eine optionale customer_external_id und cooldown_minutes (Standard 240). So wirst du darüber informiert, dass "report.render im Feld langsam läuft", ohne danach zu schauen.

Der Weg, Alerts nützlich statt ignoriert zu halten: Halte deine Log-Level ehrlich (siehe Anti-Patterns, sonst feuert deine error-Schwelle auf Dinge, die keine Fehler sind), scope jeden Alert nach Tag oder Kunde, sodass er einen klaren Besitzer hat, und setze ein Cooldown, lang genug, dass ein echter Vorfall als eine E-Mail ankommt.

Du lieferst ein Release aus und willst wissen, ob es langsamer oder lauter wurde als das letzte. Heute läuft dieser Vergleich über CSV-Export, und der Ablauf ist es wert, ausbuchstabiert zu werden, weil er eine Frage beantwortet, die Kunden ständig stellen.

Derselbe Export existiert auf den Logs- und Metrics-Seiten, sodass du Fehlervolumen oder Metrik-Pegel über Versionen auf dieselbe Weise vergleichen kannst. Ein In-UI-Timing-Filter pro Version ist im Backlog; wenn er landet, wird daraus ein paar Klicks statt eines Pivots. Bis dahin ist der CSV-Weg der unterstützte Weg, um Version-über-Version-Vergleiche zu machen, und er funktioniert gut genug, dass etliche Teams hier aufhören.

Weil jedes Event seine AppVersion trägt, weiß die Konsole bereits, wie deine Releases übers Feld verteilt sind. Genau dieses Versions-Label ist das, wonach du das exportierte Timing pivotierst.

Isolierte Aufrufe sind leicht abzunicken und schwer einzuordnen. Also hier ist Instrumentierung, hineingelassen in gewöhnlichen Code: eine Sync-Methode auf einem Data Module, die Art, die jede Line-of-Business-Delphi-App hat. Zuerst die schlichte Version, die ihre Arbeit ohne Telemetrie tut:

Nun dieselbe Methode instrumentiert, jede Ergänzung tut genau eine Aufgabe:

Was wohin ging, und warum:

Beachte die Form: Instrumentierung rahmt den echten Code, sie ersetzt ihn nicht. Lösche jede EW.-Zeile und die Methode funktioniert genau wie zuvor. Die Instrumentierung beobachtet nur.

Keines davon heißt "du hast zu viel geloggt". Es sind die Fälle, in denen das, was du schickst, dich in die Irre führt statt dir zu helfen, und der Fix steht neben jedem.

Dieselbe Zeile in einer Schleife wiederholen. Ein Debug-Aufruf in einer heißen Schleife oder ein IncrementCounter bei jeder Iteration. Es geht nicht um die Menge: Fünfhundert identische Zeilen beantworten alle dieselbe Frage, die schon die erste beantwortet hatte, und verbrauchen dabei die Quota, die die echten Events gebraucht hätten. Zeichne die Operation auf, nicht ihre Iterationen: eine Zeile beim Start, eine beim Ende oder beim Fehlschlag, und ein Counter-Inkrement pro logischer Operation. Wenn du das Detail pro Iteration während einer Diagnose wirklich brauchst, halte es auf Level Debug und hebe das Mindest-Level der Anwendung in der Konsole wieder an, wenn du fertig bist.

Personenbezogene Daten in Logs. E-Mails, Namen, Tokens oder Dateiinhalte in einer Nachricht oder einem Tag. Logs werden aufbewahrt und nach CSV exportiert, und Tags sind niedrig-kardinale Dimensionen, keine Nutzlasten, also ist das sowohl ein Datenschutzproblem als auch ein Durcheinander. Logge IDs und Kategorien; nutze das Customer-ID-Feld für Identität.

Level, die lügen. Alles auf Error geloggt, oder echte Fehlschläge auf Info geloggt. Alerts haben standardmäßig min_level = error, sodass, wenn deine Level falsch sind, deine Alerts mit ihnen falsch sind, und du entweder für nichts benachrichtigt wirst oder nie. Die Skala, die sie ehrlich hält: Fatal heißt, die App kann nicht fortfahren, Error heißt, eine Operation schlug fehl, Warning heißt degradiert, aber funktionierend, Info heißt eine bemerkenswerte Zustandsänderung, Debug heißt nur-Entwickler-Detail.

Gauge und Counter, vertauscht. Ein Counter für "aktuelle Queue-Tiefe" summiert Pegel zu einem bedeutungslosen Gesamt; ein Gauge für "Anzahl der Exporte" wirft das Gesamt weg. Wende den Additionstest aus der Tabelle oben an, bevor du wählst.

Tags, die explodieren. Eine ID, ein Zeitstempel oder irgendein Wert pro Request in einem Tag. Tags sind Dimensionen mit einer kleinen festen Menge von Werten; unbegrenzte Werte vervielfachen sich zu Tausenden einmaliger Dimensionen und machen das Dashboard unbrauchbar. Halte das Vokabular klein.

Erneut loggen, was du schon kostenlos bekommst. Manuell Betriebssystem, Version oder Hardware loggen, die bereits im Device-Snapshot mit jedem Batch mitgeliefert werden. Tu es nicht. Das einzige Feld, das du von Hand setzt, ist AppVersion, das Release-Label.

Desktop-Anwendungen laufen auf Laptops, die in Tunnel fahren, auf Maschinen hinter wackeligen VPNs, auf einem PC, den jemand zum Feierabend vom Netz trennt. Also ist das eine berechtigte Frage: Was passiert mit deiner Telemetrie, wenn das SDK den Server nicht erreichen kann?

Nichts geht verloren. Das SDK sendet Events nicht direkt von der Aufrufstelle. Es puffert sie, schreibt sie auf die Platte, und ein Hintergrund-Shipper-Thread erledigt das Senden. Wenn das Netz weg ist, schlägt das Senden einfach fehl, die Dateien bleiben auf der Platte, und der Shipper versucht es in einem Intervall erneut. In dem Moment, in dem die Verbindung zurückkommt, werden die aufgestauten Dateien der Reihe nach verschickt. Ein im Flugzeug geloggter Absturz landet auf deinem Dashboard, sobald der Laptop das nächste Mal online geht.

Vier Einstellungen an TExeWatchConfig prägen das:

Du kannst den Rückstau selbst beobachten: GetPendingCount gibt zurück, wie viele Events noch auf den Versand warten.

Eine technische Tatsache, die man kennen sollte, und sie steht mit Absicht am Ende des Leitfadens: Die monatliche Quota ist eine Live-Zählung der Zeilen, die du im Monat sendest. Es zählen Logs und Metrik-Updates zusammen, also Counter, Gauges und Timings, nicht nur die Logs. Die internen Meldungen des SDK, die mit Tag ew.system, fallen nicht in die Zählung.

Das ist keine Aufforderung, weniger zu instrumentieren. Die richtige Reihenfolge ist die, der du bis hierher gefolgt bist: Zuerst entscheidest du, was du sehen willst, dann steuerst du das Volumen, falls und sobald es ein Thema wird. Die Mittel dafür gibt es, und niemand verlangt von dir, auf Daten zu verzichten, die dich interessieren.

Wenn du dauerhaft nahe an der Grenze läufst und deine Instrumentierung komplett brauchst, gibt es nichts zu kürzen: Du beobachtest mehr Anwendungen oder mehr Kunden als damals, als du den Plan gewählt hast, und dann lohnt sich die nächste Stufe.

Ein paar Dinge, nach denen Leute fragen, sind geplant, aber nicht ausgeliefert. Sie sind hier ehrlich aufgelistet, damit du weißt, wo heute die Grenzen liegen, und nicht nach einem Feature suchst, das es noch nicht gibt.

Für alles, was es heute gibt, hat die SDK-Referenz in der Konsole die genauen Signaturen, Config-Keys und Installationsschritte. Dieser Leitfaden ist das Was und das Warum; jene ist das Wie.