The ExeWatch DevGuide

One uses clause and one initialization line. Everything else in this guide refines those two things.

1. Add the SDK to your uses clause. In a VCL app, which is the vast majority of Delphi apps, that is two units. The second one is what captures GUI exceptions.

You add only one of the two hook units, the one for the framework you are using. If the app has no GUI, a Windows service or a command line utility for example, add neither .VCL nor .FMX. There is no message loop to hook and ExeWatchSDKv1 on its own is enough.

2. Initialize once, early (in the .dpr before Application.Run, or in the OnCreate event of the main form):

Two arguments: the API key you copy from the console, and the id of the customer this installation belongs to. Done, the app is monitored.

What those two lines bought you. From now on crashes are recorded with their stack trace without you writing anything else, and the two units split the work. ExeWatchSDKv1 hooks System.ExceptProc, where unhandled exceptions from ordinary code end up. ExeWatchSDKv1.VCL (or .FMX) takes the ones that escape inside an event, an OnClick or an OnCreate: the framework message loop intercepts them and hands them to Application.OnException, and that is where the trip ends. They never reach System.ExceptProc. In a desktop app they are the most frequent category of crash, and that is why the second unit matters.

An automatic Application started log goes out too, the confirmation that the integration is alive, and the device information (operating system, machine, binary version) is sent and linked to the customer. None of this travels on your application thread. Events go into a queue on disk and a background thread ships them, so a slow network or an unreachable server never slows down or blocks the app.

The hook unit does not take away the handler you had. If you already had your own Application.OnException, the hook logs and then calls it; if you did not, it calls Application.ShowException. The error window your user saw before still appears, unchanged. And if one day you forget the unit in another project you are not left in the dark: the SDK notices it is running in a GUI app with no hook installed and writes a Warning of its own, tagged exewatch, which lands on your dashboard.

3. Log what interests you. From here on you log, count and time whenever you have something worth recording:

Open the dashboard and the events are there. From here on the guide is about bringing to mind everything that deserves to end up in there, because the list is longer than the one you would come up with right now.

That Quickstart was Delphi, the flagship. The what and why in the rest of this guide are the same for every SDK; only getting it in and initialized differs. Here is the setup for each. In all of them the last argument is your release label (AppVersion), and the API key is platform-prefixed (ew_win_, ew_lin_, ew_web_, and so on).

Delphi (native). As in the Quickstart: ExeWatchSDKv1 in the uses clause, plus ExeWatchSDKv1.VCL (or .FMX) if the app has a GUI, then InitializeExeWatch(ApiKey, CustomerId, '4.2.0'). The VCL/FMX unit captures unhandled GUI exceptions for you.

.NET. Reference the ExeWatch package (add ExeWatch.WinForms for a WinForms app), then initialize once at startup:

A console or service app skips the Install line: the client hooks AppDomain.UnhandledException on its own. WinForms needs the explicit Install before Application.Run.

Python. Install the SDK, initialize the singleton, and use the module-level ew afterwards:

Python has no GUI to hook, so capture failures where you handle them with ew.error_with_exception(exc, "tag"), or point sys.excepthook at it for a global net.

JavaScript (browser). You declare the configuration in window.ewConfig and then load the script from exewatch.com. The key is a ew_web_ key, and the SDK captures window.onerror automatically:

The order matters: the SDK initializes itself on DOMContentLoaded by reading window.ewConfig, so the configuration has to be on the page already when the script is loaded. Serve the script from exewatch.com, not from a copy of your own, so fixes reach your users without you having to redistribute anything.

This SDK is browser only, there is no Node build. Uncaught errors are collected for you, along with fetch and XHR failures and console.error calls. On a page that loads third-party scripts, ignoreUrls in the same ewConfig discards errors coming from domains you do not control, advertising and analytics for instance. That is noise which tells you nothing about your application.

DLL (C, C++, VB, legacy .NET, anything with a C ABI). Load ExeWatchSDKv1DLL.dll and call the flat exports. Strings are wide (PWideChar), every function is stdcall, and results come back as return codes:

Because a flat C ABI cannot walk the host stack or run a callback, two jobs fall to the host: pass a resolved stack string to ew_ErrorWithStackTrace, and drive periodic gauges from your own timer (there is no periodic-gauge callback). A Delphi host that prefers the DLL over the native units can use the import unit ExeWatchSDKv1Imports and call EWInitialize(…​) instead of InitializeExeWatch.

