Agent Configuration

Overview

Monitoring agents run on every managed node and are responsible for collecting host-level metrics, forwarding logs, and reporting health status to the Monitoring platform. Agents are deployed automatically when a node is registered in the deployment console, or manually for nodes outside the deployment console management.

Administrator Access Required — This operation requires the admin role. Contact your Polystack administrator if you do not have sufficient permissions.

Prerequisites

Administrator credentials with the admin role
Access to the deployment console (the Polystack Dashboard) for node management
SSH access to target nodes for manual agent installation

Deploy via the deployment console

Register the node

Navigate to the deployment console → Infrastructure → Nodes → Add Node. Provide the node IP, hostname, and role. The deployment console installs and configures the Monitoring agent as part of the node onboarding process.

Verify agent registration

Navigate to Monitor Center > Monitoring (Agents, admin view). The new node appears with status Active within 2–3 minutes of registration.

Check agent status via CLI

monitoring agent list --status all

Agent shows ACTIVE and last-seen timestamp is within the scrape interval.

Configure custom scrape targets

If the node runs application-specific metric endpoints (e.g., a database exporter), add them as additional scrape targets:Navigate to Monitor Center > Monitoring (Add Scrape Target, admin view) and provide the endpoint URL and scrape interval.

Metric endpoints must be accessible from the Monitoring collector nodes. Ensure security group rules permit inbound connections on the target port from the collector IP range.

Manual Agent Installation

For nodes not managed by the deployment console, install and configure the agent manually.

Install the agent package

Install Monitoring agent

apt install monitoring-agent

Retrieve an agent token

Generate an agent authentication token from the Monitoring portal:

Create agent token

monitoring agent token create \
  --node <HOSTNAME> \
  --expires 365d

Store the token securely — it cannot be retrieved after the command completes.

Configure the agent

Edit /etc/monitoring/agent.yaml:

/etc/monitoring/agent.yaml

server:
  endpoint: https://monitoring.polystack.internal:9090
  auth_token: <AGENT_AUTH_TOKEN>

node:
  hostname: compute-node-04
  labels:
    role: compute
    az: zone-a

scrape_interval: 30s
log_paths:
  - /var/log/syslog
  - /var/log/nova/nova-compute.log

Start and enable the agent

Enable and start Monitoring agent

systemctl enable --now monitoring-agent

Verify agent is running

systemctl status monitoring-agent

Agent service is active (running) and registers with Monitoring within 30 seconds.

Managing Agent Tokens

Token Operations
Token Rotation

List all agent tokens

monitoring agent token list

Create a new token

monitoring agent token create --node compute-node-04 --expires 365d

Revoke a token (e.g., for decommissioned nodes)

monitoring agent token revoke <TOKEN_ID>

Rotate agent tokens periodically (recommended: every 365 days) or immediately if a node is decommissioned or suspected compromised.

Generate a new token

Create replacement token

monitoring agent token create --node compute-node-04 --expires 365d

Update agent configuration

Update /etc/monitoring/agent.yaml on the node with the new token, then restart:

Restart agent with new token

systemctl restart monitoring-agent

Revoke the old token

Revoke old token

monitoring agent token revoke <OLD_TOKEN_ID>

Old token is revoked and agent authenticates successfully with the new token.

Troubleshooting Agents

Symptom	Diagnostic	Resolution
Agent shows `offline`	`systemctl status monitoring-agent`	Restart service; check token validity
Agent not in list	`monitoring agent list --status all`	Verify token; re-register node
High scrape latency	`monitoring agent stats --node <HOST>`	Reduce scrape targets; scale up node resources
Authentication errors	Check `/var/log/monitoring/agent.log`	Rotate token; verify endpoint URL

Next Steps

Metric Endpoints

Add custom application scrape targets to agents

Log Collection

Configure which log files are forwarded by each agent

Security

Agent token management and dashboard access control

Troubleshooting

Diagnose agent connectivity and metric collection issues

Core Services

Other Services

Overview

Deploy via the deployment console

Register the node

Verify agent registration

Configure custom scrape targets

Manual Agent Installation

Install the agent package

Retrieve an agent token

Configure the agent

Start and enable the agent

Managing Agent Tokens

Generate a new token

Update agent configuration

Revoke the old token

Troubleshooting Agents

Next Steps

Metric Endpoints

Log Collection

Security

Troubleshooting

​Overview

​Deploy via the deployment console

Register the node

Verify agent registration

Configure custom scrape targets

​Manual Agent Installation

Install the agent package

Retrieve an agent token

Configure the agent

Start and enable the agent

​Managing Agent Tokens

Generate a new token

Update agent configuration

Revoke the old token

​Troubleshooting Agents

​Next Steps

Metric Endpoints

Log Collection

Security

Troubleshooting

Overview

Deploy via the deployment console

Manual Agent Installation

Managing Agent Tokens

Troubleshooting Agents

Next Steps