Installing the host agent on Windows

The Instana agent can be installed as a Windows service.

Prerequisites

  • Ensure that .NET Framework 4.5 is installed before you install the host agent.
  • Ensure that a JVM is installed before you start the host agent. For more information, see the Supported JDKs section.
  • Ensure that the Instana host agent is run with Administrator privileges to avoid problems with getting monitoring data.

If you choose to install the host agent by using a Windows installer, the installer takes care of installing the prerequisites (.NET Framework 4.5 and a JVM).

Supported operating systems and platform architectures

Instana is supported on the following operating systems and platform architectures:

  • Windows Server 2022
  • Windows Server 2019
  • Windows Server 2016
  • Windows Server 2012 R2
  • Windows Server 2012 [1]
  • Windows Server 2008 R2 [1:1]
  • Windows 11
  • Windows 10
  • Windows 8.1
  • Windows 8 [1:2]
  • Windows 7 [1:3]
  • Windows Vista [1:4]

These operating systems are supported on the x64 or amd64 platform architecture.

Supported JDKs

The host agent requires a Java 8 or Java 11 runtime. You are recommended to use a JDK from the same vendor as the monitored JVMs on the same host.

The following JDKs are supported for running the host agent:

Ensure that the JVM can be used by any user on the system. You are recommended to use the latest available patch release of the Java distribution of your choice. The host agent requires a JDK that supports TLSv1.3 (available in all current JDK 8 and JDK 11 builds). If you use a JDK package that does not support strong encryption, you might get errors like "java.lang.RuntimeException: Could not generate DH key pair".

Installing the JDK

To start the host agent, your Windows host computer must have a supported JDK. Use one of the following options to install the JDK:

  • After installing the host agent, place the JDK in the <instana-agent-install-dir>/jvm directory directly, and verify that the <instana-agent-install-dir>/jvm/bin/java.exe file exists.
  • Install the JDK in a directory of your choice, and set its path to the environment variable JAVA_HOME. After installing the host agent, you can also set the JAVA_HOME environment variable by using the instana-agent-install-dir>/bin/setenv.bat file.

Installing the host agent by using a Windows installer interactively

To install the host agent by using a Windows installer interactively, which helps you install the host agent, complete the following steps:

  1. Sign in to the Instana UI, and then select an option to display the agent catalog; for example, on the home page, click Deploy Agent.

    If you are starting a new trial instance of Instana, the agent catalog is displayed with a prompt to select a host agent to install.

  2. Click the tile Windows - Windows Installer 64 bit

    If you want to run the installation process silently without any interaction, select the Windows - Windows Installer 64 bit (unattended) option, and follow the steps in the section Installing the host agent without interaction.

  3. Select the packaging option for either a dynamic or static host agent, and the runtime option for your choice of JDK.

  4. Click the download link to save the Windows installer file. Take note of the configuration values that you need to input to the installer when you run it in the next step.

  5. Run the Windows installer on the Windows host computer where you want to install the host agent. A GUI guides you through the process of installing the agent and takes care of installing the prerequisites (.NET Framework 4.5 and a JVM).

    The installer also registers the agent as a service, sets the service to start automatically, and starts the service after the installation.

Installing the host agent without interaction

If you prefer to install the host agent without interaction, you can run the Windows installer silently as follows:

  1. Sign in to the Instana UI, and then select an option to display the agent catalog; for example, on the home page, click Deploy Agent.

    If you are starting a new trial instance of Instana, the agent catalog is displayed with a prompt to select a host agent to install.

  2. Click the tile Windows - Windows Installer 64 bit (unattended)

  3. Download the Windows installer by using the link provided.

  4. Copy the installation command extract, which looks like the following example:

    @ECHO OFF

AgentBootstrap.exe INSTANA_AGENT_ENDPOINT=<your_host> INSTANA_AGENT_ENDPOINT_PORT=<your_port> INSTANA_AGENT_KEY=<your_agent_key> INSTANA_DOWNLOAD_KEY=<your_agent_key> /quiet

    You must provide the /quiet switch to prevent the GUI from being shown, so you can run the installation process silently without any user interaction. All of the other required parameters are pre-populated in the agent deployment code.

  5. Run the installation command on the Windows host computer where you want to install the host agent. The installation process runs silently through the process of installing the agent and takes care of installing the prerequisites (.NET Framework 4.5 and a JVM).

    The installer also registers the agent as a service, sets the service to start automatically, and starts the service after the installation.

Checking the status of the host agent

