Skip to main content

​
Overview

Monitoring agents run on every managed node and are responsible for collecting host-level metrics, forwarding logs, and reporting health status to the XIMP platform. Agents are deployed automatically when a node is registered in XDeploy, or manually for nodes outside XDeploy management.
Administrator Access Required — This operation requires the admin role. Contact your Xloud administrator if you do not have sufficient permissions.
Prerequisites
  • Administrator credentials with the admin role
  • Access to XDeploy (https://connect.<your-domain>) for node management
  • SSH access to target nodes for manual agent installation

​
Deploy via XDeploy

Register the node

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

Verify agent registration

Navigate to Monitoring → Administration → Agents. The new node appears with status Active within 2–3 minutes of registration.
Check agent status via CLI
ximp 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 Monitoring → Administration → Scrape Targets → Add Target and provide the endpoint URL and scrape interval.
Metric endpoints must be accessible from the XIMP 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 XDeploy, install and configure the agent manually.

Install the agent package

Install XIMP agent
apt install ximp-agent

Retrieve an agent token

Generate an agent authentication token from the XIMP portal:
Create agent token
ximp agent token create \
  --node <HOSTNAME> \
  --expires 365d
Store the token securely — it cannot be retrieved after the command completes.

Configure the agent

Edit /etc/ximp/agent.yaml:
/etc/ximp/agent.yaml
server:
  endpoint: https://ximp.xloud.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 XIMP agent
systemctl enable --now ximp-agent
Verify agent is running
systemctl status ximp-agent
Agent service is active (running) and registers with XIMP within 30 seconds.

​
Managing Agent Tokens

List all agent tokens
ximp agent token list
Create a new token
ximp agent token create --node compute-node-04 --expires 365d
Revoke a token (e.g., for decommissioned nodes)
ximp agent token revoke <TOKEN_ID>

​
Troubleshooting Agents

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