Core Concepts

Go to your Application's API Keys page to get your API Key and download the SDK. Choose the files based on your application type:

Call InitializeExeWatch once when your application starts. The SDK works with any type of Delphi application: VCL, FMX, console, web servers, Windows services.

• Deferred Customer ID
• Console App
• Web Server
• Windows Service

uses
  ExeWatchSDKv1;  // + ExeWatchSDKv1.VCL for VCL GUI apps

begin
  // Initialize early with empty customer ID
  InitializeExeWatch('ew_win_your_api_key', '');

  EW.Info('Application starting...', 'Startup');

  // Later, after reading license/config file:
  CustomerId := LoadCustomerIdFromLicense();  // your function
  EW.SetCustomerId(CustomerId);

  EW.Info('License validated for: ' + CustomerId, 'License');
end.

program MyConsoleApp;

{$APPTYPE CONSOLE}

uses
  SysUtils,
  ExeWatchSDKv1;

begin
  try
    InitializeExeWatch('ew_win_your_api_key', '');

    // Read customer from command line or config
    if ParamCount >= 1 then
      EW.SetCustomerId(ParamStr(1));

    EW.Info('Processing started', 'Main');

    // Your application logic here...

    EW.Info('Processing completed', 'Main');
  except
    on E: Exception do
      EW.Fatal(E.Message, 'Main');
  end;

  // Wait for the shipper to drain the queue before the process exits
  EW.WaitForSending(15);
  FinalizeExeWatch;
end.

program MyWebServer;

{$APPTYPE CONSOLE}

uses
  MVCFramework.Console,
  Web.WebReq,
  ExeWatchSDKv1,
  WebModuleU in 'WebModuleU.pas';

begin
  // Initialize ExeWatch - customer ID is your server/instance name
  InitializeExeWatch('ew_lin_your_api_key', 'production-server-01');

  EW.Info('Web server starting on port 8080', 'Startup');

  RunServer(8080);
end.

// In your controller:
procedure TMyController.GetCustomers;
begin
  EW.StartTiming('get_customers', 'api');
  try
    // Your logic...
    Render(CustomerService.GetAll);
    EW.EndTiming('get_customers');
  except
    on E: Exception do
    begin
      EW.EndTiming('get_customers',
        TJSONObject.Create(TJSONPair.Create('error', E.Message)), False);
      raise;
    end;
  end;
end;

procedure TMyService.ServiceStart(Sender: TService; var Started: Boolean);
begin
  // Initialize ExeWatch - customer ID from registry or config
  InitializeExeWatch('ew_win_your_api_key', '');
  EW.SetCustomerId(ReadCustomerFromRegistry);

  EW.Info('Service started', 'Service');
  Started := True;
end;

procedure TMyService.ServiceStop(Sender: TService; var Stopped: Boolean);
begin
  EW.Info('Service stopping', 'Service');
  Stopped := True;
  // SDK shutdown is automatic
end;

procedure TMyService.Timer1Timer(Sender: TObject);
begin
  EW.StartTiming('background_job');
  try
    ProcessPendingTasks;
    EW.Info('Processed %d tasks', [TaskCount], 'Worker');
    EW.EndTiming('background_job');
  except
    on E: Exception do
    begin
      EW.EndTiming('background_job',
        TJSONObject.Create(TJSONPair.Create('error', E.Message)), False);
      EW.Error('Job failed: %s', [E.Message], 'Worker');
    end;
  end;
end;

Use the global EW object to log messages anywhere in your application.

uses
  ExeWatchSDKv1;

procedure TMainForm.ButtonClick(Sender: TObject);
begin
  // Log different severity levels
  EW.Debug('Button clicked', 'UI');
  EW.Info('Processing started', 'Core');
  EW.Warning('Low memory detected', 'System');
  EW.Error('Database connection failed', 'DB');
  EW.Fatal('Critical error - shutting down', 'Core');
end;

procedure TMainForm.FormCreate(Sender: TObject);
begin
  // Set user identity (optional but recommended)
  EW.SetUser('user123', 'john@acme.com', 'John Doe');

  EW.Info('Application started', 'Startup');
end;

Add the ExeWatch project reference to your solution. For WinForms apps, also add ExeWatch.WinForms. Download both from the SDK Downloads page.

Initialize the SDK at application startup:

using ExeWatch;

// Console / WPF / Service
ExeWatchSdk.Initialize(new ExeWatchConfig
{
    ApiKey = "ew_win_your_key",
    CustomerId = "ACME-Corp"
});

// WinForms - also install the GUI exception hook
using ExeWatch.WinForms;
ExeWatchWinForms.Install(); // before Application.Run()

// Console / CLI apps: wait for the shipper to drain before exiting
EW.WaitForSending(15);
ExeWatchSdk.Shutdown();

Use the EW shortcut class anywhere in your code:

using ExeWatch;

// Logging
EW.Info("User logged in", "auth");
EW.Error("Connection failed", "database");

// User identity
EW.SetUser("user123", "john@acme.com", "John Doe");

// Global tags
EW.SetTag("environment", "production");

// Breadcrumbs
EW.AddBreadcrumb("Opened Settings", "navigation");

// Performance timing with try/catch
EW.StartTiming("load_customers", "database");
try
{
    var data = LoadCustomers();
    EW.EndTiming("load_customers");
}
catch (Exception ex)
{
    EW.EndTiming("load_customers",
        new Dictionary<string, object> { ["error"] = ex.Message }, false);
    throw;
}

