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:

For FMX/Mobile apps (Android, iOS), see the Mobile SDK section or create a mobile platform application.

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;
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 or NuGet package to your solution. For WinForms apps, also add ExeWatch.WinForms.

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()

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>

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
  Config.InitialCustomDeviceInfo :=
    reference to procedure(var Info: TDictionary<string, string>)
    begin
      Info.Add('environment', Environment);
      Info.Add('db_version', DBVersion);
      Info.Add('deployment_region', 'EU-West');
    end;

  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. Add breadcrumbs as the user navigates and interacts with your app
2. When an error or fatal event occurs, breadcrumbs are automatically attached
3. View the trail in the ExeWatch dashboard to understand the context

Delphi Example

// Add breadcrumbs as user interacts
EW.AddBreadcrumb(btNavigation, 'router', 'Opened Settings screen');
EW.AddBreadcrumb(btClick, 'ui', 'Clicked "Save" button');
EW.AddBreadcrumb(btQuery, 'db', 'SELECT * FROM users WHERE id = 123');
EW.AddBreadcrumb(btHttp, 'api', 'POST /api/settings');

// When an error occurs, breadcrumbs are automatically included
EW.Error('Failed to save settings', 'settings');

// Simple breadcrumb (custom type)
EW.AddBreadcrumb('User selected product #456');

JavaScript Example

// Add breadcrumbs: addBreadcrumb(message, category, data)
ew.addBreadcrumb('Navigated to /checkout', 'navigation');
ew.addBreadcrumb('Clicked Pay Now button', 'ui');
ew.addBreadcrumb('POST /api/payment', 'api');

// Breadcrumbs attach to 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();

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.