Custom Events

Send Events via API (No Agent Required)

You can send custom events directly via a simple HTTP GET request — no agent installation needed. Just include your API key and event details as query parameters.

Endpoint:

GET https://event.watchlog.io/

Query Parameters:

Parameter	Required	Description
`apiKey`	Yes	Your Watchlog API Key
`metric`	Yes	Name of your custom metric/event
`type`	Yes	Event type (see below)
`value`	Yes	A numeric value
`cluster`	No	Optional cluster identifier

Supported types: increment, decrement, distribution, gauge, percentage, systembyte

You can get your API Key from app.watchlog.io.

Example:

https://event.watchlog.io/?type=increment&metric=YOUR_EVENT&value=1&apiKey=YOUR_APIKEY

More examples:

# Increment a counter
curl "https://event.watchlog.io/?type=increment&metric=page_views&value=1&apiKey=YOUR_APIKEY"

# Record a gauge value
curl "https://event.watchlog.io/?type=gauge&metric=cpu_usage&value=72.5&apiKey=YOUR_APIKEY"

# Record a percentage
curl "https://event.watchlog.io/?type=percentage&metric=completion_rate&value=85&apiKey=YOUR_APIKEY"

# With optional cluster
curl "https://event.watchlog.io/?type=increment&metric=orders&value=1&apiKey=YOUR_APIKEY&cluster=eu-west"

Send Events via Agent (Client Libraries)

After installing and configuring the Watchlog Agent, you can emit custom metrics/events directly from your application using our language-specific client libraries.

Note: Sending events via client libraries requires the Watchlog Agent to be installed and running on your server.

Node.js

Installation

npm install watchlog-metric

Basic Usage

const { default: watchlogMetric } = require("watchlog-metric")

// Increment a metric by a value (default is 1)
watchlogMetric.increment("Your_metric");
watchlogMetric.increment("Your_metric", 75);

// Decrement a metric by a value (default is 1)
watchlogMetric.decrement("Your_metric");
watchlogMetric.decrement("Your_metric", 25);

// Record a percentage (value between 0 and 100)
watchlogMetric.percentage("Your_metric", 12.23);

// Record a gauge (numeric value)
watchlogMetric.gauge("Your_metric", 12.23);

// Record system bytes (e.g., for memory or bandwidth)
watchlogMetric.systembyte("Your_metric", 1024000000); // 1 GB

TypeScript

import watchlogMetric from 'watchlog-metric';

watchlogMetric.increment("Your_metric");

Docker Setup

When running your Node.js app in Docker, you can specify the agent URL explicitly:

const { SocketCli } = require("watchlog-metric");

// Create client with explicit agent URL for Docker
const watchlogMetric = new SocketCli('http://watchlog-agent:3774');

watchlogMetric.increment("Your_metric", 1);

Docker Compose Example:

version: '3.8'

services:
  watchlog-agent:
    image: watchlog/agent:latest
    container_name: watchlog-agent
    ports:
      - "3774:3774"
    environment:
      - WATCHLOG_APIKEY=your-api-key
      - WATCHLOG_SERVER=https://log.watchlog.io
    networks:
      - app-network

  node-app:
    build: .
    container_name: node-app
    ports:
      - "3000:3000"
    depends_on:
      - watchlog-agent
    networks:
      - app-network

networks:
  app-network:
    driver: bridge

Important Notes:

When using Docker, use the container name as the hostname (e.g., watchlog-agent)
Both containers must be on the same Docker network
The agent must be running before your app starts
If agentUrl is not provided, auto-detection will be used (local or Kubernetes)

Python

Installation

pip install watchlog-python

Basic Usage

from watchlog import Watchlog

watchlog_instance = Watchlog()

# Increment a metric (default +1)
watchlog_instance.increment('page_views', 10)

# Decrement a metric (default -1)
watchlog_instance.decrement('items_in_cart', 2)

# Record a gauge value
watchlog_instance.gauge('current_temperature', 22.5)

# Record a percentage (0 to 100)
watchlog_instance.percentage('completion_rate', 85)

# Record system bytes
watchlog_instance.systembyte('memory_usage', 1024)

Docker Setup

When running your Python app in Docker, you can specify the agent URL explicitly:

from watchlog import Watchlog

