Custom Events

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

Express Icon 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.ir
    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 Icon 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.ir
    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 Icon 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.ir
    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.ir
    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)
Last Updated::
Contributors: mohammad