metrics-tracker/watchlog

A PHP package for sending metrics.

2.0.0 2025-11-22 20:56 UTC

Requires

• guzzlehttp/guzzle: ^7.0

MIT

README

🔗 Website: https://watchlog.io

A lightweight PHP client for sending custom metrics to the Watchlog monitoring platform.

Installation

Install the package via Composer:

composer require metrics-tracker/watchlog

Basic Usage

use MetricsTracker\Watchlog;

$watchlog = new Watchlog();

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

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

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

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

// Set a system byte value
$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

Docker Run Example:

# 1. Create network
docker network create app-network

# 2. Run Watchlog Agent
docker run -d \
  --name watchlog-agent \
  --network app-network \
  -p 3774:3774 \
  -e WATCHLOG_APIKEY="your-api-key" \
  -e WATCHLOG_SERVER="https://log.watchlog.ir" \
  watchlog/agent:latest

# 3. Run PHP app (make sure your code uses new Watchlog('http://watchlog-agent:3774'))
docker run -d \
  --name php-app \
  --network app-network \
  -p 80:80 \
  my-php-app

Environment Detection

The package automatically detects the runtime environment:

• Local / non-K8s: http://127.0.0.1:3774
• Kubernetes: http://watchlog-node-agent.monitoring.svc.cluster.local:3774

Manual Override: You can override the endpoint by passing agentUrl parameter to the constructor:

$watchlog = new Watchlog('http://watchlog-agent:3774'); // Custom agent URL

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)
• All operations are asynchronous and fail-safe

License

MIT © Watchlog