dokploy/apps/monitoring/README.md

Dokploy Monitoring (Go Version)

Application that powers Dokploy's monitoring service.

You can use it for monitoring any external service.

Requirements

• Go 1.21

Configuration

Create a .env file in the root of the project with the following content:

METRICS_CONFIG='{
  "server": {
    "refreshRate": 25,
    "port": 3001,
    "type": "Remote | Dokploy",
    "token": "metrics",
    "urlCallback": "http://localhost:3000/api/trpc/notification.receiveNotification",
    "retentionDays": 7,
    "cronJob": "0 0 * * *",
    "thresholds": {
      "cpu": 0,
      "memory": 0
    }
  },
  "containers": {
    "refreshRate": 25,
    "services": {
      "include": ["testing-elasticsearch-14649e"],
      "exclude": []
    }
  }
}'

Installation

go mod download

Execution

go run main.go

Endpoints

• GET /health - Check service health status (no authentication required)
• GET /metrics?limit=<number|all> - Get server metrics (default limit: 50)
• GET /metrics/containers?limit=<number|all>&appName=<name> - Get container metrics for a specific application (default limit: 50)

Features

Server

• CPU Usage (%)
• Memory Usage (%)
• Disk
• Network
• CPU Model
• Operating System
• Kernel
• Architecture
• Threads

Example response:

Field	Value
timestamp	2025-01-19T21:44:54.232164Z
cpu	24.57%
cpu_model	Apple M1 Pro
cpu_cores	8
cpu_physical_cores	1
cpu_speed	3228.0 MHz
os	darwin
distro	darwin
kernel	23.4.0
arch	arm64
mem_used	81.91%
mem_used_gb	13.11 GB
mem_total	16.0 GB
uptime	752232s
disk_used	89.34%
total_disk	460.43 GB
network_in	54.78 MB
network_out	31.72 MB

Containers

Compatible with all Docker container types (standalone containers, Docker Compose, and Docker Swarm stacks). Note: When monitoring Docker Compose or Swarm stacks, use the --p flag to properly identify all services within the stack.

Example response:

Field	Value
id	1
timestamp	2025-01-19T22:16:30.796129Z
container_id	7428f5a49039
container_name	testing-elasticsearch-14649e-kibana-1

Metrics JSON:

{
  "timestamp": "2025-01-19T22:16:30.796129Z",
  "CPU": 83.76,
  "Memory": {
    "percentage": 0.03,
    "used": 2.262,
    "total": 7.654,
    "usedUnit": "MB",
    "totalUnit": "GB"
  },
  "Network": {
    "input": 306,
    "output": 0,
    "inputUnit": "B",
    "outputUnit": "B"
  },
  "BlockIO": {
    "read": 28.7,
    "write": 0,
    "readUnit": "kB",
    "writeUnit": "B"
  },
  "Container": "7428f5a49039",
  "ID": "7428f5a49039",
  "Name": "testing-elasticsearch-14649e-kibana-1"
}

Notifications

Dokploy uses a callback URL to send notifications when metrics exceed configured thresholds. Notifications are sent via POST request in the following format:

Note: Setting a threshold to 0 disables notifications for that metric.

interface Notification {
  Type: "Memory" | "CPU";
  Value: number;
  Threshold: number;
  Message: string;
  Timestamp: string;
  Token: string;
}