ServicePilot Agents

What is a ServicePilot Agent?

ServicePilot Agents are designed to collect monitoring data from various sources and send this data to ServicePilot. ServicePilot Agents require minimal configuration. All they need is web access to ServicePilot and an API Key to secure the communication. All further configuration is done through the ServicePilot web interface.

ServicePilot SaaS Agents

ServicePilot Agents for On Premise ServicePilot

How many ServicePilot Agents should be installed?

To see if a ServicePilot Agent needs to be installed on the same server from which it will collect data, see the Local collect column in the Licenses - Agent details table in the ServicePilot web interface.

1. Using a user with administrative privileges, log in to ServicePilot
2. Click on Agents > Install an agent
3. Click on the Agent Details

ServicePilot Agent proxy for access to ServicePilot

Please contact our ServicePilot support if you want to setup a ServicePilot Agent proxy.

ServicePilot Agent collection capabilities

Different ServicePilot Agents have different collection capabilities. To see what the Enterprise Agents can do, take a look at the Agent Details web pages:

1. Using a user with administrative privileges, log in to ServicePilot
2. Click on Agents > Install an agent
3. Click on the Agent Details

ServicePilot Enterprise Agents

These Enterprise Agents collect data from servers on which they are installed or from other devices. The Agents may also receive unsolicited event data if they are configured to do so.

The ServicePilot Windows Agent uses the Microsoft .NET framework.

The ServicePilot Linux Agent has been compiled for currently supported RedHat and Debian based x86 and x64 distributions as well as 32-bit and 64-bit Raspberry Pi OS on ARM.

ServicePilot Endpoint Agent

The ServicePilot Endpoint Agent is designed to collect hardware and software inventory from Windows workstations.

ServicePilot Developer Agents

Statistical data on the number and type of web calls made in Puppeteer, JavaScript in web browsers and Node.js applications may be collected. These integrations require instrumenting the code in question to send ServicePilot details of the calls.

Open Source Agent integration

The ServicePilot Windows Agent may act as a gateway to a number of Open Source Agents, so providing ServicePilot with the data collected by these agents.

ServicePilot Status Monitor

The ServicePilot Status Monitor is not an agent used to collect data, instead it is an extension of the ServicePilot web interface for ServicePilot users to see the current number of elements with alerts on the Windows desktop.

The ServicePilot Status Monitor can be downloaded from the User menu.

Download ServicePilot Agents

Obtaining a ServicePilot API Key

Installing a ServicePilot Windows Agent

After downloading the ServicePilot Agent, double-click on the file to run the installer. Set the parameters so that the ServicePilot Agent can communicate with ServicePilot.

Parameter	Description
API Key	A write authorized API Key as found in the list of API Keys listed above
Remote Command	Do not enable this parameter unless a monitored resource requires this ability. Package descriptions will indicate when this is required

Parameter	Description
Use proxy	If access to ServicePilot requires a web proxy then enable this option and complete the proxy address and port fields
Address	Specify the IP Address of the proxy
Port	Specify the port of the proxy
Username	Specify a username to allow proxy access, if required
Password	Specify a password to allow proxy access, if required
Use SP proxy	If access to ServicePilot requires a ServicePilot proxy then enable this option and complete the proxy URL field
URL	Specify the URL of an accessible ServicePilot proxy

Installing a ServicePilot Linux Agent

After downloading the ServicePilot Agent, make sure that the file is executable and become root to be able to run the self-extracting archive. At the end of the installation, the script will ask for an API Key. Set the parameters so that the ServicePilot Agent can communicate with ServicePilot. You may stop and start the spagent service using your Linux distribution's standard commands.

For x86 the file is called servicepilotlinuxagent.run
For ARM the file is called servicepilotlinuxarmagent.run

# chmod +x servicepilotlinuxagent.run
# ./servicepilotlinuxagent.run

Creating directory _agent_files
Verifying archive integrity...  100%   All good.
Uncompressing ServicePilot Linux Agent Package  100%
spagent install script running
No configuration found, awaiting input
Enter API KEY

10000000-0000-0000-0000-000000000000

Use web proxy? [default: n]

n

Use ServicePilot proxy? [default: n]

n

Run in debug mode? [default: n]

n

Enter ServicePilot Agent Log Path [default: '/var/log/servicepilot/']

/var/log/servicepilot/

This is debian based distro
Removing spagent files
Removing dotnetcoreagent files
Reset spagent
Created symlink /etc/systemd/system/multi-user.target.wants/spagent.service → /etc/systemd/system/spagent.service.
spagent started

