Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.polystack.tech/llms.txt

Use this file to discover all available pages before exploring further.

​
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

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>

​
Troubleshooting Agents

SymptomDiagnosticResolution
Agent shows offlinesystemctl status monitoring-agentRestart service; check token validity
Agent not in listmonitoring agent list --status allVerify token; re-register node
High scrape latencymonitoring agent stats --node <HOST>Reduce scrape targets; scale up node resources
Authentication errorsCheck /var/log/monitoring/agent.logRotate 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