> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/wazuh/wazuh-dashboard-plugins/llms.txt
> Use this file to discover all available pages before exploring further.

# Agent Monitoring

> Monitor agent health, performance, and statistics using the Wazuh Dashboard's comprehensive monitoring features.

## Introduction

The Wazuh Dashboard provides real-time monitoring capabilities for deployed agents, enabling administrators to track agent health, performance metrics, and operational statistics. The monitoring interface offers detailed insights into agent communication, event processing, and system status.

## Agent Status Monitoring

### Status Overview

Agents are continuously monitored and categorized by their connection status:

* **Active**: Agents actively communicating with the manager
* **Disconnected**: Agents that lost connection with the manager
* **Pending**: Newly registered agents awaiting initial configuration
* **Never Connected**: Registered agents that have not established communication

Each status category is color-coded for quick visual identification:

* **Active**: Green (success status)
* **Disconnected**: Red (danger status)
* **Pending**: Yellow (warning status)
* **Never Connected**: Gray (disabled status)

Status implementation: `wz_agent_status.ts:1`

### Status Codes and Descriptions

The dashboard displays detailed status codes with descriptions:

* Each agent has a `status_code` that provides granular information about its state
* Status descriptions explain the reason for the current status
* Hover tooltips display the full status description
* An information icon (iInCircle) provides additional context

Component implementation: `agent-status.tsx:1`

### Synchronization Status

In addition to connection status, agents display synchronization status:

* **Synced**: Agent configuration is synchronized with the manager
* **Not Synced**: Agent has pending configuration updates
* **Syncing**: Synchronization in progress

Synchronization monitoring ensures agents receive the latest:

* Configuration changes
* Group policy updates
* Manager directives
* Module settings

Component implementation: `agent-synced.tsx:1`

## Agent Statistics Dashboard

### Accessing Agent Statistics

To view detailed statistics for an agent:

1. Navigate to the Endpoints section
2. Select an agent from the table
3. Navigate to the "Stats" tab

Navigation path: `/agents?tab=stats&agent={agent_id}`

Component implementation: `agent-stats.tsx:1`

### Agent Requirements

The statistics dashboard requires:

* **Agent Status**: Must be "Active"
* **Agent Version**: Equal to or higher than 4.2.0
* **Permissions**: `agent:read` permission on the specific agent or its groups

Agents not meeting these requirements will display appropriate prompts:

* Inactive agents: `PromptNoActiveAgentWithoutSelect`
* Version incompatibility: `PromptAgentFeatureVersion`

### Statistics Ribbon

The statistics ribbon displays key agent metrics:

#### Status

Current operational status of the agent.

#### Buffer

Indicates whether the message buffer is enabled or disabled.

* **Enabled**: Agent can queue messages when manager is unreachable
* **Disabled**: Messages may be lost during connection interruptions

#### Message Buffer

Number of messages currently in the agent's buffer.

#### Messages Count

Total number of messages processed by the agent.

#### Messages Sent

Total number of messages successfully sent to the manager.

#### Last Acknowledgment

Timestamp of the last message acknowledgment from the manager.

* Formatted for readability using `formatUIDate()`
* Indicates manager-agent communication health

#### Last Keep Alive

Timestamp of the last keep-alive signal from the agent.

* Critical indicator of agent connectivity
* Formatted using `formatUIDate()`
* Used to detect communication failures

### Log Collector Statistics

The statistics dashboard displays two log collector tables:

#### Global Statistics

Cumulative statistics since the agent started:

* **Location**: Log file or source being monitored
* **Events**: Total number of events collected
* **Bytes**: Total bytes processed
* **Start Time**: When collection began
* **End Time**: Latest collection timestamp

#### Interval Statistics

Statistics for the current collection interval:

* **Location**: Log file or source being monitored
* **Events**: Events collected in the current interval
* **Bytes**: Bytes processed in the current interval
* **Start Time**: Interval start timestamp
* **End Time**: Interval end timestamp

### Statistics Export

Both statistics tables support CSV export:

* **Global Export**: `agent-stats-{agent_id}-logcollector-global.csv`
* **Interval Export**: `agent-stats-{agent_id}-logcollector-interval.csv`

Export functionality is provided by the `AgentStatTable` component.

Component implementation: `table.tsx:1`

## API Endpoints for Statistics

### Agent Statistics Endpoint

```
GET /agents/{agent_id}/stats/agent
```

Returns:

* Agent operational status
* Buffer configuration and usage
* Message counts and statistics
* Acknowledgment timestamps
* Keep-alive information

Response structure:

```json theme={null}
{
  "data": {
    "affected_items": [{
      "status": "active",
      "buffer_enabled": true,
      "msg_buffer": 0,
      "msg_count": 15234,
      "msg_sent": 15234,
      "last_ack": "2026-03-04T10:30:45Z",
      "last_keepalive": "2026-03-04T10:31:00Z"
    }]
  }
}
```

### Log Collector Statistics Endpoint

```
GET /agents/{agent_id}/stats/logcollector
```

Returns:

* Global collection statistics
* Interval collection statistics
* Per-location metrics

Response structure:

```json theme={null}
{
  "data": {
    "affected_items": [{
      "global": {
        "start": "2026-03-01T00:00:00Z",
        "end": "2026-03-04T10:31:00Z",
        "files": [
          {
            "location": "/var/log/syslog",
            "events": 5432,
            "bytes": 1234567
          }
        ]
      },
      "interval": {
        "start": "2026-03-04T10:00:00Z",
        "end": "2026-03-04T10:31:00Z",
        "files": [
          {
            "location": "/var/log/syslog",
            "events": 123,
            "bytes": 34567
          }
        ]
      }
    }]
  }
}
```

## Real-Time Monitoring