#

For a full list of command line parameters, run the installer with the -- --help option.

1. ServicePilot Linux Agent Help	./servicepilotlinuxagent.run -- --help

Installing a ServicePilot Linux Agent in Docker

The ServicePilot Linux Agent may be run in a Docker container.

The Docker container hostname will need to be unique so that it may be configured correctly.

Connecting a ServicePilot Agent container to the ServicePilot SaaS offering will require a SERVICEPILOT_API_KEY to be set. Proxy environement variables may also be added:

docker run --detach --hostname spagent1 -e SERVICEPILOT_API_KEY=10000000-0000-0000-0000-000000000000 servicepilot/agent:latest

For On Premise deployments SERVICEPILOT_API_KEY, SERVICEPILOT_IP, SERVICEPILOT_PORT and HTTPS environment variables are required. Proxy environment variables may also be added:

docker run --detach --hostname spagent1 -e SERVICEPILOT_API_KEY=00000000-0000-0000-0000-000000000000 -e SERVICEPILOT_IP=servicepilot.company.com -e SERVICEPILOT_PORT=443 -e HTTPS=1 servicepilot/agent:latest

Installing a ServicePilot Linux Agent in Kubernetes

The ServicePilot Linux Agent may be run in a Kubernetes Pod.

The Kubernetes Pod hostname will need to be unique so that it may be configured correctly.

Note: Running a ServicePilot Agent in a Kubernetes Pod will limit its abilities to remote polling and obtaining Kubernetes information.

Deploy a ServicePilot Agent DaemonSet to the Kubernetes cluster. Note the SERVICEPILOT_* environment variables that need to match your ServicePilot deployment. For ServicePilot SaaS SERVICEPILOT_IP should be data.servicepilot.com. For On Premise deployments SERVICEPILOT_API_KEY, SERVICEPILOT_IP, SERVICEPILOT_PORT and HTTPS environment variables are required.

# Create a namespace for ServicePilot components
apiVersion: v1
kind: Namespace
metadata:
  name: monitoring
  labels:
    app: servicepilot-agent
---
# To have ServicePilot retrieve metrics from Kubelets with authentication and
# authorization enabled (which is highly recommended and included in security
# benchmarks) the following flags must be set on the kubelet(s):
#
# --authentication-token-webhook
# --authorization-mode=Webhook
#
apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRole
metadata:
  name: servicepilot-stats-viewer
  labels:
    rbac.authorization.k8s.io/servicepilot-stats-viewer: "true"
rules:
  - apiGroups: [""]
    resources:
      - nodes
      - nodes/proxy
      - nodes/metrics
      - nodes/stats
      - services
      - endpoints
      - pods
      - ingresses
      - configmaps
      - persistentvolumes
    verbs: ["get", "list", "watch"]
  - apiGroups: ["extensions", "networking.k8s.io"]
    resources:
      - ingresses/status
      - ingresses
    verbs: ["get", "list", "watch"]
  - apiGroups: ["metrics.k8s.io"]
    resources: 
      - pods
    verbs: ["get", "list", "watch"]
  - nonResourceURLs:
      - "/metrics"
    verbs: ["get"]
---
apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRole
metadata:
  name: servicepilot
  labels:
    app: servicepilot-agent
aggregationRule:
  clusterRoleSelectors:
    - matchLabels:
        rbac.authorization.k8s.io/servicepilot-stats-viewer: "true"
    - matchLabels:
        rbac.authorization.k8s.io/aggregate-to-view: "true"
rules: [] # Rules are automatically filled in by the controller manager.
---
apiVersion: v1
kind: ServiceAccount
metadata:
  name: servicepilot
  labels:
    app: servicepilot-agent
  namespace: monitoring
---
apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRoleBinding
metadata:
  name: servicepilot
  labels:
    app: servicepilot-agent
subjects:
  - kind: ServiceAccount
    name: servicepilot
    namespace: monitoring
roleRef:
  apiGroup: rbac.authorization.k8s.io
  kind: ClusterRole
  name: servicepilot
---
# ServicePilot Agent deployment
apiVersion: apps/v1
kind: DaemonSet
metadata:
  name: servicepilot-agent
  namespace: monitoring
  labels:
    app: servicepilot-agent