// Custom metrics
EW.IncrementCounter("orders_processed");
EW.SetGauge("queue_length", 42);

• Automatic Exception Capture — Unhandled exceptions, WinForms thread exceptions
• Offline Persistence — Logs saved to disk, sent when connection is available
• Hardware Info — CPU, RAM, disks, monitors, OS version
• User Identity — Track users across sessions
• Breadcrumbs — Trail of user actions before errors
• Performance Timing — Measure any operation with StartTiming/EndTiming
• Custom Metrics — Counters and gauges with periodic sampling
• Global Tags — Key-value context for all logs
• Server Config — Remotely adjust flush interval, batch size, log level, sampling
• Zero Dependencies — No NuGet packages required, uses System.Text.Json and System.Net.Http

Add the configuration object to your HTML page, before the SDK script. You'll find your API key in the dashboard under API Keys > JavaScript.

<!-- Add this before </body> -->
<script>
  window.ewConfig = {
    apiKey: 'ew_web_xxxxxxxxxxxxxxxx',
    customerId: 'ACME-Corporation'
  };
</script>

Add the SDK script right after the configuration. Use the minified version for production.

<!-- Production (minified, 12KB) -->
<script src="https://exewatch.com/static/js/exewatch.v1.min.js"></script>

<!-- Development (readable, 35KB) -->
<script src="https://exewatch.com/static/js/exewatch.v1.js"></script>

