Skip to main content

Deploying UniAgent

Prerequisites​

  • Administrator privileges on the server where UniAgent will be deployed, and firewall configuration to ensure communication between UniAgent and Collector.
  • Permission to restart all applications, and the user must not be changed during the restart.
  • The maximum estimated disk space required for the UniAgent directory is 10GB.
  • It is recommended that the host installing UniAgent has at least 1GB of available memory.
  • If an Agent is already installed before deploying UniAgent, uninstall the existing Agent before installing UniAgent.
  • UniAgent will monitor all Java, PHP, and .NET Core processes. Processes that should not be monitored must be manually added to the blacklist.
  • UniAgent has requirements for OS and Docker versions. For details, refer to the UniAgent Support List.
  • Do not install UniAgent from other vendors on the same machine simultaneously.

Network Policy (Example)​

⚠️ The following are example IP addresses. Please configure network policies according to the actual addresses in your project.

img

Source AddressTarget AddressTarget PortDescription
192.168.5.2 (collector)192.168.5.1 (dashboard)80Collector installation, uploading data to the platform
192.168.5.3 (agent)192.168.5.1 (dashboard)80Agent installation
192.168.5.3 (agent)192.168.5.2 (collector)7665,7666Backend application agent sends data to Collector. APM Collector uses 7665, Infra Collector use 7666
User192.168.5.1 (dashboard)80Platform dashboard access

Deploying on Linux​

Environment Confirmation​

⚠️ Confirm whether the server CPU is ARM64 or x86_64 architecture.

⚠️ Confirm network connectivity with the selected Collector.

Deployment Steps​

  1. Log in to the Guanyun AIOps platform, and in the left navigation bar, select Management -> Deployment Status -> UniAgents Management.

  2. In the UniAgents Management tab, click Add in the upper right corner, select the Linux agent type, and configure UniAgents parameters.

    • ⚠️ Select the OS CPU architecture: currently supports x86_64 and ARM64. Please select the architecture matching the target server.
    • Select UniAgent version: for private deployments, the UniAgent installation package must be uploaded in advance by a super admin before it can be displayed here.
    • ⚠️ Multiple NICs: If the server has multiple IPs, specify which IP to use for communication with the Collector. By default, the agent will automatically use the first available IP in the NIC list.
      • Example 1: If the server has both an external and internal IP, and no IP is specified, the agent may use the external IP, causing external network traffic. In this case, select the internal IP.
      • Example 2: If the server is a VM communicating with the Collector via NAT, the agent may obtain the internal IP, which Infra Collector cannot access. Specify the external IP and configure NAT mapping accordingly.
    • Business System: This parameter affects the business system name in Applications & Microservices. When an application uploads monitoring data for the first time, a business system with this name will be created and the application will be associated with it. If a business system with the same name already exists, new applications will be associated with the existing system.
    • Tag: This parameter affects the permission group of the agent server in Infrastructure. If the tag does not exist, create it in Infrastructure > Configuration > Tag Management.
    • Full Stack Data Collection: When enabled, UniAgent collects both infrastructure and application performance data. If disabled, only infrastructure data is collected.

  3. Select Agent Collector. If data is available in the Collector list, select it (multiple selection supported, but deployment environments must match). If not, or to add a new Collector, click Add Collector (see Collector Deployment).

  4. Download the UniAgent installation script using one of the following methods (Collector selection required):

    • Method 1: Click Generate Command to generate a command. Click copy and execute it on the target server.
    • Method 2: If the network is not accessible, click Download to download the installation script, then transfer it to the target server.

  5. Verify the installation script. After copying, execute the verification command on the target server. The script checks for completeness and will prompt if incomplete.

  6. Run the installation script:

    • ⚠️ It is recommended to use the root user to install UniAgent.
      • Installation command:
      sudo sh ./tingyun-agent-<version>.sh
      • Uninstall command:
      sudo /opt/tingyun-oneagent/uninstall.sh
    • ⚠️ If not using root, install as a non-root user:
      • Differences from root installation:
        • Does not support monitoring containerized applications
        • Does not support auto-start on boot
        • Does not support host monitoring
        • Only supports monitoring applications started by the agent user
        • Only supports Java, .NET Core, Python, and Node.js monitoring
      • Installation command:
      sh ./tingyun-agent-<version>.sh --none-privilege=true
      • Uninstall command:
      source ~/.tingyun/scripts/uninstall.sh

  7. Validation

    • For root installation:
      • Default installation directory: /opt/tingyun-oneagent
      • Check status:
      sudo systemctl status tingyun-oneagent
      sudo systemctl start tingyun-oneagent
      sudo systemctl stop tingyun-oneagent
      sudo systemctl restart tingyun-oneagent
      • Ensure /etc/ld.so.preload contains /lib64/libinterceptor.so.
      • By default, Nginx, Python, and Node.js monitoring are disabled. To enable, edit /opt/tingyun-oneagent/conf/interceptor.conf and set nginx_enabled, python_enabled, or nodejs_enabled to true.
    • For non-root installation:
      • Installation directory: ~/.tingyun, logs in ~/.tingyun/logs
      • The script will attempt to auto-configure environment variables. If .bashrc or .bash_profile exists, it will append source ~/.tingyun/scripts/start.sh.
      • By default, Python and Node.js monitoring are disabled. To enable, edit ~/.tingyun/conf/interceptor.conf and set python_enabled or nodejs_enabled to true.

  8. Restart the processes to be monitored.

    • For root installation, restart the target processes or containers to inject the agent.
    • For non-root installation, add the following to the application startup script and restart: 
      source ~/.tingyun/scripts/start.sh
      export TINGYUN_APP_NAME=your_app_name

  9. View deployment status and application information.

    • For root installation, click View Deployment Status at the bottom of the Add UniAgent Deployment page to see the server and process information. If data is present, deployment is successful. In the left navigation, go to Infrastructure > Host Monitoring to see the new host, and Applications & Microservices > Business System to see the new application.
    • For non-root installation, go to Applications & Microservices > Business System to see the new application.