spec:
  selector:
    matchLabels:
      app: servicepilot-agent
  template:
    metadata:
      labels:
        app: servicepilot-agent
    spec:
      tolerations:
      # this toleration is to have the daemonset runnable on master nodes
      # remove it if your masters can't run pods
      - key: node-role.kubernetes.io/control-plane
        operator: Exists
        effect: NoSchedule
      - key: node-role.kubernetes.io/master
        operator: Exists
        effect: NoSchedule
      serviceAccountName: servicepilot
      containers:
        - name: servicepilot
          image: servicepilot/agent
          env:
          - name: SERVICEPILOT_API_KEY
            value: "10000000-0000-0000-0000-000000000000"
          - name: SERVICEPILOT_IP
            value: "data.servicepilot.com"
          - name: SERVICEPILOT_PORT
            value: "443"
          - name: HTTPS
            value: "1"
          - name: NODE_NAME
            valueFrom:
              fieldRef:
                fieldPath: spec.nodeName
          - name: NODE_IP
            valueFrom:
              fieldRef:
                fieldPath: status.hostIP
          - name: HOSTNAME
            value: $(NODE_NAME)

Check that a ServicePilot Agent is working

To make sure that the ServicePilot Agents are communicating correctly with ServicePilot, open the Agents web page:

1. Using a user with administrative privileges, log in to ServicePilot
2. Open SETUP > Agents
3. The Agent should appear in the list with either a yellow or green status and a Last seen value within a few seconds. A yellow status indicates that the Agent has yet to be given anything to do.

Set the Default agent

When provisioning resources at least one ServicePilot Agent can be set to indicate to perform that resource monitoring on the same machine as the resource or from remote Agents.

If the Agent fields are left blank then the Default agent will be used to monitor the resource.

To change the ServicePilot Default agent:

1. Using a user with administrative privileges, log in to ServicePilot
2. Open SETUP > Agents
3. Click on the edit icon for the Default agent field
4. Select the new Default agent
5. Click OK

Set a Backup agent

Optionally, a Backup agent can be set that will take over the monitoring responsibilities of the Default agent after a new minutes if the Default agent looses connectivity with the ServicePilot Manager. The Backup agent needs to be in a position to access all of the same resources as the Default agent and be installed on the same OS type as the Default agent.

To change the ServicePilot Backup agent:

1. Using a user with administrative privileges, log in to ServicePilot
2. Open SETUP > Agents
3. Click on the edit icon for the Backup agent field
4. Select the new Default agent
5. Click OK

The Backup agent cannot be set to the same value as the Default agent.

ServicePilot Agent logs

ServicePilot Agent logs may indicate connectivity errors between the ServicePilot Agent and ServicePilot or they may indicate issues obtaining data from devices. These Agent logs are particularly interesting if monitoring does not appear to work between the Agent and remote devices due to bad access credentials.

Open the Agent logs with a text editor:

Windows Agent logs

C:\Program Files (x86)\ServicePilot\ServicePilot ISM Enterprise\logs\ServicePilotAgent.log

Linux Agent logs

/var/log/servicepilot/servicepilotagent.log
/var/log/servicepilot/spgoagent.log

Uninstalling a ServicePilot Agent

If a ServicePilot Agent is no longer required, it can be uninstalled.

Check if an Agent is being used

1. Using a user with administrative privileges, log in to ServicePilot
2. Open SETUP > Agents
3. If an Agent is not used, the status is be yellow meaning that it is not configured. If the Agent is still being used, clicking on the blue magnifying glass will show the Agent details including the Agent data. This will list the resources that are currently using this Agent.

Uninstalling a ServicePilot Windows Agent

To uninstall a ServicePilot Windows Agent successfully, make sure that it is stopped before removing it.

1. Stop the ServicePilotAgent service
2. Stop the ServicePilot Setup Console if it is running
3. Uninstall the ServicePilot Agent from the Windows Programs and Features control panel
4. Optional: you may delete the C:\Program Files (x86)\ServicePilot directory if you do not want to keep the Agent logs
5. Optional: if you do not want to re-install a ServicePilot Agent then you may remove the HKEY_LOCAL_MACHINE\SOFTWARE\ServicePilot Technologies registry key

Uninstalling a ServicePilot Linux Agent

Make sure that the ServicePilot Linux Agent is not used before removing it.

1. Uninstall the ServicePilot Linux Agent	./servicepilotlinuxagent.run -- --uninstall

Remove uninstalled Agents from the Agent list

Until an Agent is uninstalled, removing it from the Agent list will not have the desired effect as the Agent will continue to communicate with ServicePilot and re-add itself to the Agent list.

1. Using a user with administrative privileges, log in to ServicePilot
2. Open SETUP > Agents
3. Click on the orange waste bin icon followed by the Delete button to remove an Agent from the Agent list