surveil/doc/source/tutorials/getting_started.rst

Getting started with Surveil

0. Prerequisite

Surveil's development environment is based on Docker and docker-compose.

First you need to install Docker. Refer to the project installation documentation.

You can install docker-compose with the following command:

sudo pip install -U docker-compose

1. Starting the containers

You will then be able to use the environment with the following commands:

• sudo docker-compose up: Launch Surveil and its dependencies in containers.
• sudo docker-compose down: Kill the active docker containers, if any.
• sudo docker-compose rm: Remove all containers, if any.
• sudo docker-compose build: Build the docker images.

Configuration for the different services running in the Docker containers are stored in tools/docker.

After running sudo docker-compose up, you should be able to acces all services at the ports configured in the docker-compose.yml file.

• Surveil API: http://localhost:5311/v1/hello
• Bansho (surveil web interface): http://localhost:8888 (any login info is fine)
• InfluxDB: http://localhost:8083 (user:root pw:root)
• Grafana: http://localhost:80 (user:admin pw:admin)
• Shinken WebUI: http://localhost:7767/all (user:admin pw:admin)

After about 40 seconds, a script will be executed to create fake hosts in the Surveil configuration. You should see it in the docker-compose logs.

The Surveil container mounts your local project folder and pecan reloads every time the project files change thus providing a proper development environment.

Note: Fedora users might want to uncomment the privileged: true line in docker.compose.yml if they face permissions issues.

2. Interacting with the API

You can use the python-surveilclient CLI to interact with the API.

Install it with the following command:

sudo pip install -U python-surveilclient

You'll need to provide the Surveil API URL. You can do this with the --surveil-api-url parameter, but its easier to just set it as environment variable:

export SURVEIL_API_URL=http://localhost:5311/v2
export SURVEIL_AUTH_URL=http://localhost:5311/v2/auth

Viewing host status

You can use the CLI to view the status of the currently monitored hosts and services with surveil status-host-list and surveil status-service-list

Example output: :

+-------------------------------+---------------+-------+------------+-----------------------------------+
| host_name                     | address       | state | last_check | plugin_output                     |
+-------------------------------+---------------+-------+------------+-----------------------------------+
| srv-ldap-01                   | 127.0.0.1     | UP    | 1431712968 | OK - 127.0.0.1: rta 0.036ms, l... |
| sw-iwebcore-01                | 127.0.0.1     | UP    | 1431712971 | OK - 127.0.0.1: rta 0.041ms, l... |
| os-controller-1.cloud.mtl.sfl | 145.50.1.61   | UP    | 1431713146 | OK - 172.20.1.21: rta 0.453ms,... |
| os-compute-1.cloud.mtl.sfl    | 145.50.1.62   | UP    | 1431713144 | OK - 172.20.1.31: rta 0.318ms,... |
| os-compute-2.cloud.mtl.sfl    | 145.50.1.63   | UP    | 1431713144 | OK - 172.20.1.32: rta 0.378ms,... |
| os-compute-3.cloud.mtl.sfl    | 145.50.1.64   | UP    | 1431713146 | OK - 172.20.1.33: rta 0.373ms,... |
| os-compute-4.cloud.mtl.sfl    | 145.50.1.65   | UP    | 1431713146 | OK - 172.20.1.34: rta 0.337ms,... |
+-------------------------------+---------------+-------+------------+-----------------------------------+

You can also use the CLI to view the configured hosts in the API with surveil config-host-list and surveil config-service-list

Adding a new host

The Surveil CLI provides function to add hosts:

surveil config-host-create --host_name openstackwebsite --address openstack.org

This will configure a new host in Surveil. However, it won't be monitored until Surveil's config is reloaded. You can do this with the CLI:

surveil config-reload

It will take from 5 to 10 seconds for Surveil to start monitoring the host. After this delay, you will be able to consult the host status with the CLI:

surveil status-host-list

Using Bansho the web interface

The Surveil client uses the Surveil API to query information concerning hosts and services. Bansho (Surveil's web interface) also uses this API. To use Bansho simply open a browser at http://localhost:8888 and press login.