The ExeWatch DevGuide

None of what follows is needed to get going. Add it when you actually need it, one line at a time.

Want to know which release an event came from? Pass a third argument.

That is AppVersion, your release label ('4.2.0', '2026-Q1', 'v2-beta'). The binary version is a separate field, which the SDK already reads from the executable on its own. This third argument is for when your idea of a release does not match the number compiled into the .exe.

You do not know the customer at startup? Initialize anyway, with an empty id, and set it as soon as you find out. The how and the why are in the Initialization: beyond the one-liner section, a little further on.

This is the situation logs and a stack trace exist for, and the good news is that turning it on is one line of setup. Add ExeWatchSDKv1.VCL (for a VCL app) or ExeWatchSDKv1.FMX (for FMX) to your uses clause, and the SDK hooks the framework exception path for you: every unhandled GUI exception is captured as Fatal, tagged exception, with its stack trace, and flushed immediately so nothing is lost as the app dies. If you forget the unit and the app is a GUI, the SDK notices and warns you to add it. By the time the customer picks up the phone, the crash is already on your dashboard, with the stack, the app version, the OS, and the customer id attached. You are no longer asking them to reproduce anything; you are reading what happened.

The exceptions you catch and handle yourself do not travel through that hook, so log those explicitly with the exception overload, which carries the stack trace along:

Across the other SDKs the shape is the same. .NET is EW.ErrorWithException(ex, "document") and also auto-captures unhandled exceptions. Python is ew.error_with_exception(…​). The DLL exposes ew_ErrorWithStackTrace(Msg, Tag, StackTrace, ExceptionClass): a flat C ABI cannot walk the host stack, so the host resolves the trace and passes the string in. The JavaScript SDK is browser only (ew_web_ keys) and auto-captures window.onerror.

What a captured crash looks like on the dashboard: an EAccessViolation with its stack resolved to unit, method, and line, alongside the session, device, and customer that hit it. This is a build with symbol info; without it the same frames would be bare addresses.

The last piece is not having to watch the dashboard for crashes at all. Wire an alert on fatal count (covered under Alerts below) and a spike reaches you by email, in minutes, instead of by support ticket, in days.

The stack trace answers the question where. Breadcrumbs answer the other half, the half you are always missing: what the user was doing before. They are crumbs you drop while the application works, and ExeWatch attaches them by itself to the next Error or Fatal, in order, next to the stack.

Watch how you write them, though, because this is where almost everyone gets it wrong the first time. They are not five lines one under the other. Each one sits where the thing actually happens, spread across the application, and between one and the next the user goes through screens and minutes of work.

Notice the values inside the messages too: the invoice number, the file name, the row count. Those values never belong in a tag, because each distinct value becomes a dimension and blows your dashboard apart. In a breadcrumb message they fit perfectly, and that is exactly where they earn their keep, because the difference between "imported a file" and "imported pricelist_2026.csv with 1284 rows" is the whole distance between a trail and a diagnosis.

When that crash lands on the dashboard you are no longer reading that there is an access violation inside SaveDocument. You are reading that this customer, and only this customer, imports an external price list before exporting, and that your export code has never seen rows shaped like that. The sequence you could not get anyone to describe is written right there.

The same thing helps in the more elusive version of the problem, the one where the error hits many customers but not always. With a dozen crashes on the dashboard you stop reasoning by hypothesis and start comparing trails: if a certain step appears in all of them and never appears in healthy sessions, the guessing is over. It is the same work you would do with logs, except you did not have to predict in advance which log you would need.

The type is one of a fixed set of sixteen values (btClick, btNavigation, btHttp, btQuery, btUser, btForm, btFile, btState, btTransaction, btConfig, btCustom and others), and the dashboard uses it to give an icon and make the trail readable at a glance. There is a short form too, EW.AddBreadcrumb('Export started'), when all you want is to leave a note.

Four behaviors to know, because they change what you find in front of you when it counts:

What is worth a breadcrumb: moving from one screen or dialog to another (btNavigation, btForm), the outbound calls you make (btHttp), the queries that matter (btQuery), the actions with which the user changes the state of the program, login, role switch, company switch (btUser), and the files the user opens or imports (btFile). The rule of thumb is simple: if tomorrow, looking at a crash, you would want to ask "what had they done before?", that is a crumb to drop today.