# Create client with explicit agent URL for Docker
watchlog_instance = Watchlog(url='http://watchlog-agent:3774')

watchlog_instance.increment('page_views', 1)

Docker Compose Example:

version: '3.8'

services:
  watchlog-agent:
    image: watchlog/agent:latest
    container_name: watchlog-agent
    ports:
      - "3774:3774"
    environment:
      - WATCHLOG_APIKEY=your-api-key
      - WATCHLOG_SERVER=https://log.watchlog.io
    networks:
      - app-network

  python-app:
    build: .
    container_name: python-app
    ports:
      - "8000:8000"
    depends_on:
      - watchlog-agent
    networks:
      - app-network

networks:
  app-network:
    driver: bridge

Important Notes:

When using Docker, use the container name as the hostname (e.g., watchlog-agent)
Both containers must be on the same Docker network
The agent must be running before your app starts
If url is not provided, auto-detection will be used (local or Kubernetes)

PHP

Installation

composer require metrics-tracker/watchlog

Basic Usage

use MetricsTracker\Watchlog;

$watchlog = new Watchlog();

// Increment (default +1)
$watchlog->increment('page_views');
$watchlog->increment('page_views', 5);

// Decrement (default -1)
$watchlog->decrement('active_users');
$watchlog->decrement('active_users', 2);

// Record a gauge value
$watchlog->gauge('memory_usage', 512);

// Record a percentage (0 to 100)
$watchlog->percentage('cpu_usage', 75);

// Record system bytes
$watchlog->systembyte('disk_space', 1024000);

Docker Setup

When running your PHP app in Docker, you can specify the agent URL explicitly:

use MetricsTracker\Watchlog;

// Create client with explicit agent URL for Docker
$watchlog = new Watchlog('http://watchlog-agent:3774');

$watchlog->increment('page_views', 1);

Docker Compose Example:

version: '3.8'

services:
  watchlog-agent:
    image: watchlog/agent:latest
    container_name: watchlog-agent
    ports:
      - "3774:3774"
    environment:
      - WATCHLOG_APIKEY=your-api-key
      - WATCHLOG_SERVER=https://log.watchlog.io
    networks:
      - app-network

  php-app:
    build: .
    container_name: php-app
    ports:
      - "80:80"
    depends_on:
      - watchlog-agent
    networks:
      - app-network

networks:
  app-network:
    driver: bridge

Important Notes:

When using Docker, use the container name as the hostname (e.g., watchlog-agent)
Both containers must be on the same Docker network
The agent must be running before your app starts
If agentUrl is not provided, auto-detection will be used (local or Kubernetes)

C#

Installation

dotnet add package Watchlog.Metric

Basic Usage

using WatchlogMetric;

// Initialize the client
var watchlog = new WatchlogClient();

// Increment (default +1)
watchlog.Increment("your_metric");
watchlog.Increment("your_metric", 75);

// Decrement (default -1)
watchlog.Decrement("your_metric");
watchlog.Decrement("your_metric", 25);

// Record a percentage (0 to 100)
watchlog.Percentage("your_metric", 12.23);

// Record a gauge value
watchlog.Gauge("your_metric", 12.23);

// Record system bytes
watchlog.SystemByte("your_metric", 1024000000); // 1 GB

Docker Setup

When running your .NET app in Docker, you can specify the agent URL explicitly:

using WatchlogMetric;

// Create client with explicit agent URL for Docker
var watchlog = new WatchlogClient("http://watchlog-agent:3774");

watchlog.Increment("your_metric", 1);

Docker Compose Example:

version: '3.8'

services:
  watchlog-agent:
    image: watchlog/agent:latest
    container_name: watchlog-agent
    ports:
      - "3774:3774"
    environment:
      - WATCHLOG_APIKEY=your-api-key
      - WATCHLOG_SERVER=https://log.watchlog.io
    networks:
      - app-network

  dotnet-app:
    build: .
    container_name: dotnet-app
    ports:
      - "5000:5000"
    depends_on:
      - watchlog-agent
    networks:
      - app-network

networks:
  app-network:
    driver: bridge

Important Notes:

When using Docker, use the container name as the hostname (e.g., watchlog-agent)
Both containers must be on the same Docker network
The agent must be running before your app starts
If agentUrl is not provided, auto-detection will be used (local or Kubernetes)