The same thing, in full, with MSVC. No import library and no Embarcadero runtime: define EW_DYNAMIC_LOAD before the header and every ew_* becomes a function pointer, which ExeWatchSDKv1.dynload.c resolves at runtime with LoadLibrary and GetProcAddress. This is a complete program, not a fragment:

It compiles in a single command, from an "x64 Native Tools Command Prompt for VS 2022", passing the folder that holds the header and the loader:

The only line here that is not ceremony is ew_WaitForSending. A command line utility can exit before the shipper thread has drained the queue, and that call writes the buffer to disk and waits for the queue to empty, returning how many events are still pending. It is not a data-loss problem, because the queue lives on disk and picks up again on the next run, but without the wait your events show up on the dashboard one run late. The compilable sample with everything else, user identity, global tags, breadcrumbs, nested timings and gauges, is in ExeWatchSamples/MSVCWithDLLSDK.

The same DLL from a Delphi console app. A Delphi host can use the DLL instead of the native units too, and in two cases that is the right choice: when you are on a Delphi older than XE8, which is the floor for the native SDK, and when you have several applications to update by shipping a single binary. The import unit ExeWatchSDKv1Imports goes back as far as Delphi 5. This one is a whole program too:

The wrappers with the EW prefix accept string and do the conversion to PWideChar themselves, so no cast appears in your code. Since this is a console app, the same two lines as before apply: ew_WaitForSending before exiting, and ew_Shutdown to close cleanly.

One thing to know before you ship. By default the unit links the DLL statically, so ExeWatchSDKv1DLL_x64.dll has to sit next to the executable at startup. If it is missing the process does not start at all: Windows stops it with a missing-DLL error before your first line of code runs. If you would rather have the application start anyway and only give up telemetry, define EW_DYNAMIC_LOAD in the project options. The unit switches to LoadLibrary, and you call EWLoadDLL at startup and check its result, the way the MSVC example above does.

And with Free Pascal. There is nothing Delphi-specific about the DLL: it is a flat C ABI, stdcall, wide strings. On Windows the same ExeWatchSDKv1Imports compiles under FPC, which the unit detects and switches to {$MODE DELPHI} by itself. Where string is not Unicode the internal alias becomes WideString and the EW* wrappers convert for you, so the code you write stays the code in the example above.

The Quickstart’s single InitializeExeWatch call is all most apps ever need. That third argument is AppVersion, your own release label ('4.2.0', '2026-Q1', 'v2-beta'); the binary version is a separate, auto-detected field read from the executable, so you get both from the one line. Here is what to reach for when that line is not enough.

This is a deliberate, supported flow, not a workaround. While the customer id is empty the SDK holds back the device-info record, because it needs the id to attach the device to the right customer, and sends it the moment you call SetCustomerId. If the id later changes (a different customer on the same machine) the SDK re-sends the device info under the new customer, so the device shows up correctly for both. The rule is simple: initialize first, identify when you can.

Customer and user are two different identities, set with two different calls. SetCustomerId sets the customer: the account or tenant this installation belongs to, which is what the dashboard groups devices and alerts by. Who is actually using the app is a separate thing, the user, and you set that with SetUser:

The id, email, and name then ride along with every event as user_id, so a crash shows not just which customer hit it but which person. Use SetCustomerId for the account and SetUser for the human; they are independent, and you can set either, both, or neither.

When the three-argument call is not enough, build a TExeWatchConfig and pass that instead. Every field has a sane default, so set only what you need:

The settings worth knowing:

The other SDKs take the same concepts under closely matching field names; the reference has the exact signature for each.

A blank dashboard is intimidating, and the first question is always the same: where do I start? The short answer is that if something interests you, record it. Do you want to know whether that function fails? Log it. How many times it gets used? Count it. Whether it is slow, and by how much? Time it. The mistake that costs you is not having sent a few events too many. It is standing in front of a production problem and finding that the one piece of code involved has nothing to say.

That moment always comes, and it comes on a Tuesday afternoon with a customer on the phone. You have the stack trace of the crash but you do not know what the user was doing a moment earlier, because you never logged that step. You know the sync takes forever but not which phase eats the time, because you timed only the total. In those twenty minutes you never regret the lines you sent too many. You regret the three you did not write.