Deploying on Windows​

Environment Confirmation​

⚠️ Confirm OS version: Windows 7 SP1 / Windows Server 2008 R2 and below are not supported. For these, install patch KB3033929 and reboot before installing.

⚠️ Confirm network connectivity with the selected Collector.

⚠️ Security software may block some components during installation. Temporarily disable or whitelist security software during installation.

Deployment Steps​

  1. Log in to the Guanyun AIOps platform, and in the left navigation bar, select Management -> Deployment Status -> UniAgents Management.
  2. In the UniAgents Management tab, click Add in the upper right corner, select the Windows agent type, and configure UniAgents parameters.
    • Select UniAgent version: for private deployments, the UniAgent installation package must be uploaded in advance by a super admin before it can be displayed here.
    • ⚠️ Multiple NICs: If the server has multiple IPs, specify which IP to use for communication with the Collector. By default, the agent will automatically use the first available IP in the NIC list.
    • Business System: This parameter affects the business system name in Applications & Microservices. When an application uploads monitoring data for the first time, a business system with this name will be created and the application will be associated with it. If a business system with the same name already exists, new applications will be associated with the existing system.
    • Tag: This parameter affects the permission group of the agent server in Infrastructure. If the tag does not exist, create it in Infrastructure > Configuration > Tag Management.
    • Full Stack Data Collection: When enabled, UniAgent collects both infrastructure and application performance data. If disabled, only infrastructure data is collected.
  3. Select Agent Collector. If data is available in the Collector list, select it (multiple selection supported, but deployment environments must match). If not, or to add a new Collector, click Add Collector (see Collector Deployment).
  4. Click the blue Download button to download the UniAgent installation package (Collector selection required).
  5. Extract and install on the target server.
    • ⚠️ Always extract to a directory before running the installer. Do not run the installer directly from the archive.
    • After extraction, run tingyun-monitor-xxx.exe as administrator.
    • For silent installation, copy the package to the target machine and run the following PowerShell script as administrator:
    Expand-Archive -Force -LiteralPath <package_path>\tingyunagent-windows-<version>.zip -DestinationPath <extract_path>
    <extract_path>\windows_oneagent\tingyun-monitor-<version>.exe /S
    • /S means silent installation.
  6. After deployment, check the UniAgent running status.
    • ⚠️ During installation, drivers and components must be installed. Security software may block some components, causing installation failure. Temporarily disable or whitelist security software during installation.
    • Run C:\Program Files\tingyun\monitor\bin\manager.exe to check the result.
  7. Immediately restart the business application for validation.
    • ⚠️ Due to various permission and antivirus settings on Windows, dependencies may not be fully effective after deployment, causing issues. Always restart the business application to validate agent effectiveness.
    • ⚠️ For IIS deployments, IIS processes may be recycled after a certain number of requests or time, loading an unvalidated agent. To avoid this, after deployment and status confirmation, immediately restart the IIS application to validate the agent.