Real-Time Monitoring, Metrics, and Alerting in Dokploy

Dokploy ships a first-party monitoring stack that collects and stores time-series metrics for both host machines and individual containers. All metrics are displayed in the dashboard as interactive charts — no third-party observability tools required for basic use cases. You can configure data retention, collection frequency, per-metric alert thresholds, and log-rotation policies directly from the Dokploy UI.

What is Monitored

Dokploy’s monitoring sidecar (a Go binary built from Dockerfile.monitoring) collects two categories of data:

Server (host) metrics

Field	Description
`cpu`	CPU utilisation percentage
`cpuModel`	Processor model name
`cpuCores` / `cpuPhysicalCores`	Logical and physical core count
`cpuSpeed`	Clock speed in GHz
`memUsed` / `memUsedGB` / `memTotal`	Memory usage in GB
`diskUsed` / `totalDisk`	Disk usage in GB
`networkIn` / `networkOut`	Network throughput in MB/s
`os` / `distro` / `kernel` / `arch`	Host OS information
`uptime`	System uptime in seconds
`timestamp`	ISO 8601 collection time

Container metrics

For each monitored container, the sidecar collects per-container data from docker stats:

Field	Description
`CPU`	CPU usage percentage
`Memory.percentage`	Memory utilisation %
`Memory.used` / `Memory.total`	Used and total memory
`Network.input` / `Network.output`	Network I/O
`BlockIO.read` / `BlockIO.write`	Disk block I/O
`Name` / `ID`	Container name and short ID

Metrics are stored in a local SQLite database inside the monitoring container and served over HTTP on a configurable port (default: 4500).

Accessing Monitoring

Dashboard monitoring page

Navigate to Monitoring in the Dokploy sidebar to see a fleet-wide view of server resource usage over time.

Per-application monitoring tab

Each application has a dedicated Monitoring tab. Under the hood it calls application.readAppMonitoring (getApplicationStats), which returns real-time Docker stats for the containers belonging to that application.

The per-application monitoring tab is only available for self-hosted Dokploy instances. The cloud version returns an error for this endpoint.

Server Metrics

user.getServerMetrics returns the current user record, which includes the user’s monitoring configuration. This is used to determine where the monitoring service is running and what token to use for authenticated requests. server.getServerMetrics fetches actual time-series data from the monitoring sidecar for a remote server. It takes three parameters:

{
  url: string;        // e.g. "http://<server-ip>:4500"
  token: string;      // bearer token configured during setup
  dataPoints: string; // number of data points to return, e.g. "50" or "all"
}

The response is an array of SystemMetrics snapshots ordered by timestamp. If the monitoring service is not running or the application is not yet included in the configuration, the endpoint returns a descriptive error:

No monitoring data available. This could be because:

1. You don't have setup the monitoring service, you can do in web server section.
2. If you already have setup the monitoring service, wait a few minutes and refresh the page.

Container Metrics

user.getContainerMetrics fetches per-container time-series data from the sidecar’s /metrics/containers endpoint. It requires:

{
  url: string;        // monitoring service base URL
  token: string;      // bearer token
  appName: string;    // Docker service / container name to filter by
  dataPoints: string; // number of historical records to return
}

The response is an array of ContainerMetric records, each containing the CPU, memory, network, and block I/O breakdown for that container at a point in time. If no appName is provided, or the container has no recorded data yet, the response is an empty array.

Metrics Token

user.getMetricsToken retrieves the configuration bundle needed to query monitoring endpoints programmatically:

{
  serverIp: string;           // primary server IP
  enabledFeatures: boolean;   // whether paid/monitoring features are active
  metricsConfig: {
    server: {
      type: "Dokploy" | "Remote";
      port: number;
      token: string;
      urlCallback: string;
      refreshRate: number;
      retentionDays: number;
      cronJob: string;
      thresholds: {
        cpu: number;    // alert threshold (%)
        memory: number; // alert threshold (%)
      };
    };
    containers: {
      refreshRate: number;
      services: {
        include: string[];  // container names to monitor
        exclude: string[];  // container names to skip
      };
    };
  };
}

Use this token and URL to query the monitoring API directly from external tools or scripts.

Monitoring Setup

Configure the primary (web) server

Navigate to Settings → Web Server → Monitoring and fill in:

Port – the port the monitoring sidecar will listen on (default: 4500)
Token – a secret bearer token; keep this private
Refresh rate – how often (in seconds) metrics are collected
Retention days – how many days of data to keep before auto-purging
Cron job – cron expression for the data-retention cleanup job
URL callback – the URL the sidecar posts alert payloads to when thresholds are exceeded
CPU threshold – CPU percentage that triggers an alert (e.g., 85)
Memory threshold – memory percentage that triggers an alert (e.g., 90)
Containers → include/exclude – list of Docker service names to collect container metrics for

