Agent Installation

ApicaAgent Client The Apica Monitoring Agent is a service that collects performance metrics at regular intervals, the . The collected data is sent to a controller server which stores the data in a database administered by Apica. Examples of metrics collected by the agent could be include CPU usage, memory usage, network, and disk utilization. The PMA agent communicates with its controller via TCP or HTTP. Utilize the following table to determine which hostname:port combination to whitelist in order to connect the agent to the controller server.

Windows Performance Agent (PMA)

The client for Windows uses Windows Performance Objects to gather system statistics. The installation package is an MSI package that places the necessary files in a target location on the local system.

Windows Agent Downloads

Apica Agent Setup

PMA Windows .NET 3.5

PMA Windows .NET 4.5

PMA Windows v.1.1

Installation

• Run ApicaAgentSetup.msi

...

• Follow the installation instructions on the screen

• Open config.xml in the installation directory and enter your agent ticket. This will be provided to you by the Apica team.

...

• Start the agent by starting the ApicaAgent service.

• Stop the agent by stopping the ApicaAgent service.

Windows Client

The client for Windows uses Windows Performance Objects to gather system statistics. The installation package is an MSI package that places the necessary files in a target location on the local system.

[Coming Soon (ApicaAgentSetup_external.msi)]

Installation

• Run ApicaAgentSetup.msi

...

• Follow the installation instructions on the screen

• Open config.xml in the installation directory and enter your agent ticket. This will be provided to you by the Apica team.

...

• Start the agent by starting the ApicaAgent service.

...

• Stop the agent by stopping the ApicaAgent service.

Configuration

...

Configure performance counters

The pmcConfig file describes the performance counters that will be collected by the agent.

In this example we instruct the agent to collect the performance counter % Processor Time in performance object Processor, and we want to collect statistics for all processors so we set the instance to _Total.

<performanceCounter>
  <pmc name="cid">1</pmc>
  <pmc name="CategoryName">Processor</pmc>
  <pmc name="CounterName">% Processor Time</pmc>
  <pmc name="InstanceName">_Total</pmc>
</performanceCounter>

The easiest way to find additional Performance Counters is to open perfmon.exe on the local machine and add a new counter.

...

You will be presented with a list of Categories like Processor or Processor Information and within these categories, you will find different performance counters like % User Time or % Processor Time.

...

Once you have added the counter to perfmon, the selected counters will be displayed at the bottom of the window. The list of selected counters contains the information that needs to be supplied to the agent in the pmcConfig file.

...

Object = CategoryName, Counter = CounterName, Instance = InstanceName

You can find a complete list of pre-defined counters as well as instructions for creating your own counters in the following article: Apica PMA Counters Summary

You can find several templates which include sets of pre-defined counters tailored to different environments (SQL server, for example) in this article: Agent Templates

Troubleshooting Windows Agents

Troubleshooting the agent installation or operation can be done by referencing the error messages in logs.

Examples

Logs: The agent logs are sent to the application event log in windows.

...

Connectivity issues

If the agent is configured to use plain TCP it must be able to connect to ltagcontroller.apicasystem.com on TCP port 26300.

If the agent is configured to use HTTP is must be able to connect to ltagcontroller.apicasystem.com on TCP port 26301.

...

Misconfigured Performance Counters

The error message below occurs when the agent is unable to fetch a performance counter from the underlying operating system. Please check your pmcConfig file and correct any errors, also make sure that you are able to find all of the configured performance counters using perfmon.exe on the local machine.

...

Linux

Windows

Linux Agent

The client for Linux utilizes the libstatgrab library to collect system statistics. The installation package is a tar archive containing an installation script that places the necessary files in default locations on the local system.

⏬ Linux Agent Downloads

PMA Linux v.1.1

PMA Linux v1.2

PMA FreeBSD8 v1.0

Free BSDx64 10.1

PMA Controller

Default locations

The binary file is located at /usr/bin/apicaagent,

configuration files are stored in /etc/apica

and a startup script is placed in /etc/init.d/.

Installation

Before you install the agent make sure that the local machine is able to connect to ltagcontroller.apicasystem.com on TCP port 26300 or 26301.

• Extract the files from install_apicaagent.tar.gz.

...

• Enter the directory install_apicaagent and run install_apicaagent.sh

...

• Open /etc/apica/client.conf and enter your agent ticket.

...

• Start the agent by running /etc/init.d/apicaagent start

• Stop the agent by running /etc/init.d/apicaagent stop

Configuration

Linux Troubleshooting

Troubleshooting the agent installation or operation can be done by referencing the error messages in logs.

Examples

Logs: The agent logs are sent to the application event log in windows.

...

Connectivity issues

Connectivity issues: If the agent is configured to use plain TCP it must be able to connect to ltagcontroller.apicasystem.com on TCP port 26300. If the agent is configured to use HTTP is must be able to connect to ltagcontroller.apicasystem.com on TCP port 26301.

Note: If you are using an internal agent controller, please make sure that the agent is able to connect to the internal host name or IP address on either 26300 (TCP) or 26301 (HTTP).

...

Custom metrics

The Linux client supports custom metrics gathered from an external script. The script must send output to standard output in the following format (one JSON object per value):

^{{ `counter_id` : { `id` : counter_id, `timestamp` : unix_timestamp, `value` : sample_value }, `counter_id` : { `id` : counter_id, `timestamp` : unix_timestamp, `value` : sample_value } }}

In the configuration file you need to uncomment and edit the following settings (The example below uses a python script but you may use any kind of script that prints to stdout):

script_enabled = true

script = python path/to/your/python/script

Example: Established connections

^{#!/usr/bin/python import os import time cons = os.popen("netstat -nt | grep ESTABLISHED | wc -l").read(); print { "28" : { "id" : 28, "timestamp" : int(time.time()), "value" : int(cons.replace('\n',''))} };}

Example: Threads

^{#!/usr/bin/python import os import time threads = os.popen("ps -eLF | wc -l").read(); print { "42" : { "id" : 42, "timestamp" : int(time.time()), "value" : int(threads.replace('\n','')}

Misconfigured Performance Counters

The error message below occurs when the agent is unable to fetch a performance counter from the underlying operating system. Please check your pmcConfig file and correct any errors, also make sure that you are able to find all of the configured performance counters using perfmon.exe on the local machine.

...

Counters