Use the global ew object anywhere in your JavaScript code (same as Delphi's EW).

// Set user identity (optional but recommended)
ew.setUser({ id: 'user123', email: 'john@acme.com', name: 'John Doe' });

// Log messages
ew.debug('Page loaded', 'init');
ew.info('User clicked checkout', 'ui');
ew.warning('Slow API response', 'api');
ew.error('Payment failed', 'checkout');

// Add breadcrumbs for debugging
ew.addBreadcrumb('Clicked Buy Now button', 'ui');
ew.addBreadcrumb('Navigated to /checkout', 'router');

// Set global tags
ew.setTag('environment', 'production');
ew.setTag('version', '2.5.0');

<!DOCTYPE html>
<html>
<head>
  <title>My Web App</title>
</head>
<body>
  <h1>Welcome</h1>
  <button onclick="doSomething()">Click me</button>

  <!-- ExeWatch Configuration -->
  <script>
    window.ewConfig = {
      apiKey: 'ew_web_xxxxxxxxxxxxxxxx',
      customerId: 'ACME-Corporation'
    };
  </script>
  <script src="https://exewatch.com/static/js/exewatch.v1.min.js"></script>

  <script>
    // Initialize user
    ew.setUser({ id: 'user123', email: 'john@acme.com' });
    ew.info('Page loaded', 'init');

    function doSomething() {
      ew.addBreadcrumb('Button clicked', 'ui');
      ew.info('User clicked the button', 'ui');
    }
  </script>
</body>
</html>

By default, the SDK captures all errors on the page, including failures from third-party scripts (Google Ads, analytics, fonts, social widgets). Use ignoreUrls to filter out noise from URLs you don't control.

<script>
  window.ewConfig = {
    apiKey: 'ew_web_xxxxxxxxxxxxxxxx',
    customerId: 'ACME-Corporation',
    ignoreUrls: [
      // Strings: match if URL contains the string
      'googlesyndication.com',
      'googleadservices.com',
      'google-analytics.com',
      'googletagmanager.com',
      'fonts.googleapis.com',
      'facebook.net',
      'doubleclick.net',

      // RegExp: for more complex patterns
      /analytics\..*\.com/,
      /cdn\.third-party\.io/
    ]
  };
</script>

Configure this only when all of the following apply:

• Your backend returns errors in a non-standard JSON schema (not { "message": ... }, { "detail": ... } or { "error": { "message": ... } })
• You want specific fields from that payload (e.g. exception, statuscode, traceId) promoted to the log title or to dedicated fields in extra_data for filtering
• The default raw responseBody capture (already enabled) isn't enough for your workflow

Example — API returns { "error": { "message": "...", "exception": "..." }, "statuscode": 500 }:

window.ewConfig = {
  apiKey: 'ew_web_xxxxxxxxxxxxxxxx',
  customerId: 'ACME-Corporation',

  // Optional: parse your custom error schema
  httpErrorExtractor: function(body, contentType, status, url) {
    try {
      var j = JSON.parse(body);
      return {
        message: j.error && j.error.message,          // shown in log title
        extra: {                                                // merged into extra_data
          apiException: j.error && j.error.exception,
          apiStatusCode: j.statuscode
        }
      };
    } catch (e) { return null; }  // fall back to default parsing
  }
};

Download the DLL package from your Application's API Keys page. It contains everything you need:

Add ExeWatchSDKv1Imports.pas to your project. Copy the appropriate DLL next to your executable.

Call EWInitialize once at application startup. Works with VCL apps, console programs, and Windows services.

• Deferred Customer ID
• VCL Application
• Console App
• Windows Service

uses
  ExeWatchSDKv1Imports;

begin
  // Initialize early — empty customer ID, capture startup logs immediately
  EWInitialize('ew_win_your_api_key', '');

  EWInfo('Application starting...', 'Startup');

  // Later, after reading license / config:
  CustomerId := LoadCustomerIdFromLicense;  // your function
  EWSetCustomerId(CustomerId);

  EWInfo('License validated for: ' + CustomerId, 'License');
end.

uses
  ..., ExeWatchSDKv1Imports;

procedure TMainForm.FormCreate(Sender: TObject);
begin
  if EWInitialize('ew_win_your_api_key', 'ACME-Corp') <> EW_OK then
  begin
    ShowMessage('ExeWatch init failed: ' + string(EWGetLastErrorStr));
    Application.Terminate;
    Exit;
  end;

  // Manual exception hook — replaces ExeWatchSDKv1.VCL unit
  Application.OnException := OnAppException;

  EWInfo('Application started', 'Startup');
end;

procedure TMainForm.FormDestroy(Sender: TObject);
begin
  ew_Shutdown;  // flush and close the SDK
end;

procedure TMainForm.OnAppException(Sender: TObject; E: Exception);
begin
  // Pass stack trace if you use JCL / madExcept / EurekaLog; otherwise empty
  EWErrorWithStackTrace(E.Message, 'exception', '', E.ClassName);
  Application.ShowException(E);
end;

program MyConsoleApp;

{$APPTYPE CONSOLE}

uses
  SysUtils,
  ExeWatchSDKv1Imports;

begin
  try
    EWInitialize('ew_win_your_api_key', '');

    if ParamCount >= 1 then
      EWSetCustomerId(ParamStr(1));

    EWInfo('Processing started', 'Main');

    // Your application logic here...

    EWInfo('Processing completed', 'Main');
  except
    on E: Exception do
      EWFatal(E.Message, 'Main');
  end;

  // Wait for the shipper to drain the queue before the process exits
  ew_WaitForSending(15);
  ew_Shutdown;
end.

procedure TMyService.ServiceStart(Sender: TService; var Started: Boolean);
begin
  EWInitialize('ew_win_your_api_key', '');
  EWSetCustomerId(ReadCustomerFromRegistry);
  EWInfo('Service started', 'Service');
  Started := True;
end;

procedure TMyService.ServiceStop(Sender: TService; var Stopped: Boolean);
begin
  EWInfo('Service stopping', 'Service');
  ew_Shutdown;
  Stopped := True;
end;

// Background job with timing
procedure TMyService.Timer1Timer(Sender: TObject);
var
  ElapsedMs: Double;
begin
  EWStartTiming('background_job', 'worker');
  try
    ProcessPendingTasks;
    EWEndTiming('background_job', ElapsedMs);
    EWInfo('Job completed', 'Worker');
  except
    on E: Exception do
    begin
      EWEndTiming('background_job', ElapsedMs);
      EWError('Job failed: ' + E.Message, 'Worker');
    end;
  end;
end;

Use the EW* convenience wrappers anywhere in your code. All accept plain Delphi strings.

// Five severity levels — same as native SDK
EWDebug('Entering payment handler', 'UI');
EWInfo('Processing started', 'Core');
EWWarning('Low memory detected', 'System');
EWError('Database connection failed', 'DB');
EWFatal('Critical failure — aborting', 'Core');

// User identity (optional)
EWSetUser('user-42', 'john@acme.com', 'John Doe');

// Breadcrumbs — attached to next Error/Fatal automatically
EWAddBreadcrumb(EW_BT_NAVIGATION, 'router', 'Opened customer details');
EWAddBreadcrumb(EW_BT_CLICK, 'ui', 'Clicked Save');
EWAddBreadcrumb(EW_BT_QUERY, 'db', 'UPDATE customers SET ...');
EWError('Save failed: connection lost', 'DB');  // breadcrumbs attached here

// Performance timing
var
  ElapsedMs: Double;
begin
  EWStartTiming('load_customers', 'database');
  try
    RunQuery;
    EWEndTiming('load_customers', ElapsedMs);
  except
    on E: Exception do
    begin
      EWEndTiming('load_customers', ElapsedMs);
      EWError('Query failed: ' + E.Message, 'DB');
    end;
  end;

// Metrics
EWIncrementCounter('orders.placed', 1, 'shop');
EWRecordGauge('active_connections', ActiveCount, 'db');

// Global tags (attached to all subsequent logs)
EWSetTag('environment', 'production');
EWSetTag('feature_flag', 'new_checkout');

Download the DLL package from your Application's API Keys page. Add these files to your C++Builder project:

Include the header with EW_DYNAMIC_LOAD, load the DLL, then call ew_Initialize. All string arguments use wide literals (L"...").

• VCL Application
• Console App
• Windows Service

// In your .cpp file — BEFORE any other ExeWatch include
#define EW_DYNAMIC_LOAD
#include "ExeWatchSDKv1.h"
// Also add ExeWatchSDKv1.dynload.c to the project

static const wchar_t* EXEWATCH_API_KEY = L"ew_win_your_api_key";

void __fastcall TMainForm::FormCreate(TObject *Sender)
{
    // Load the DLL (searches exe dir and Windows DLL path)
    if (ew_LoadSDK() != EW_OK) {
        ShowMessage("Failed to load ExeWatch DLL");
        Application->Terminate();
        return;
    }

    // Initialize the SDK
    if (ew_Initialize(EXEWATCH_API_KEY, L"ACME-Corp", L"") != EW_OK) {
        wchar_t errBuf[512];
        ew_GetLastError(errBuf, 512);
        ShowMessage(String("ExeWatch init failed: ") + errBuf);
        Application->Terminate();
        return;
    }

    // Hook unhandled VCL exceptions
    Application->OnException = OnAppException;

    ew_Info(L"Application started", L"startup");
}

void __fastcall TMainForm::FormDestroy(TObject *Sender)
{
    if (ew_IsSDKLoaded()) {
        ew_Shutdown();
        ew_UnloadSDK();
    }
}

void __fastcall TMainForm::OnAppException(TObject *Sender, Exception *E)
{
    String msg = String(E->ClassName()) + ": " + E->Message;
    ew_ErrorWithStackTrace(msg.c_str(), L"exception", NULL, E->ClassName().c_str());
    Application->ShowException(E);
}

#define EW_DYNAMIC_LOAD
#include "ExeWatchSDKv1.h"

int main()
{
    if (ew_LoadSDK() != EW_OK) return 1;

    ew_Initialize(L"ew_win_your_api_key", L"ACME-Corp", L"");
    ew_Info(L"Processing started", L"main");

    // Your logic...

    ew_Info(L"Processing completed", L"main");

    // Wait for the shipper to drain the queue before the process exits
    ew_WaitForSending(15);
    ew_Shutdown();
    ew_UnloadSDK();
    return 0;
}

void __fastcall TMyService::ServiceStart(TService *Sender, bool &Started)
{
    if (ew_LoadSDK() != EW_OK) { Started = false; return; }

    ew_Initialize(L"ew_win_your_api_key", L"", L"");
    ew_SetCustomerId(ReadCustomerFromRegistry());
    ew_Info(L"Service started", L"service");
    Started = true;
}

void __fastcall TMyService::ServiceStop(TService *Sender, bool &Stopped)
{
    ew_Info(L"Service stopping", L"service");
    ew_Shutdown();
    ew_UnloadSDK();
    Stopped = true;
}

// Background job with timing
void __fastcall TMyService::Timer1Timer(TObject *Sender)
{
    double elapsed;
    ew_StartTiming(L"background_job", L"worker");
    try {
        ProcessPendingTasks();
        ew_EndTiming(L"background_job", &elapsed);
        ew_Info(L"Job completed", L"worker");
    } catch (Exception &E) {
        ew_EndTiming(L"background_job", &elapsed);
        ew_Error(E.Message.c_str(), L"worker");
    }
}

All ew_* functions accept wchar_t* (wide strings). Use L"..." literals or UnicodeString::c_str().

// Five logging levels
ew_Debug(L"Entering payment handler", L"ui");
ew_Info(L"Processing started", L"core");
ew_Warning(L"Low memory detected", L"system");
ew_Error(L"Database connection failed", L"db");
ew_Fatal(L"Critical failure — aborting", L"core");

// User identity (optional)
ew_SetUser(L"user-42", L"john@acme.com", L"John Doe");

// Breadcrumbs — auto-attached to the next Error/Fatal
ew_AddBreadcrumb(EW_BT_NAVIGATION, L"router", L"Opened customer details", NULL);
ew_AddBreadcrumb(EW_BT_CLICK,      L"ui",     L"Clicked Save", NULL);
ew_AddBreadcrumb(EW_BT_QUERY,      L"db",     L"UPDATE customers SET ...", NULL);
ew_Error(L"Save failed: connection lost", L"db");  // breadcrumbs attached here

// Performance timing
double elapsed;
ew_StartTiming(L"load_customers", L"database");
try {
    RunQuery();
    ew_EndTiming(L"load_customers", &elapsed);
} catch (Exception &E) {
    ew_EndTiming(L"load_customers", &elapsed);
    ew_Error(E.Message.c_str(), L"db");
}

// Counters (cumulative)
ew_IncrementCounter(L"orders.placed", 1.0, L"shop");

// Gauges (point-in-time)
ew_RecordGauge(L"active_connections", (double)ActiveCount, L"db");

// Global tags
ew_SetTag(L"environment", L"production");
ew_SetTag(L"feature_flag", L"new_checkout");

Download the DLL package from your Application's API Keys page and add these files to your project:

Compile the loader alongside your source. No import library (.lib) required — dynload.c resolves everything at runtime via LoadLibrary + GetProcAddress.

cl /EHsc /W4 /nologo /I<sdk-dir> myapp.c <sdk-dir>\ExeWatchSDKv1.dynload.c

Define EW_DYNAMIC_LOAD before the header, call ew_LoadSDK() once, then ew_Initialize(). All string arguments use wide literals (L"...").

• Console / Batch
• Deferred Customer ID
• Windows Service

#define EW_DYNAMIC_LOAD
#include "ExeWatchSDKv1.h"
#include <cstdio>
// Compile with: cl /EHsc myapp.c ExeWatchSDKv1.dynload.c

int wmain()
{
    // Load DLL at runtime — no import library needed
    if (ew_LoadSDK() != EW_OK) {
        fwprintf(stderr, L"Failed to load ExeWatch DLL\n");
        return 1;
    }

    if (ew_Initialize(L"ew_win_your_api_key", L"ACME-Corp", L"1.0.0") != EW_OK) {
        wchar_t err[512] = {};
        ew_GetLastError(err, 512);
        fwprintf(stderr, L"Init failed: %ls\n", err);
        ew_UnloadSDK();
        return 1;
    }

    ew_Info(L"Processing started", L"main");

    /* your application logic here */

    ew_Info(L"Processing completed", L"main");

    // Wait for the shipper to drain the queue before the process exits
    int remaining = ew_WaitForSending(15);
    if (remaining > 0)
        fwprintf(stderr, L"%d event(s) still queued — will retry on next run\n", remaining);

    ew_Shutdown();
    ew_UnloadSDK();
    return 0;
}

#define EW_DYNAMIC_LOAD
#include "ExeWatchSDKv1.h"

ew_LoadSDK();

// Initialize early — empty customer ID, capture startup events immediately
ew_Initialize(L"ew_win_your_api_key", L"", L"1.0.0");

ew_Info(L"Application starting...", L"startup");

// Later, after reading license / config:
wchar_t customerId[256];
LoadCustomerIdFromLicense(customerId, 256);  /* your function */
ew_SetCustomerId(customerId);

ew_Info(L"License validated", L"license");

VOID WINAPI ServiceMain(DWORD argc, LPTSTR* argv)
{
    /* register service control handler, set status to START_PENDING ... */

    ew_LoadSDK();
    ew_Initialize(L"ew_win_your_api_key", L"", L"1.0.0");
    ew_SetCustomerId(ReadCustomerFromRegistry());
    ew_Info(L"Service started", L"service");

    /* set status to RUNNING, enter main service loop */
    ServiceLoop();

    ew_Info(L"Service stopping", L"service");
    ew_Shutdown();
    ew_UnloadSDK();
}

// Timed background job
void RunBackgroundJob()
{
    double elapsed;
    ew_StartTiming(L"background_job", L"worker");
    if (ProcessPendingTasks() == 0) {
        ew_EndTiming(L"background_job", &elapsed);
        ew_Info(L"Job completed", L"worker");
    } else {
        ew_EndTiming(L"background_job", &elapsed);
        ew_Error(L"Job failed", L"worker");
    }
}

All ew_* functions accept wchar_t*. Use L"..." literals or wide string buffers. Works identically across MSVC, MinGW, and Clang.

// Five logging levels
ew_Debug(L"Entering payment handler", L"ui");
ew_Info(L"Processing started", L"core");
ew_Warning(L"Low memory detected", L"system");
ew_Error(L"Database connection failed", L"db");
ew_Fatal(L"Critical failure", L"core");

// User identity (optional)
ew_SetUser(L"user-42", L"alice@acme.com", L"Alice Smith");

// Breadcrumbs — auto-attached to the next Error/Fatal
ew_AddBreadcrumb(EW_BT_NAVIGATION, L"nav",    L"Opened main screen",      NULL);
ew_AddBreadcrumb(EW_BT_CLICK,      L"ui",     L"Clicked 'Run report'",    NULL);
ew_AddBreadcrumb(EW_BT_QUERY,      L"db",     L"SELECT * FROM customers", NULL);
ew_Error(L"Save failed: connection lost", L"db");  // breadcrumbs attached here

// Performance timing
double elapsed;
ew_StartTiming(L"generate_report", L"reports");
GenerateReport();
ew_EndTiming(L"generate_report", &elapsed);
wprintf(L"Report done in %.1f ms\n", elapsed);

// Counters (cumulative) and gauges (point-in-time)
ew_IncrementCounter(L"reports.generated", 1.0, L"reports");
ew_RecordGauge(L"queue.depth", (double)QueueSize(), L"jobs");

// Global tags (attached to all subsequent events)
ew_SetTag(L"environment", L"production");
ew_SetTag(L"build",       L"msvc-x64");

The simplest way to initialize - provide API key and Customer ID at startup.

// Delphi
Config := TExeWatchConfig.Create('ew_desk_xxx', 'ACME-Corp');
InitializeExeWatch(Config);
EW.SendDeviceInfo;

Initialize the SDK without knowing the customer ID upfront. This is useful when:

• License validation happens after app startup
• User authentication determines the customer
• You want to track unlicensed installations

// Initialize without customer ID
Config := TExeWatchConfig.Create('ew_desk_xxx', '');  // Empty customer_id
InitializeExeWatch(Config);

// Logs are tracked by device_id until customer is set
EW.Warning('No valid license found', 'license');

// Later, after license validation...
EW.SetCustomerId('ACME-Corp');
EW.Info('License validated successfully', 'license');

The TExeWatchConfig record supports many options:

// Full configuration example
Config := TExeWatchConfig.Create('ew_desk_xxx', 'ACME-Corp');
Config.Release := '2.5.0';
Config.SampleRate := 0.5;  // Send 50% of debug/info events
Config.BufferSize := 50;
Config.FlushIntervalMs := 3000;
InitializeExeWatch(Config);

Use case: User switches between different accounts/licenses without restarting the application.

procedure TMainForm.FormCreate(Sender: TObject);
var
  Config: TExeWatchConfig;
begin
  Config := TExeWatchConfig.Create('ew_win_abc123...', 'CUSTOMER-A');
  InitializeExeWatch(Config);
  // Device info sent with customer_id = 'CUSTOMER-A'
end;

procedure TMainForm.OnUserSwitched(const NewCustomer: string);
begin
  // User switches from CUSTOMER-A to CUSTOMER-B
  EW.SetCustomerId(NewCustomer);

  // Device info is RE-SENT with the new customer_id
  // Backend updates the device to belong to the new customer
  EW.Info('User switched to ' + NewCustomer, 'auth');
end;

Use case: Desktop SaaS application where customer_id is determined after user login.

var
  FCurrentCustomer: string = '';

procedure TMainForm.FormCreate(Sender: TObject);
var
  Config: TExeWatchConfig;
begin
  // Initialize SDK WITHOUT customer_id
  Config := TExeWatchConfig.Create('ew_win_abc123...', '');
  InitializeExeWatch(Config);

  // Log without customer_id (user not logged in yet)
  EW.Info('Application started - waiting for login', 'startup');
end;

procedure TMainForm.OnLoginSuccess(const Username, Company: string);
begin
  // After login, set customer_id
  FCurrentCustomer := Company;
  EW.SetCustomerId(FCurrentCustomer);

  // From now on, all logs have customer_id
  EW.Info('User logged in: ' + Username, 'auth');
end;

procedure TMainForm.OnLogout;
begin
  EW.Info('User logged out: ' + FCurrentCustomer, 'auth');
  // Optionally reset customer_id for next user
  // EW.SetCustomerId('');
end;

Use case: Track custom deployment metadata like environment (production/staging), database version, or feature flags.

procedure TMainForm.FormCreate(Sender: TObject);
var
  Config: TExeWatchConfig;
  Environment, DBVersion: string;
begin
  // Read configuration from file/registry
  Environment := ReadEnvironmentFromConfig;  // 'production', 'staging', etc.
  DBVersion := GetDatabaseVersion;           // '5.2.1'

  Config := TExeWatchConfig.Create('ew_win_abc123...', 'CUSTOMER-ID');

  // Add custom device info (array of TPair)
  Config.InitialCustomDeviceInfo := [
    TPair<string, string>.Create('environment', Environment),
    TPair<string, string>.Create('db_version', DBVersion),
    TPair<string, string>.Create('deployment_region', 'EU-West')
  ];

  InitializeExeWatch(Config);
  EW.Info('Application started in ' + Environment, 'startup');
end;

// Update custom info at runtime
procedure TMainForm.OnFeatureFlagChanged(const Flags: string);
begin
  EW.SetCustomDeviceInfo('feature_flags', Flags);
  // Changes sent on next log batch
end;

Release is a version identifier that tags every log event with the version of your app that generated it. This lets you correlate errors and issues with specific versions of your software.

The SDK tracks two version-related values. Understanding the difference helps you use them correctly:

Choose a format that works for your release process:

The Updates page shows the current version state of every device in your application. Every time a device sends data to ExeWatch (logs, device info), its version information is automatically updated. The page provides stats, filters, and a version distribution chart to help you understand your deployment landscape at a glance.

To inspect a specific device's version history (past upgrades, downgrades), click on the device name to open its detail modal.

ExeWatch tracks two distinct version identifiers for each device. They serve different purposes and do not necessarily change together:

The Latest Version stat card shows the highest version currently deployed across all devices. Since version identifiers can vary in format, ExeWatch uses a gradual fallback strategy to determine which version is "the latest":

Examples

Every time your SDK initializes, it generates a unique session ID and sends an "Application started" log. ExeWatch uses this data — along with device IDs, customer IDs, and timestamps — to compute usage analytics automatically.

Navigate to Usage in the app toolbar and select a time period (1d, 7d, 30d, 90d, or All) to explore your application's usage data.

All widgets on the Usage page respect the selected period. The time bucket granularity adapts automatically:

Each stat card also shows a delta percentage comparing the current period to the previous period of equal length (e.g., last 7 days vs the 7 days before that).

Three signals are evaluated over the last 24 hours. The overall status is the worst of the three.

If there are fewer than 100 events in 24h, the error rate shows as Insufficient data instead of a potentially misleading percentage. All thresholds are customizable per application in App Settings → Health Thresholds.

ExeWatch won't flood your inbox when a metric hovers near a threshold. Three safeguards keep notifications meaningful:

• Hysteresis — once a signal enters a worse state, it needs to improve by a 30% margin before it can recover. For example, an error rate that crossed 1% (Degraded) must drop below 0.7% to return to Healthy.
• Consecutive confirmation — a new status must hold for 3 consecutive checks before it is accepted. A single spike won't change the status.
• Cooldown — after a notification is sent, the next one is held for at least 60 minutes (configurable in App Settings).

How It Works

1. Scatter breadcrumb calls where relevant things happen in your code (form opened, button clicked, query run, HTTP call). They are not meant to be added in batches — one per significant user action is the idea.
2. When an Error or Fatal log is emitted — whether by your code or by ExeWatch's automatic exception capture — the last 20 breadcrumbs from the same thread are automatically attached to that log event and then cleared.
3. Breadcrumbs are not attached to Info, Warning, or Debug logs.
4. View the trail in the ExeWatch dashboard log detail to understand the context that led to the error.

Delphi Example

Realistic usage: breadcrumbs are scattered across event handlers, not added four-in-a-row. When the try..except calls EW.ErrorWithException, all breadcrumbs from this thread are automatically attached.

procedure TSettingsForm.FormShow(Sender: TObject);
begin
  EW.AddBreadcrumb(btNavigation, 'router', 'Opened Settings screen');
end;

procedure TSettingsForm.btnSaveClick(Sender: TObject);
begin
  EW.AddBreadcrumb(btClick, 'ui', 'Clicked "Save" button');
  try
    EW.AddBreadcrumb(btQuery, 'db', 'UPDATE users SET ...');
    FDatabase.SaveSettings(FUser);

    EW.AddBreadcrumb(btHttp, 'api', 'POST /api/settings');
    FApi.NotifyBackend(FUser);
  except
    on E: Exception do
    begin
      // Manually logged error → breadcrumbs from this thread get attached
      EW.ErrorWithException(E, 'settings');
      raise;
    end;
  end;
end;

// Simpler form — overload with no type (defaults to btCustom):
EW.AddBreadcrumb('User selected product #456');

JavaScript — Automatic Breadcrumbs

The JavaScript SDK automatically captures breadcrumbs for common browser events. You don't need to call addBreadcrumb() for these — they are collected automatically when auto-capture is enabled (default):

• Navigation — history.pushState() and history.replaceState() calls (used by SPA routers like Angular, React Router, Vue Router)
• Clicks — user clicks on any element (captures tag name, id, class, and text)
• HTTP requests — all fetch() and XMLHttpRequest calls, including method, URL, and response status

These automatic breadcrumbs provide context about what the user was doing before an error occurred, without requiring any manual instrumentation. URLs matching ignoreUrls are excluded from HTTP breadcrumbs.

JavaScript — Manual Breadcrumbs

You can also add custom breadcrumbs for application-specific events:

// Add custom breadcrumbs: addBreadcrumb(message, category, data)
ew.addBreadcrumb('User selected Premium plan', 'billing');
ew.addBreadcrumb('Applied discount code SAVE20', 'checkout');

// Both automatic and manual breadcrumbs attach to the next error
ew.error('Payment processing failed', 'checkout');

How It Works

1. Call StartTiming('operation_name') before the operation
2. Call EndTiming('operation_name') after it completes
3. View timing statistics in the ExeWatch dashboard (Timing tab)
4. Operations exceeding the slow threshold are highlighted

Delphi Example

// Basic timing with try..except
EW.StartTiming('database_query');
try
  RunMyDatabaseQuery;
  EW.EndTiming('database_query');  // success
except
  on E: Exception do
  begin
    EW.EndTiming('database_query',
      TJSONObject.Create(TJSONPair.Create('error', E.Message)), False);
    raise;
  end;
end;

// With category for grouping
EW.StartTiming('load_customers', 'database');
try
  LoadCustomersFromDB;
  EW.EndTiming('load_customers');
except
  on E: Exception do
  begin
    EW.EndTiming('load_customers',
      TJSONObject.Create(TJSONPair.Create('error', E.Message)), False);
    raise;
  end;
end;

JavaScript Example

// Basic timing
ew.startTiming('api_call');
await fetch('/api/data');
ew.endTiming('api_call');

// With category
ew.startTiming('render_chart', 'ui');
renderComplexChart();
ew.endTiming('render_chart');

ExeWatch supports two types of metrics, inspired by Prometheus:

1. Your application records metrics using IncrementCounter or RecordGauge
2. The SDK aggregates values locally (min, max, avg, count)
3. Every 60 seconds, aggregated data is flushed to the ExeWatch server
4. For periodic gauges, the SDK automatically samples registered callbacks at a configurable interval (default 30s)
5. View metrics in the Metrics tab of your application dashboard

Counters

// Increment by 1 (default)
EW.IncrementCounter('api_calls');

// Increment by a specific value
EW.IncrementCounter('bytes_processed', FileSize);

// With a tag for grouping
EW.IncrementCounter('api_calls', 1, 'network');
EW.IncrementCounter('cache_hits', 1, 'database');

Gauges (manual)

// Record a point-in-time value
EW.RecordGauge('active_connections', ActiveCount);
EW.RecordGauge('queue_depth', Queue.Count, 'jobs');

Gauges (periodic / automatic)

// Register a callback that the SDK samples every 30s automatically
EW.RegisterPeriodicGauge('memory_mb',
  function: Double
  begin
    Result := GetProcessMemoryMB;
  end,
  'system');

// Unregister when no longer needed
EW.UnregisterPeriodicGauge('memory_mb');

Configuration

// Set gauge sampling interval (default 30s, min 10s)
Config.GaugeSamplingIntervalSec := 15;

// Counters
ew.incrementCounter('page_views');
ew.incrementCounter('api_calls', 1, 'network');

// Manual gauge
ew.recordGauge('items_in_cart', cart.length);

// Periodic gauge (auto-sampled every 30s)
ew.registerPeriodicGauge('dom_nodes', function() {
  return document.querySelectorAll('*').length;
}, 'performance');

// Unregister
ew.unregisterPeriodicGauge('dom_nodes');

// Force flush metrics immediately
ew.flushMetrics();

Configuration

// Set gauge sampling interval in config (default 30, min 10)
window.ewConfig = {
  apiKey: 'ew_web_xxx',
  customerId: 'customer123',
  gaugeSamplingIntervalSec: 15
};

User Identity represents the person currently using your application. This is different from Customer (which represents the company/organization) and Device (which represents the computer).

Example scenario: ACME Corporation (Customer) has 50 employees. Each employee has their own computer (Device). When John Doe logs into the app on his computer, you call SetUser so all his actions are tagged with his identity.

Call SetUser after the user logs into your application. All subsequent log events will include this user information.

// After user logs in successfully
EW.SetUser(
  'user-12345',     // ID - unique identifier
  'john@acme.com',  // Email (optional)
  'John Doe'        // Display name (optional)
);

// Now all logs include user info
EW.Info('Opened invoice #123', 'invoices');
EW.Warning('Slow query detected', 'db');
EW.Error('Failed to save', 'core');
// All these logs will show: user_id=user-12345

// When user logs out
EW.ClearUser;
EW.Info('User logged out', 'auth');

// After user logs in (pass an object)
ew.setUser({
  id: 'user-12345',
  email: 'john@acme.com',
  name: 'John Doe'
});

// All logs now tagged with user
ew.info('Added item to cart', 'cart');
ew.error('Payment failed', 'checkout');

// On logout
ew.clearUser();

The SDK ships events asynchronously in a background thread. For long-running applications (desktop GUI, Windows services) this is transparent — the thread keeps running and Shutdown handles the final flush automatically.

For short-lived processes — console tools, batch jobs, test suites, CI scripts — the process may exit before the shipper thread has had time to send everything. Calling WaitForSending before Shutdown ensures no events are lost.

• Delphi Native
• Delphi 4–XE7 (DLL)
• C++Builder (DLL)
• .NET / C#
• Python

program MyConsoleApp;

{$APPTYPE CONSOLE}

uses
  SysUtils, ExeWatchSDKv1;

var
  Remaining: Integer;
begin
  InitializeExeWatch('ew_win_your_api_key', 'ACME-Corp');

  EW.Info('Batch job started', 'job');
  RunBatchJob;
  EW.Info('Batch job completed', 'job');

  // Block until all events are shipped (timeout: 15 seconds)
  Remaining := EW.WaitForSending(15);
  if Remaining > 0 then
    Writeln('Warning: ' + IntToStr(Remaining) + ' event(s) still queued — will retry on next run');

  // Shutdown after WaitForSending — order matters
  FinalizeExeWatch;
end.

uses
  SysUtils, ExeWatchSDKv1Imports;

var
  Remaining: Integer;
begin
  EWInitialize('ew_win_your_api_key', 'ACME-Corp');

  EWInfo('Batch job started', 'job');
  RunBatchJob;
  EWInfo('Batch job completed', 'job');

  // Block until all events are shipped (timeout: 15 seconds)
  Remaining := ew_WaitForSending(15);
  if Remaining > 0 then
    Writeln('Warning: ' + IntToStr(Remaining) + ' event(s) still queued');

  ew_Shutdown;
end.

// Console / batch application example
#define EW_DYNAMIC_LOAD
#include "ExeWatchSDKv1.h"

int main()
{
    ew_LoadSDK();
    ew_Initialize(L"ew_win_your_api_key", L"ACME-Corp", L"");

    ew_Info(L"Batch job started", L"job");
    RunBatchJob();
    ew_Info(L"Batch job completed", L"job");

    // Block until all events are shipped (timeout: 15 seconds)
    int remaining = ew_WaitForSending(15);
    if (remaining > 0)
        fwprintf(stderr, L"%d event(s) still queued — will retry on next run\n", remaining);

    ew_Shutdown();
    ew_UnloadSDK();
    return 0;
}

using ExeWatch;

ExeWatchSdk.Initialize(new ExeWatchConfig { ApiKey = "ew_win_your_api_key", CustomerId = "ACME-Corp" });

EW.Info("Batch job started", "job");
RunBatchJob();
EW.Info("Batch job completed", "job");

// Block until all events are shipped (timeout: 15 seconds)
int remaining = EW.WaitForSending(15);
if (remaining > 0)
    Console.Error.WriteLine($"{remaining} event(s) still queued — will retry on next run");

ExeWatchSdk.Shutdown();

from exewatch import initialize_exewatch, ew, finalize_exewatch

initialize_exewatch('ew_win_your_api_key', 'ACME-Corp')

ew.info('Batch job started', 'job')
run_batch_job()
ew.info('Batch job completed', 'job')

# Block until all events are shipped (timeout: 15 seconds)
remaining = ew.wait_for_sending(15)
if remaining > 0:
    print(f"{remaining} event(s) still queued — will retry on next run", file=sys.stderr)

finalize_exewatch()

Return value & timeout guidance

A timeout of 10–30 seconds is appropriate for most batch jobs on a normal connection. For very large event volumes or slow connections, increase accordingly. Always call WaitForSending before Shutdown / FinalizeExeWatch.

What Data Does the SDK Collect?

Delphi Native SDK — Desktop, Server, Mobile

JavaScript SDK — Browser

Where Is Data Stored?

• Servers: ExeWatch data is stored on servers located in the European Union (EU)
• Encryption: All data is transmitted over HTTPS (TLS 1.2+)
• Retention: Data is retained according to your ExeWatch plan (7, 30, or 90 days) and automatically deleted after that period
• Sub-processors: See our Data Processing Agreement (DPA) for the full list of sub-processors

Copy and adapt the text below for your application's Privacy Policy or Terms of Service. Replace the placeholders in [brackets] with your own information.