Click Save & Setup. This calls admin.setupMonitoring, which saves the configuration and calls setupWebMonitoring() to start the monitoring container.

Configure remote servers (optional)

For each remote server in your fleet, navigate to Servers → [Server Name] → Monitoring and configure the same fields. Click Setup to call server.setupMonitoring, which copies the config to the remote server and starts the monitoring container there via SSH.

Verify the sidecar is running

The monitoring sidecar exposes a /health endpoint:

curl http://<server-ip>:4500/health
# {"status":"ok"}

If the health check fails, re-run setup or check Docker container logs for the dokploy-monitoring container.

Monitoring sidecar architecture

The sidecar is a standalone Go binary (Dockerfile.monitoring) that:

Reads configuration from the METRICS_CONFIG environment variable
Initialises a SQLite database for persistent storage
Starts a metrics collection goroutine that samples host stats at the configured refreshRate
Starts a ContainerMonitor that calls docker stats for each included service
Runs a cleanup cron job that purges records older than retentionDays
Serves a Fiber HTTP API secured by bearer-token middleware

Cleaning Monitoring Data

To purge all stored metrics without uninstalling the monitoring stack, use settings.cleanMonitoring. This recreates the monitoring data directory (MONITORING_PATH), effectively deleting all collected data.

Settings → Web Server → Monitoring → Clean Data

Cleaning monitoring data is irreversible. All historical metrics, including data used for trend charts, will be permanently deleted.

Log Management

Application and access logs accumulate over time. Dokploy can automatically rotate and delete old logs on a schedule.

Operation	API call	Description
Configure cleanup	`settings.updateLogCleanup`	Pass a cron expression to enable scheduled cleanup, or `null` to disable
Check status	`settings.getLogCleanupStatus`	Returns whether log cleanup is active and the current schedule

Example: enable daily log cleanup at midnight:

// settings.updateLogCleanup
{
  cronExpression: "0 0 * * *"
}

Pass null as the cronExpression to stop the scheduled job.

Threshold Alerts

When CPU or memory usage on a monitored server exceeds the configured thresholds, the monitoring sidecar POSTs an AlertPayload to the urlCallback URL:

{
  "ServerType": "Dokploy",
  "Type": "CPU",
  "Value": 92.5,
  "Threshold": 85.0,
  "Message": "CPU usage (92.50%) exceeded threshold (85.00%)",
  "Timestamp": "2024-11-01T12:05:00Z",
  "Token": "<your-token>"
}

The Type field is "CPU" for CPU alerts and "Memory" for memory alerts. The Token field in the payload allows you to verify the request came from your monitoring instance. Dokploy also integrates with its notification system: configure notification channels (Slack, Discord, email, webhooks, etc.) in Settings → Notifications so that threshold breaches are routed to your team automatically.

Set up at least one notification channel before deploying to production. Even with monitoring running, alerts are only useful if they reach someone. Navigate to Settings → Notifications → Add Notification to configure Slack, Telegram, Discord, email, or a custom webhook. Threshold notifications will be delivered to every active channel.

Get Started

Core Features

Infrastructure

Integrations

Administration

Enterprise

Real-Time Monitoring, Metrics, and Alerting in Dokploy

What is Monitored

Server (host) metrics

Container metrics

Accessing Monitoring

Dashboard monitoring page

Per-application monitoring tab

Server Metrics

Container Metrics

Metrics Token

Monitoring Setup

Monitoring sidecar architecture

Cleaning Monitoring Data

Log Management

Threshold Alerts

Build docs developers (and LLMs) love

Get Started

Core Features

Infrastructure

Integrations

Administration

Enterprise

Documentation Index

​What is Monitored

​Server (host) metrics

​Container metrics

​Accessing Monitoring

​Dashboard monitoring page

​Per-application monitoring tab

​Server Metrics

​Container Metrics

​Metrics Token

​Monitoring Setup

​Monitoring sidecar architecture

​Cleaning Monitoring Data

​Log Management

​Threshold Alerts

Build docs developers (and LLMs) love

What is Monitored

Server (host) metrics

Container metrics

Accessing Monitoring

Dashboard monitoring page

Per-application monitoring tab

Server Metrics

Container Metrics

Metrics Token

Monitoring Setup

Monitoring sidecar architecture

Cleaning Monitoring Data

Log Management

Threshold Alerts