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 nxtRadar platform. Agents are deployed automatically when a node is registered in nxtDeploy, or manually for nodes outside nxtDeploy management.

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

Prerequisites

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

Deploy via nxtDeploy

Register the node

Navigate to nxtDeploy → Infrastructure → Nodes → Add Node. Provide the node IP, hostname, and role. nxtDeploy installs and configures the nxtRadar 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

nxtradar 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 nxtRadar 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 nxtDeploy, install and configure the agent manually.

Install the agent package

Install nxtRadar agent

apt install nxtradar-agent

Retrieve an agent token

Generate an agent authentication token from the nxtRadar portal:

Create agent token

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

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

Configure the agent

Edit /etc/nxtradar/agent.yaml:

/etc/nxtradar/agent.yaml

server:
  endpoint: https://nxtradar.NxtSight.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 nxtRadar agent

systemctl enable --now nxtradar-agent

Verify agent is running

systemctl status nxtradar-agent

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

Managing Agent Tokens

Token Operations
Token Rotation

List all agent tokens

nxtradar agent token list

Create a new token

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

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

nxtradar 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

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

Update agent configuration

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

Restart agent with new token

systemctl restart nxtradar-agent

Revoke the old token

Revoke old token

nxtradar 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 nxtradar-agent`	Restart service; check token validity
Agent not in list	`nxtradar agent list --status all`	Verify token; re-register node
High scrape latency	`nxtradar agent stats --node <HOST>`	Reduce scrape targets; scale up node resources
Authentication errors	Check `/var/log/nxtradar/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

Agent Configuration

Overview

Deploy via nxtDeploy

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 nxtDeploy

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 nxtDeploy

Manual Agent Installation

Managing Agent Tokens

Troubleshooting Agents

Next Steps