So start generous. If something can fail, if it can get slow, if you need to know how much it is used, if it explains why the app behaved the way it did, send it. Adding more is easy while you are writing the code. Adding it later, when the build in question is already installed at three hundred customers, means a release and weeks of waiting. And the noise, if there is ever too much of it, you can turn down whenever you like: the minimum level and the sampling rate of each application are changed from the console, without recompiling anything.

The only thing not worth sending is what says nothing even to you: a Debug('I am here'), an Info('step 1'), a message with no context that makes sense only while you are typing it. The rest of the guide is there to bring to mind what does deserve a place, and to pick the right tool for each thing, since a crash, a usage count and a duration are recorded in three different ways.

Before the recipes, the map. ExeWatch gives you five instrumentation tools, and each one exists to answer a different question. Almost every "what do I track here?" decision becomes obvious once you know which question you are asking.

Two things are easy to miss, and both save you real work later.

Tags are the quiet sixth tool. Every log, counter, gauge, and timing call takes a tag, and there is a process-wide SetTag for context that rides along with everything. Tags are how you carve the dashboard into "payment" versus "sync" versus "ui" without inventing a separate metric for each feature. Get them right and every chart can be filtered the way you think; get them wrong and the dashboard turns into noise. The tag hygiene section is next, and it is short.

Device info is automatic and free. App version, binary version, OS, and hardware ship with every batch without a single call from you. Do not re-log them. The one field you set by hand is AppVersion, the release label, and that is exactly what makes version comparison possible later.

A tag is there to filter with, not to carry data. Keep them short, few, and stable over time, and the dashboard stays legible even after a few years of additions.

In practice:

Set the context that never changes once, at startup, so you are not repeating it on every call:

From then on every event carries that context, and you can filter the whole dashboard down to, say, the Pro edition on the stable channel without touching another line of code.

Tags you set with SetTag (or GlobalTags at init) become a Global Tags filter in the console, so you can slice every view by environment, edition, feature flag, and whatever else you tagged.

The recipes that follow use Delphi. The concepts are identical across SDKs; only the spelling changes. This table is the map, so a .NET or Python reader can translate any snippet at a glance. The console reference has the full signatures.

Two SDK-specific facts worth carrying into every recipe: the DLL has no periodic-gauge callback, so you drive it from your own timer, and JavaScript is browser-only. Everything else is a one-to-one rename.

Each recipe starts from a situation you have been in, or will be, and works back to the one thing worth instrumenting. One canonical Delphi snippet each; use the table above to translate it to your SDK. Where behavior genuinely differs, it is noted.

Those three tools get confused constantly, and confusing them does not throw an error, it silently records data that means nothing, which is worse. The distinction is simple once you say it out loud:

When in doubt, try adding two readings together. If the sum is meaningful, 12 exports plus 8 exports really is 20 exports, it is a counter. If the sum is nonsense, a queue of 12 plus a queue of 8 is not a queue of 20, it is a gauge. If what you care about is elapsed time, it is a timing.

An alert is what lets you stop watching the dashboard. Instead of checking in and hoping to catch a problem, you describe the problem once and ExeWatch emails you when it happens. Two kinds ship today, and it pays to know exactly what each one fires on, because the honest limits of alerting shape how you use everything above.

Log-volume alerts fire when the count of log events at or above a level crosses a threshold inside a window. You set threshold (a count), window_minutes, min_level (default error), an optional tags filter, an optional customer_external_id, and cooldown_minutes (default 60) so one incident does not page you fifty times. A typical one reads: "more than 20 fatal events in 15 minutes for customer Acme."

The same alert as a form in the console: a threshold over a time window at a minimum level, with a cooldown, optionally narrowed by tag and by customer. Scoping "Filter by Customer" to Acme is how you get paged about Acme’s errors without hearing about anyone else.

Error rate over time. A spike like the ones here is exactly what a log-volume alert watches for, so it reaches you by email the moment it starts instead of when you happen to open this chart.

Timing alerts fire when operations matching a timing id pattern run slower than a duration threshold, often enough to cross a count threshold inside a window. The fields are a timing_id_pattern, a duration threshold in milliseconds, an occurrence threshold (default 5), window_minutes, an optional customer_external_id, and cooldown_minutes (default 240). This is how you get told "report.render is running slow in the field" without watching for it.

The way to keep alerts useful instead of ignored: keep your log levels honest (see anti-patterns, or your error threshold fires on things that are not errors), scope each alert by tag or customer so it has a clear owner, and set a cooldown long enough that one real incident arrives as one email.