What the dashboard gives back: open the crash and next to the stack you find the last twenty steps that led to it, in order, with type and category. The same crash from two different customers reads as two different stories, and that is usually where it becomes clear which of the two is yours.

Drop one counter at the entry point of each feature you care about. A counter is the right tool here, not a log, because the question is "how many," and counters are summed into rollups on the backend, so what you read back is the total across every installation, cheaply, without you storing one row per click.

A month later the dashboard ranks your features by real usage, and the roadmap argument is settled by evidence: you extend what people use and quietly retire what they do not.

The fix is to measure the operation in the field and tag every measurement with the release that produced it. Wrap the operation in a timing pair, and set the release label at init so every sample knows its version:

The release label comes from init: InitializeExeWatch(ApiKey, CustomerId, '4.2.0') sets AppVersion for the run, while the binary version is auto-detected separately, so you get both. Now the workflow that answers the question: after the release has been live long enough to gather samples, open the "Timing" page, filter by time window, and use "Export CSV". The file respects your active filters and opens in Excel, where you pivot average and p95 duration by app_version. The sluggishness stops being an opinion and becomes "report.render went from 120ms to 300ms in 4.2," which you caught from your own field data before it turned into churn. A native in-UI "filter by version" view is on the backlog; until it ships, the CSV pivot is the supported path, and the same export works for "Logs", "Timing", and "Metrics" alike.

Nested traces break that four seconds apart. Start a trace, run a timing around each phase inside it, and end the trace. The backend reconstructs a waterfall, one bar per phase, so you can see which child actually dominates:

StartTrace returns a trace id and EndTrace returns the total elapsed milliseconds, so you can log or assert on the total if you want, and each nested timing becomes a child span. On the dashboard "checkout is slow" turns into "payment is 80% of checkout," which tells you the problem is the gateway, not your code, and saves you the day you would have spent optimizing the wrong phase. .NET and Python mirror this exactly; the DLL uses ew_StartTrace(Name, Buffer, BufLen), which writes the trace id into a caller-provided buffer, and ew_EndTrace(&ElapsedMs).

An aggregated trace: each phase is a bar with its avg, min, max, and p95, and the percentage tells you how much of the parent it accounts for. Here the transform and render phases dominate, so that is where the time goes. The statistics are computed over successful runs, so a failed phase does not skew them.

You will forget an EndTiming eventually. The SDK is built to survive it without leaking memory or reporting a wrong number, but what you get is never as good as a clean pair, which is the real reason for the try/finally. Here is exactly what happens to an open timing, depending on how it ends up:

The pattern across all four: a forgotten EndTiming becomes a failed sample plus a Warning, never a clean duration. That is the machinery protecting you, not a feature to lean on. Wrap every pair in try/finally and none of it ever fires.

A leak is a level that climbs and does not come back down, which is exactly what a gauge measures. You do not want to sprinkle gauge calls through your render loop; you want the value sampled on an interval. Register a periodic gauge and the SDK sampler thread reads your callback for you, with no timer of your own:

Good things to watch this way: working set in MB, GDI or handle count, open document count, cache size. After a day or two the dashboard shows the signature plainly, a sawtooth climbing all through each session and dropping at restart, and because a gauge keeps average, min, max, and sample count per window, the rising average and max are the leak. Slice by app_version and you can often pin it to the exact release that introduced it.

One divergence to respect: the periodic-gauge callback exists on Delphi, .NET (a Func<double>), Python, and JS, but not the DLL, because a callback cannot cross the flat C ABI. With the DLL the host owns the interval: run your own timer and call ew_RecordGauge(Name, Value, Tag) each tick.

If you set the customer id at init and tag your logs by subsystem, you can isolate any slice cleanly:

Now filter the dashboard to Acme’s sync errors and the picture resolves in seconds: it is one customer, behind a corporate firewall, not your code failing everywhere. Take it one step further and create an alert scoped by customer_external_id and tag, and you get paged about Acme’s sync problems specifically, while staying silent about the other 200 customers who are fine. Per-customer and per-feature error rates, each alertable on its own, all out of consistent tagging.

