Installing the Agent on Windows

Installing with the Windows Installer

Instana provides an executable installer based on MSI. You can download it from your Management Portal and use it to install the agent and its dependencies on your Windows machines. You start the installation process by just double-clicking the icon. A GUI will take you through the process of installing the agent and take care of installing the pre-requisites. If you prefer your installation to happen without interaction, you can do so by passing parameters to the installer.

INSTANA_AGENT_ENDPOINT – Corresponds to the host your agent will connect to (see Agent Communication)

INSTANA_AGENT_ENDPOINT_PORT – The TCP port used for communication, normally 443 (https) (see Agent Communication)

INSTANA_AGENT_KEY – The agent key you can obtain from your Management Portal

In addition to these parameters, you can pass in the /quiet switch, which will prevent the GUI from coming up and thus run the installation-process silently without any user interaction. A typical command-line for running the agent installer silently looks like this:

AgentBootstrap.exe INSTANA_AGENT_ENDPOINT=[your-host] INSTANA_AGENT_ENDPOINT_PORT=[your-port] INSTANA_AGENT_KEY=[your-key] /quiet

Besides installing the agent itself, the installer will also take care of installing prerequisites (namely .NET Framework 4.5, VC++ runtime and a JVM). Furthermore the installer will register the agent as a service, set it to be started automatically, and start it right after installation.

If you prefer a manual approach to agent installation, please follow the steps below.

Manual Installation

Extract the contents of the archive for manual installation to a folder of your choice. This folder we be referred to as <instana-agent-install-dir> in this document.

Prerequisites

.net Framework 4.5 must be available.

Java 8 must be available.

A Java 8 Development Kit (JDK 8) needs to be available for the agent. There are two options:

  1. The easiest is to place that JDK into <instana-agent-install-dir>/jvm (so that <instana-agent-install-dir>/jvm/bin/java exists).

  2. The customizable way is to export an environment variable called JAVA_HOME to point to that JDK (this environment variable can be also set via instana-agent-install-dir>/bin/setenv.bat).

At the moment, the following JVMs are supported for running the agent:

It is important that the JVM is executable for any user on the system. We recommend using the latest available patch release of the Java distribution of your choice. Be advised that depending on your OS distribution, the packages provided by the OS distributor might not contain strong encryption support due to export control. Using such a package will result in errors like “java.lang.RuntimeException: Could not generate DH key pair.”

Agent Communication

The agent will download updates and sensors from the following host:

DNS Name: artifact-public.instana.io; Destination Port: tcp/80 and tcp/443.

We provide Instana in different regions at the geographically closest connection point for your agents, where the agent data is sent to:

  • Europe:

    • DNS Name: saas-eu-west-1.instana.io
    • Destination Port: tcp/443
  • United States:

    • DNS Name: saas-us-west-2.instana.io
    • Destination Port: tcp/443
  • Rest of the World:

    • DNS Name: saas-us-west-2.instana.io
    • Destination Port: tcp/443 Note: Even though the IP addresses are static, please use the DNS names wherever possible.

Agent Download

To install, simply download and extract the agent archive matching your system architecture.

You can access the portal for download just after logging in to Instana itself. Click on the profile picture in the top right corner to access the Management Portal. This will lead directly to the download section. Just select the appropriate operating system in the dropdown menu and download the agent. It is automatically preconfigured with your account settings so that you just have to extract and start the agent.

Agent Management

Starting the Agent

INSTANA_AGENT_FOLDER\bin\start.bat

Stopping the Agent

INSTANA_AGENT_FOLDER\bin\stop.bat

Status of the Agent

INSTANA_AGENT_FOLDER\bin\status.bat

As a Service

Installing the agent as a Windows service means that no manual start is necessary and that users are not required to be logged in.

Service Wrapper Download

A service wrapper is recommended for installation to be as easy as possible. Instana suggests using WinSW, which can be downloaded from https://github.com/kohsuke/winsw.

Please position the executable file, winsw-VERSION-bin.exe, in the Instana agent folder (a folder of your choice, referred to as <instana-agent-install-dir>) and name it instana-agent.exe. In order to start the agent, Windows will call this wrapper. Details can be found in the configuration file instana-agent.xml in the same directory.

Service Wrapper Configuration File

The following is an example config file for the service wrapper. It should be located in the Instana agent folder with the same name as the wrapper executable, except with the extension .xml (i.e instana-agent.xml).

<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>

Installing the Wrapper as a Service

Now that the wrapper has been configured and named, the .exe and .xml files with the same name can be run by simply running the following command in the Instana agent directory:

instana-agent.exe install

This installs the wrapper as a service. In order to start it, use:

net start instana-agent-service