After installing the host agent, you can check its status on the Agents dashboard in the Instana UI. To display the Agents dashboard, click More > Agents on the sidebar of the Instana UI.

Tip: To find an agent in a long list of host agents, you can use the search bar with windows or other search strings like the Windows hostname.

A newly installed Windows host agent on the Agents dashboard

For the status of the host agent as a Windows service, check your Windows services list for instana-agent-service.

If you want to uninstall the host agent, run the Windows installer on the Windows host computer where you installed the host agent, and then select the Uninstall option.

Installing the host agent by using a .zip file

You can install the host agent manually by downloading and extracting a host agent .zip file.

The downloaded .zip file contains the agent files, but does not contain a JVM needed to run the host agent. Ensure that a supported JVM is installed on the Windows host computer on which you want to install the host agent.

1. Downloading the .zip file

  1. Sign in to the Instana UI, and then select an option to display the agent catalog; for example, on the home page, click Deploy Agent.

    If you are starting a new trial instance of Instana, the agent catalog is displayed with a prompt to select a host agent to install.

  2. Click the tile Windows - Zip Archives.

  3. Select the packaging option for either a dynamic or static host agent.

  4. Review the prerequisites.

  5. Click the download link for either 32-bit or 64-bit Windows to save the .zip file.

  6. Extract the downloaded .zip file to a folder of your choice (<instana-agent-install-dir>) on your Windows host computer.

2. Starting the host agent

The host agent is preconfigured with your account settings.

To start the host agent, run the following command:

<instana-agent-install-dir>\bin\start.bat

3. Checking the status of the host agent

After installing the host agent, you can check its status on the Agents dashboard in the Instana UI. To display the Agents dashboard, click More > Agents on the sidebar of the Instana UI.

To find an agent in a long list of host agents, you can use the search bar with windows or other search strings like the Windows hostname.

To check the status of the host agent on your Windows host computer, run the following command:

<instana-agent-install-dir>\bin\status.bat

To stop the host agent, run the following command:

<instana-agent-install-dir>\bin\stop.bat

If you want to uninstall a host agent, stop the agent, and then delete the installation folders.

4. Optional: Installing the host agent as a Windows service

If you want to install the host agent as a Windows service, you are recommended to use Service Wrapper. For more information about Service Wrapper, see WinSW.

1. Downloading the Service Wrapper

Download the Service Wrapper file winsw-VERSION-bin.exe, put it in the Instana host agent folder (a folder of your choice, referred to as <instana-agent-install-dir>), and then rename it to instana-agent.exe.

2. Creating the Service Wrapper configuration file

To start the host agent, Windows calls this Service Wrapper by using the configuration file instana-agent.xml in the same directory as the instana-agent.exe file.

The configuration file instana-agent.xml must be in the host agent folder where you put the instana-agent.exe file.

You need to create a configuration file for the Service Wrapper as follows:

<service>
 <id>instana-agent</id>
 <name>Instana Agent</name>
 <description>Instana Agent</description>
 <!-- start -->
 <executable>"<instana-agent-install-dir>\bin\karaf.bat"</executable>
 <startargument>daemon</startargument>
 <!-- stop -->
 <stopexecutable>"<instana-agent-install-dir>\bin\karaf.bat"</stopexecutable>
 <stopargument>stop</stopargument>
 <stoptimeout>10sec</stoptimeout>
 <!-- logging -->
 <logpath><instana-agent-install-dir>\data\log</logpath>
 <log mode="roll-by-time">
   <pattern>yyyyMMdd</pattern>
 </log>
</service>

3. Installing the Wrapper as a service

To install the host agent as a Windows service, go to the host agent folder where you put the instana-agent.exe and instana-agent.xml files, and then run the following command:

instana-agent.exe install

Then, start the host agent Windows service by running the following command:

net start instana-agent-service

Troubleshooting agent deployment

If installing the agent is not successful at first, you can check log messages and troubleshooting tips. If this troubleshooting section does not answer the questions you have, contact the IBM Instana support team with information about your experience, so that we can help you and update our documentation accordingly.

For troubleshooting information that is general to all host agents, see Managing host agents / Troubleshooting.

  1. Instana support coincides with Microsoft Lifecycle Policy. Instana provides official support for End of Support (EOS) Windows versions only if an official Custom Support Agreement is available. ↩︎ ↩︎ ↩︎ ↩︎ ↩︎

  2. These agent runtimes are available as options for Windows installer packages to install the host agent. ↩︎ ↩︎