### Agent Table Refresh

The agents table supports real-time monitoring through:

* **Automatic Reload**: Table data refreshes at configured intervals
* **Manual Reload**: Click the refresh button to update immediately
* **External Reload**: Triggered by dashboard events (e.g., status changes)

Reload mechanism:

```typescript theme={null}
const reloadAgents = async () => {
  setReloadTable(Date.now());
  if (props.setExternalReload) {
    props.setExternalReload(Date.now());
  }
};
```

### Live Status Updates

Agent status updates are reflected in real-time:

* Color-coded status indicators update automatically
* Sync status changes are immediately visible
* Last keep-alive timestamps update dynamically
* Disconnection events trigger visual alerts

## Agent Keep-Alive Monitoring

### Keep-Alive Mechanism

Agents send periodic keep-alive signals to the manager:

* Default interval: 10 seconds
* Configurable in agent configuration
* Used to detect agent failures
* Triggers status changes when missed

### Keep-Alive Thresholds

Agent status transitions based on keep-alive signals:

1. **Active**: Keep-alive received within expected interval
2. **Disconnected**: Keep-alive missed for configured timeout period
3. **Manager Action**: Manager may trigger alerts or automated responses

### Monitoring Keep-Alive

View keep-alive information:

* **Agent Table**: "Last Keep Alive" column shows timestamp
* **Agent Details**: Detailed keep-alive information in agent view
* **Statistics**: "Last Keep Alive" metric in stats ribbon

## Event Monitoring

### Events Count Dashboard

The agent welcome screen displays real-time event counts:

* Total events processed
* Events by category (security, system, network, etc.)
* Event trends over time
* Comparison with historical data

Component implementation: `events-count.tsx:1`

### Event Categories

Events are categorized for monitoring:

* **Security Events**: Security-related detections and alerts
* **System Activity**: System-level events and changes
* **Network Activity**: Network traffic and connections
* **Cloud Services**: Cloud provider events (AWS, Azure, GCP)
* **Applications**: Application-specific events
* **Access Management**: Authentication and authorization events

## Performance Monitoring

### Message Processing

Monitor agent message processing performance:

* **Messages Count**: Total messages processed
* **Messages Sent**: Messages successfully delivered to manager
* **Message Rate**: Messages per second
* **Buffer Usage**: Current buffer utilization

### Resource Usage

While not directly displayed in the statistics dashboard, monitor:

* CPU usage through system inventory
* Memory consumption via system metrics
* Disk I/O for log processing
* Network bandwidth utilization

## Health Checks

### Agent Health Indicators

Key indicators of agent health:

1. **Connection Status**: Should be "Active"
2. **Keep-Alive Frequency**: Regular intervals without gaps
3. **Message Delivery**: Messages sent should equal messages counted
4. **Buffer Status**: Buffer should not be consistently full
5. **Synchronization**: Agent should remain synced

### Warning Signs

Indicators that require attention:

* Frequent status transitions (Active ↔ Disconnected)
* Growing message buffer without delivery
* Prolonged "Not Synced" status
* Irregular keep-alive intervals
* Messages counted significantly higher than messages sent

## Monitoring Alerts

### Status Change Notifications

The dashboard can be configured to alert on:

* Agent transitions to "Disconnected" status
* Agents remaining in "Never Connected" state
* Synchronization failures
* Keep-alive timeout events

### Custom Monitoring Rules

Administrators can create custom monitoring rules:

* Define thresholds for message buffer usage
* Set acceptable keep-alive intervals
* Configure alerts for specific status codes
* Monitor message delivery rates

## Bulk Monitoring

### Multi-Agent Overview

Monitor multiple agents simultaneously:

* **Dashboard View**: Status distribution across all agents
* **Filtered Monitoring**: Focus on specific groups or statuses
* **Bulk Operations**: Act on multiple agents based on status

### Group-Based Monitoring

Organize monitoring by agent groups:

* View statistics aggregated by group
* Compare performance across groups
* Identify group-wide issues
* Apply group-level monitoring policies

## Troubleshooting with Monitoring Data

### Connectivity Issues

**Symptoms:**

* Agent status: Disconnected
* Last keep-alive: Outdated timestamp
* Messages sent: Not increasing

**Investigation:**

1. Check last keep-alive timestamp gap
2. Verify network connectivity
3. Review agent and manager logs
4. Test manager port accessibility

### Performance Issues

**Symptoms:**

* High message buffer usage
* Messages sent \< messages counted
* Slow event processing

**Investigation:**

1. Review buffer statistics
2. Check manager resource usage
3. Analyze network latency
4. Verify log collector configuration

### Synchronization Issues

**Symptoms:**

* Agent status: Not synced
* Configuration changes not applied
* Group assignments not reflected

**Investigation:**

1. Check synchronization status
2. Verify group memberships
3. Review configuration distribution logs
4. Manually trigger synchronization

## Best Practices

### Regular Monitoring

* Review agent status daily
* Monitor keep-alive timestamps for anomalies
* Track message processing rates
* Investigate buffer growth patterns

### Threshold Configuration

* Set appropriate keep-alive timeout values
* Configure buffer sizes based on network reliability
* Establish baseline performance metrics
* Define acceptable status transition frequencies

### Proactive Maintenance

* Address "Disconnected" agents promptly
* Investigate "Never Connected" agents within 24 hours
* Monitor for agents with outdated versions
* Regularly review synchronization status

### Documentation

* Document normal operating parameters
* Record baseline statistics for comparison
* Maintain runbooks for common issues
* Track patterns in status changes

## Related Documentation

* [Agent Management Overview](/agents/overview)
* [Agent Deployment](/agents/deployment)
* [Agent Configuration](/agents/configuration)
* [System Inventory](/agents/system-inventory)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.