Managing Host Agents

All host agents reporting to Instana are displayed on the Agents View. This page gives a quick overview of all agents, their important properties and general health. Furthermore, each host agent has its own Agent Management View, which displays real-time information about important metrics and allows you to configure the agent in various ways.

Agent Management Dashboard

To view an Agent Management Dashboard, on any host dashboard click Open Agent Management.

agent management button

Furthermore, all Agent Management Dashboards can be reached through the Agents View.

The Agent Management Dashboard displays the agent configuration and current runtime metrics. In the management area on top configurations can be changed and operations, like a restart, executed. Further down runtime metrics, and the current agent log are shown.

agent dash

Change Agent Mode

The host agent mode is relevant for host-based licensing, and it is used to decide whether the agent counts as an Infrastructure or an APM agent. The host agent mode can be toggled using Change Agent Mode control.

In the Change Agent Mode dialog, the following options are provided:

  • APM, which maps to the APM host agent mode
  • Infrastructure, which maps to the INFRASTRUCTURE host agent mode
  • Disabled, which maps to the OFF host agent mode

Change Log Level

The log level defines the level of detail that the agent logs should contain.

In the Chang Agent Log Level dialog, the following options are provided:

  • INFO, normal level of details
  • DEGUB, extended details for trouble shooting
  • TRACE, most details for further problem analysis

Update Agent

This button manually triggers the agent auto update as described at Updates of Dynamic Host Agents.

Note: During the update the host agent cannot provide any data so expect a short gap.

Reset Agent

Resetting the agent is very similar to restarting the agent process, but the current process remains active. This means OS level watchdogs / service scripts will not see the process identifier (pid) changing.

Note: During the reset the host agent cannot provide any data so expect a short gap.

Reboot Agent

Rebooting the agent will stop the current agent process and create a new one. The process of the used start script will still be unchanged but OS level watchdogs / service scripts could see a changed process identifier (pid) depending on their watch target.

Note: During the reboot the host agent cannot provide any data so expect a short gap.

Sensor Information

To view the list of sensors and host agent components that are used by the agent, click Sensors Info.

Configuration Management

Git-based configuration management can be enabled and configured in the configuration management section. Details of this feature, and the used nomenclature are described on the Git-based configuration management page.

Note: To support Configuration Management at least agent-bootstrap version 1.2.11 is required.

Note: In order to have access to this feature, users need to have a role that has the Configuration of agents permission enabled. For more information about users, roles, and permissions, see our managing users docs.

Agent Health View permission

Initializing Configuration Management

If no configuration management is active it can be initialized with the Initialize button at the top of the Configuration Management section.

Initializing configuration management

The initialization dialog provides the settings:

  • Remote Name, name the git remote should be set to
  • Remote Branch, name of the branch to use for updates
  • Remote URI, URI of the git repository

Initialize & Restart will configure the agent according to the given settings and restart it to fetch the newest configuration.

Update Configuration Management

If configuration management is already active its details are displayed in the Configuration Management section. This includes information about the configured remote, like branch name und URI, and the currently used commit, like hash and commit message.

To update the configuration the Configuration Management dialog can be opened using the Update button at the top of the section.

Initializing configuration management

Similar to the initialization dialog the following settings can be changed:

  • Remote Name, name the git remote should be set to
  • Remote Branch, name of the branch to use for updates
  • Remote URI, URI of the git repository

Update & Restart will configure the agent according to the given settings and restart it to fetch the newest configuration.

Self Monitoring

Not only is the host agent monitoring other software running on the host, furthermore it does constant lightweight self-monitoring. Gathered metrics can be used to observe host agent performance and resource consumption:

agent metrics

Agents View

The Agents view, located in the main navigation bar under More > Agents, provides an overview of all host agents reporting to the Instana tenant unit.

Using the search bar on top of the page the view can be narrowed down to a subset of agents using Dynamic Focus Queries.

Agent Health View

Bulk Agent Management

Note: In order to have access to this feature, users need to have a role that has the Configuration of agents permission enabled. For more information about users, roles, and permissions, see our managing users docs.

Agent Health View permission

The Agents view allows for quick access to the following features:

  • Update All Agents: updates all reporting agents to the latest version.
  • Reset All Agents: resets all reporting agents.
  • Instana Agent Installation: Agent installation instructions for all supported platforms.

Host Agent Health Status

The host agent health monitoring table contains the following information:

  • Agent entity link (links to the agent management dashboard)
  • Agent version
  • Agent boot version
  • Origin of installation
  • Update Mode
  • Mode (Disabled, Infrastructure or APM)
  • Log level
  • JVM name and version
  • Reporting status

Reported Agents

As with most features in Instana, the host agent health monitoring view strongly depends on the current time configuration.

There are two important things to understand:

  1. The table presents all agents which reported within the current time window.
  2. The status (reporting / not reporting) is based on the selected time.

The following conceptual image will show how the reporting indicator behaves.

Agent Health View concept

In this example image, the time window was set, so that three agents are listed. The end of the selected time window was set somewhere around 6:20am. The agent table would now indicate Agent 1 as not reporting because it stopped reporting at 6:00am, so before 6:20am. The other two agent have reported at this time.

Debugging

Create a Host Agent Heap Dump

To create a heap dump of the host agent, run the following command:

TS=`date +%s` && /opt/instana/agent/jvm/bin/jmap -dump:file=/tmp/agent-dump-$TS.hprof `cat /opt/instana/agent/agent.pid` && gzip /tmp/agent-dump-$TS.hprof