The simplest version is a counter per outcome, sliced by an outcome tag:

But if you are already timing the operation, you do not need a second counter, because EndTiming carries a success flag as its third parameter (default True):

This flag does something subtler than a counter, and it is worth understanding. A failed timing is not discarded: it is recorded, so you can count failures and see them in the timing list. But it is left out of the duration statistics. The average, min, max, and p95 on the "Timing" page are computed from successful runs only. That matters because failures are often the slowest calls, an operation that gave up after a 30-second timeout, and if those counted toward your latency you would think your sync got slower when really it started failing. With the success flag you read the true latency of the runs that worked and the failure rate, from one call.

You create a key in Settings → API access. Only the account owner sees the page, and the API is included in the paid plans: on Hobby the page explains what it does and points to the upgrade.

The key, which starts with ew_api_, is shown once, with a button to copy it. ExeWatch keeps only a fingerprint and cannot show it to you again: if you lose it, you create another. When a key is created, the owner gets an email with its name, scope and IP address, so a key you did not create stands out right away.

The list shows each key’s last use and the IP it came from. Revoking takes one click, and the key stops working within about ten seconds. Changing your password does not revoke keys, because they belong to the account and not to the user.

In the examples APP_ID is the application id (returned by GET /v1/applications) and the key is in the EXEWATCH_API_KEY variable.

The latest errors. /logs searches the events, most recent first. Without dates it looks at the last 24 hours.

The response has items, has_more and next_offset. When has_more is true, repeat the call with offset=<next_offset>.

A metric’s series. The name and the type (counter or gauge) go in the query string. /metrics lists the metrics you have.

Each point has bucket_start, value, min_value, max_value, avg_value and sample_count. Intervals with no data do not appear: for a gauge, an invented zero would be false data.

Pulling everything, at intervals. To copy your logs into a system of your own there is /logs/export. The first call passes since, the following ones pass the cursor you received. The two parameters are never sent together.

Repeat until has_more is false. A page covers at most 7 days of data, or 1 day if you filter by level, customer_id or device_id: a long span takes several calls. When has_more is false you are caught up. Keep the last next_cursor and next time resume from there, so you receive only what arrived in the meantime. The cursor holds only a position, so you can change the filters between calls.

The export does not deliver rows ExeWatch is still writing: data that arrived a few seconds ago shows up on the next call. since cannot be older than your plan’s retention (422); an older cursor resumes from the start of the retention.

/metrics/export works the same way on the metric rollups. Customers and machines are read with /customers and /devices.

All GET, under https://api.exewatch.com/v1.

The machines' hardware data and the extra data of customers and machines do not leave the API. The full schema, with types and response codes, is at https://api.exewatch.com/v1/openapi.json: it is the file to hand to a tool or an AI agent.

Limits apply per account, not per key: creating more keys does not give you more resources.

search accepts up to 200 characters and 5 words.

The 429 and the 503 carry the Retry-After header: wait that many seconds before retrying. A 504 does not pass by waiting, because the same query would take just as long: narrow the window or add a filter. Every API error has the shape {"error": "…​", "detail": "…​"}. The exception is the per-IP 429: it comes from the web server in front of the API, at most 60 requests per minute per IP, and its body may not be JSON. Shared egress addresses, such as those of a cloud BI service, count as a single IP.

Every log from /logs carries app_version, app_binary_version and session_id. The two versions are the ones the device declared when it wrote the log: app_version is set by the application, app_binary_version is read from the binary by the SDK. The value is null when there is no device snapshot for that log, and the empty string "" when the snapshot existed but had no version.

The same three fields are filters on /logs: app_version, app_binary_version and session_id. The match is exact, and the two versions are separate filters. Like search and tag, they limit the window to 7 days.

stack_trace and breadcrumbs live inside extra_data. The stack is under the key stack_trace in every SDK. JavaScript SDK clients older than 0.17.1 sent it under stack, so look there too.

ExeWatchMCP lets an AI agent read what your applications report to ExeWatch: errors, slow operations, metrics, versions, customers and devices. You ask it, from your editor, to explain what is slow, to fix last week’s errors or to say what to work on first, and it works on your code with the evidence in hand. It is an MCP server, so it works with any agent that supports MCP. The same package also installs exewatch, a command line for scripts and for agents that prefer a shell. It only reads and cannot change or delete anything, needs Python 3.9 or later and has no dependencies.

