Agent Monitoring

​

Introduction

​

Agent Status Monitoring

​

Status Overview

• 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

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

​

Status Codes and 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

​

Synchronization Status

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

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

​

Agent Statistics Dashboard

​

Accessing Agent Statistics

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

​

Agent Requirements

• 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

• Inactive agents: PromptNoActiveAgentWithoutSelect
• Version incompatibility: PromptAgentFeatureVersion

​

Statistics Ribbon

​

Status

​

Buffer

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

​

Message Buffer

​

Messages Count

​

Messages Sent

​

Last Acknowledgment

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

​

Last Keep Alive

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

​

Log Collector Statistics

​

Global Statistics

• 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

• 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

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

​

API Endpoints for Statistics

​

Agent Statistics Endpoint

GET /agents/{agent_id}/stats/agent

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

{
  "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

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

{
  "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

• 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)

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

​

Live Status Updates

• 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

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

​

Keep-Alive Thresholds

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

• 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

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

​

Event Categories

• 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

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

​

Resource Usage

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

​

Health Checks

​

Agent Health Indicators

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

• 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

• Agent transitions to “Disconnected” status
• Agents remaining in “Never Connected” state
• Synchronization failures
• Keep-alive timeout events

​

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

• 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

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

​

Troubleshooting with Monitoring Data

​

Connectivity Issues

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

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

​

Performance Issues

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

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

​

Synchronization Issues

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

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
• Agent Deployment
• Agent Configuration
• System Inventory