You ship a release and want to know whether it got slower or noisier than the last one. Today that comparison runs through CSV export, and the workflow is worth spelling out because it answers a question customers raise constantly.

The same export exists on the Logs and Metrics pages, so you can compare error volume or metric levels across versions the same way. An in-UI per-version timing filter is on the backlog; when it lands, this becomes a couple of clicks instead of a pivot. Until then, the CSV route is the supported way to do version-over-version comparison, and it works well enough that plenty of teams stop here.

Because every event carries its AppVersion, the console already knows how your releases are spread across the field. That same version label is what you pivot the exported timing by.

Isolated calls are easy to nod along to and hard to place. So here is instrumentation dropped into ordinary code: a sync method on a data module, the kind every line-of-business Delphi app has. First the plain version, doing its job with no telemetry:

Now the same method instrumented, each addition doing exactly one job:

What went where, and why:

Notice the shape: instrumentation frames the real code, it does not replace it. Delete every EW. line and the method still works exactly as before. The instrumentation only watches.

None of these is "you logged too much." They are the cases where what you send misleads you instead of helping you, and the fix sits next to each one.

Repeating the same line inside a loop. A Debug call in a hot loop, or an IncrementCounter on every iteration. The point is not the quantity. It is that five hundred identical lines all answer the same question the first one already answered, and meanwhile they eat the quota the real events needed. Record the operation, not its iterations: one line when it starts, one when it finishes or fails, and a single counter increment per logical operation. If you genuinely need the per-iteration detail during a diagnosis, keep it at Debug level and raise the minimum level of the application from the console when you are done.

Personal data in logs. Emails, names, tokens, or file contents in a message or a tag. Logs are retained and exportable to CSV, and tags are low-cardinality dimensions, not payloads, so this is both a privacy problem and a mess. Log ids and categories; use the customer id field for identity.

Levels that lie. Everything logged at Error, or genuine failures logged at Info. Alerts default to min_level = error, so if your levels are wrong your alerts are wrong with them, and you are either paged for nothing or never paged at all. The scale that keeps them honest: Fatal means the app cannot continue, Error means an operation failed, Warning means degraded but working, Info means a notable state change, Debug means developer-only detail.

Gauge and counter, swapped. A counter for "current queue depth" sums levels into a meaningless total; a gauge for "number of exports" throws the total away. Apply the addition test from the table above before you pick.

Tags that explode. An id, a timestamp, or any per-request value in a tag. Tags are dimensions with a small fixed set of values; unbounded values multiply into thousands of one-off dimensions and make the dashboard unusable. Keep the vocabulary small.

Re-logging what you already get for free. Manually logging OS, version, or hardware that already ships in the device snapshot with every batch. Do not. The only field you set by hand is AppVersion, the release label.

Desktop apps run on laptops that go into tunnels, on machines behind flaky VPNs, on a PC someone unplugs from the network at closing time. So this is a fair question: what happens to your telemetry when the SDK cannot reach the server?

Nothing is lost. The SDK does not send events straight from the call site. It buffers them, writes them to disk, and a background shipper thread does the sending. When the network is down the send simply fails, the files stay on disk, and the shipper retries on an interval. The moment connectivity returns, the queued files are shipped in order. A crash logged on a plane lands on your dashboard the next time the laptop gets online.

Four settings on TExeWatchConfig shape this:

You can watch the backlog yourself: GetPendingCount returns how many events are still waiting to ship.

One technical fact to know, and it comes at the end of the guide on purpose: the monthly quota is a live count of the rows you send during the month. Logs and metric updates count together, that is counters, gauges and timings, not logs alone. The internal SDK messages, the ones tagged ew.system, are left out of the count.

This is not an invitation to instrument less. The right order is the one you have followed so far: first you decide what you want to see, then, if and when volume becomes a topic, you manage it. The tools to manage it exist, and nobody is asking you to give up a number you care about.

If you sit consistently close to the ceiling with instrumentation you need all of, there is nothing to cut: you are watching more applications or more customers than when you chose the plan, and at that point it is worth moving up a tier.

A few things people ask for are planned but not shipped. They are listed here, honestly, so you know where today’s edges are and do not go looking for a feature that is not there yet.

For anything that does exist today, the SDK reference in the console has the exact signatures, config keys, and installation steps. This guide is the what and the why; that one is the how.