It installs two commands: exewatch-mcp, the MCP server, and exewatch, the command line.

The key. You need an API key, which means a paid plan. Create it as described in "Creating a key" above: it appears once, so copy it right away. The key goes in the environment of the server, never in a prompt. EXEWATCH_API_URL changes the server (default https://api.exewatch.com) and must be https; http is accepted only for localhost and 127.0.0.1.

Connect an agent. The agent starts the server itself: you give it the command and the key. In Claude Code:

In Codex:

Or, in the file ~/.codex/config.toml:

Any other agent with an mcpServers setting takes the same thing as JSON:

If the agent cannot find exewatch-mcp on its PATH, give the full path of the command, or the Python that installed it: "command": "python", "args": ["-m", "exewatch_cli", "mcp"].

Delphi and C++Builder. In RAD Studio, KAI, the AI assistant of the IDE, can use the same server. Register exewatch-mcp as an MCP server of KAI with the JSON above, and you can ask it, without leaving the IDE, to read what your program reported and to fix it. For KAI to point at the right line, compile the program with a detailed map file (Project Options, Linking, Map file) and enable stack frames (Compiling): without them the Delphi SDK cannot send a stack trace, and says why in no_stacktrace_reason.

One project only. The key decides what the agent can read. If you work on projects for different customers, create one key per customer, limited to that customer’s applications, and register the server in the project folder instead of for your whole user. In Claude Code, claude mcp add already does this: the default scope, local, covers only the folder you run it from, and the key stays in your user profile, out of the repository. To share the setup with the people who work on the project, use --scope project: Claude Code reads .mcp.json from the project folder, a file you commit. Write in it the name of an environment variable instead of the key, and each person sets the variable to their own key:

Claude Code replaces ${EXEWATCH_API_KEY} with the value of the variable when it starts the server. With several customers on the same computer, use a different name in each project, such as ${EXEWATCH_API_KEY_ACME}. Codex reads .codex/config.toml from the folder of a project you trust:

env_vars passes the variable from the environment Codex runs in to the server. There it must be called EXEWATCH_API_KEY, so with several customers start Codex from a terminal where it holds the right key.

The key in an environment variable. Instead of writing the key in the agent’s configuration you can set EXEWATCH_API_KEY once in your environment, as shown in "The command line" below, and register the server without --env: claude mcp add exewatch — exewatch-mcp. On Windows setx EXEWATCH_API_KEY ew_api_…​ makes the variable permanent, but only for programs started afterwards: reopen the terminal, the agent and RAD Studio.

What to ask. When the agent connects, the server gives it the rules for investigating with ExeWatch, and the agent can read the full guide with the tool exewatch_guide. A stack trace is often missing, so the agent also uses the message, the breadcrumbs, the events of the same session, the pattern of versions, customers and devices, the timings and the metrics. You can ask:

Put the name and the environment of the application in the instructions the agent reads for the project (CLAUDE.md, AGENTS.md or the equivalent), for example: "the ExeWatch application of this project is Invoices, PROD". The agent then does not have to guess, and it checks that the sdk_type of that application (delphi, delphi_dll, dotnet, python or javascript) matches the code it is working on.

What the agent can read.

Hardware details of a device, such as memory and free disk space, are in the console and are not available through the API: when the evidence points to them, the agent says so.

What to trust. Messages, stacks and names are text written by the software that sent them, sometimes by its users, which is why every result carries "untrusted_content": true: the agent reads them as data and does not follow instructions found in them. Customer names, e-mails and host names are personal data. A key limited to some applications is the right one to give to a contractor, and you revoke it from the same page where you created it.

The command line. exewatch does the same from a terminal, for scripts and for agents with a shell. Every command prints JSON. exewatch --help and exewatch <command> --help read like a Linux man page, and exewatch guide prints the guide. The key is read from the environment variable EXEWATCH_API_KEY; there is no --api-key option on purpose, because a key typed on the command line ends up in your shell history and in the process list.

The variable only lasts as long as the terminal session. To keep it, put it in your shell profile or in your user environment variables, and keep it out of any repository.

Start by listing your applications. The output is a single line, shown here formatted for readability.

To see the applications at a glance, --format table prints one plain line per application (environment, SDK, name, id), and --env keeps one environment: DEV, TEST, STAGING or PROD, in any case. The table has no untrusted_content envelope: application names are still text written by someone else, so treat them as data.

--app takes the exact name (case does not matter) or the id. If two applications share a name, as the same application does in PROD and in DEV, add --env to say which one. Without it the error lists their environments and ids. With an id, --env is only checked: if the application lives in another environment, the command stops.

Each item is compact, to save context. With --full you get the whole record, including extra_data, where the stack (stack_trace, or stack for JavaScript SDK clients older than 0.17.1) and the breadcrumbs live. For a timing the compact item also shows duration_ms and success.

groups, timings and versions take --app, --env, --since (7d if omitted) and --scan, the largest number of events to read (2000 if omitted, at most 10000). groups and timings also take --version, --tag, --customer, --device and --limit, the number of items to print (20 if omitted). They read the newest events first, and say so: when sampled is true in the result, the period holds more events than were read, and the result describes the newest ones.

To go past --limit in errors and logs, repeat the command with --to set to the client_timestamp of the last item you received.

Things worth knowing:

Errors go to stderr (in the MCP server they come back as an error of the tool) and never include the key. The exit code is 0 on success, 1 for an API or network error, 2 for wrong usage or a missing key.

The context of an error. Fetch the error’s session and stop at the moment of the error: you see what the user did right before it.

If the session lasts longer than the default 24 hours, add --from too. To read the stack and the breadcrumbs of that very error, add --limit 1 --full and use errors instead of logs.

What is slow. timings lists the measured operations, the slowest first by 95th percentile, with the same figures per version: a release that made an operation slower shows up there. Read the slowest occurrence with logs --full for what the application attached to the measure, and look around it with --session. A trace shows only its total, not its steps. Only operations the application measures with start_timing appear: if there are none, that is the first thing to add.

Is this version worse than the previous one. versions gives errors and devices per version. Then run groups --version for each of the two versions: an error group that exists only in the later one, or whose first appearance is after its release, is a regression. The rates in versions are rough, so do not decide on them alone.

Why a metric is high. metrics gives the exact name, type and tag; series gives the values over time, where a counter shows the sum in each bucket and a gauge the last value. Compare the hour the value rose with versions (a release at that moment?) and with groups over the same hours.

An error with no stack. A stack is often missing, and the other evidence is enough more often than you would think: the message, the breadcrumbs, the events of the same session before it, the version, the customer and the device. If no_stacktrace_reason is set, it says why the SDK sent none: for Delphi the usual cause is a program compiled without the detailed map file.

A version filter that matches nothing. The filter is an exact match: 2.3 does not match 2.3.0.145. Run the command again without the filter and read app_version in the results. An empty string means the device snapshot had no version, null means there was no snapshot at all.

Where the stack is. The .NET SDK writes the stack at the end of message, and stack_trace stays null. Stacks from minified JavaScript do not point back to the source.

A stack that is too long. If extra_data goes over 30 KB, ExeWatch cuts the tail of the longest text, usually the stack, and leaves a marker at the end: […​ N characters truncated by ExeWatch …​]. If the excess is in breadcrumbs and not in a text, the whole extra_data is dropped and the message stays. In both cases the reason is written in an ew.system log.

From version to source. app_version does not say which commit it is: to get there you need the git tags of your own application.

Paging limits. --to is inclusive: on the next page the last row you already received shows up again. With more than one --level (and with errors, which asks for error and fatal) more than one row can reappear: every row already received with the same instant as the last one. If more than --limit rows share the same instant, there is no way past them. Raise --limit (at most 1000) or narrow the search with a filter.

Trying it from Swagger Editor. In Swagger Editor, import the file https://api.exewatch.com/v1/openapi.json (File → Import URL) or paste its content. The schema declares the server, so "Try it out" calls the API directly: enter the key in Authorize.

If a piece of information would be useful to you outside the console, in a report or a spreadsheet, that is a good reason to log it.