Welcome to temBoard agent documentation!

temBoard is a powerful management tool for PostgreSQL.

temBoard agent is a Python service designed to run along PostgreSQL, exposing a REST API to implement various management tasks on PostgreSQL instance. See http://temboard.io/ for the big picture.

Features

  • Non intrusive daemon dedicated to one PostgreSQL cluster.
  • No extra dependencies.
  • Written python2.7 and python3, supported by stable distribution releases.
  • Secured REST API with SSL and credentials.
  • Extensible with plugins.

Table of Contents

Installation

This page document a quick way of installing the agent. For production system, you may want to use trusted certificate and other enhancement.

Prerequisites

In order to run temBoard agent, you require:

  • PostgreSQL 9.4+, listening on UNIX socket, on the same host. Check with sudo -u postgres psql.
  • openssl.
  • Python 2.6+ or 3.5+. Check with python --version.
  • A running temBoard UI.
  • bash and sudo for setup script.

Now choose the method matching best your target environment.

Debian

temBoard debs are published on Dalibo Labs APT repository. temBoard agent supports Debian stretch, jessie and wheezy. Start by enabling Dalibo Labs APT repository.

# echo deb http://apt.dalibo.org/labs $(lsb_release -cs)-dalibo main > /etc/apt/sources.list.d/dalibo-labs.list
# curl https://apt.dalibo.org/labs/debian-dalibo.asc | apt-key add -
# apt update -y  # You may use apt-get here.

You can install now temBoard agent with:

# apt install temboard-agent
# temboard-agent --version

RHEL / CentOS

temBoard RPM are published on Dalibo Labs YUM repository. temBoard agent supports RHEL / CentOS 6 and 7. Start by enabling Dalibo Labs YUM repository.

$ sudo yum install -y https://yum.dalibo.org/labs/dalibo-labs-2-1.noarch.rpm
$ sudo yum makecache fast

Warning

Do NOT use temBoard agent rpm from PGDG. They are known to be broken.

With the YUM repository configured, you can install temBoard agent with:

$ sudo yum install temboard-agent
$ temboard-agent --version

PyPI

temBoard agent wheel and source tarball are published on PyPI.

Installing from PyPI requires Python2.6+, pip and wheel. It’s better to have a recent version of pip. For Python 2.6, you will need some backports libraries.

$ sudo pip install temboard-agent
$ sudo pip2.6 install logutils argparse  # Only for Python 2.6
$ temboard-agent --version

Note where is installed temBoard agent and determine the prefix. You must find a share/temboard-agent folder in e.g /usr or /usr/local. If temBoard agent is installed in /usr/local, please adapt the documentation to match this system prefix.

Setup one instance

To finish the installation, you will need to follow the next steps for each Postgres instance on the host:

  • configure the agent;
  • add a first user;
  • start the agent;
  • finally register it in the UI.

The quickest way to setup temBoard agent is to use the auto_configure.sh script, installed in /usr/share/temboard-agent.

You must run this script as root, with PG* env vars set to connect to the Postgres cluster you want to manage. By default, the script uses postgres UNIX user to connect to Postgres cluster. The script receives the temBoard UI URL as single required argument.

Note

Each agent is identified by the fully qualified hostname. If hostname --fqdn can’t resolve the FQDN of your HOST, simply overwrite it using TEMBOARD_HOSTNAME envvar. Remember that localhost or even a short hostname is not enough. auto_configure.sh enforces this.

# /usr/share/temboard-agent/auto_configure.sh https://temboard-ui.lan:8888

The script shows you some important information for the next steps:

  • the path to the main configuration file like /etc/temboard-agent/11/main/temboard-agent.conf.
  • TCP port like 2345.
  • secret key for registration like d52cb5d39d265f03ae570e1847b90e10.

You will need these information later. Keep them near. Now add a first user using temboard-agent-adduser:

# sudo -u postgres temboard-agent-adduser -c /etc/temboard-agent/11/main/temboard-agent.conf

Adapt the configuration file to match the one created by auto_configure.sh. Later, once the agent is registered, you will need to authenticate against the agent with this user, right from the UI.

Now start the agent using the command suggested by auto_configure.sh. On most systems now, it’s a systemd service:

# systemctl start temboard-agent@11-main

Now you can register the agent in the UI using temboard-agent-register:

# sudo -u postgres temboard-agent-register -c /etc/temboard-agent/11/main/temboard-agent.conf --host $(hostname --fqdn) --port 2345 --groups default https://temboard-ui.lan:8888

Don’t forget to adapt this command line to your case. Configuration file, port and temBoard UI address are likely to change from one installation to another. temboard-agent-register will ask you to login to the UI. Beware, it is NOT the user on the agent.

It’s up!

Congratulation! You can continue on the UI and see the agent appeared, and monitoring data being graphed.

You can repeat the above setup for each instance on the same host.

Upgrade (RHEL/CentOS)

1.2 to 2.0

Stop the agent:

sudo systemctl stop temboard-agent

Update the package:

sudo yum install python-setuptools
sudo yum install temboard-agent

Start the agent:

sudo systemctl start temboard-agent

1.1 to 1.2

Stop the agent:

sudo systemctl stop temboard-agent

Update the package:

sudo yum install temboard-agent

Start the agent:

sudo systemctl start temboard-agent

0.0.1 to 1.1

Stop the agent:

sudo systemctl stop temboard-agent

Update the package:

sudo yum install temboard-agent

Update configuration file /etc/temboard-agent/temboard-agent.conf:

  • supervision plugin name must be replaced by monitoring
  • settings plugin name must be replaced by pgconf
  • CA cert. file usage is not mandatory anymore, parameter ssl_ca_cert_file can be commented

Start the agent:

sudo systemctl start temboard-agent

Configuration

temBoard agent reads configuration from arguments, environment and file. Defaut configuration file is /etc/temboard-agent/temboard-agent.conf. You can change this with TEMBOARD_CONFIGFILE envvar or --configfile switch.

temBoard agent always searches for a directory whose name is built with the config file and the .d suffix. Thus the default config directory is /etc/temboard-agent/temboard-agent.conf.d. temBoard agent reads only files suffixed with .conf. temBoard agent reads files in POSIX sort order: uppercase precedes lowercase.

The configuration file is mandatory. The configuration directory is optional.

The configuration file is in INI-style format as implemented by Python stlib config parser. Configuration parameters are distributed under sections:

  • temboard: this is the main section grouping core parameters;
  • postgresql: parameters related to the PostgreSQL cluster that the agent is connected to;
  • logging: how and where to log;
  • dashboard: parameters of the plugin dashboard;
  • monitoring: plugin monitoring;
  • administration: plugin administration.

temboard section

  • port: port number that the agent will listen on to serve its HTTP API. Default: 2345;
  • address: IP v4 address that the agent will listen on. Default: 0.0.0.0 (all);
  • users: Path to the file containing the list of the users allowed to use the HTTP API. Default: /etc/temboard-agent/users;
  • plugins: Array of plugin (name) to load. Default: ["monitoring", "dashboard", "pgconf", "administration", "activity"];
  • ssl_cert_file: Path to SSL certificate file (.pem) for the embeded HTTPS process serving the API. Default: /etc/temboard-agent/temboard-agent_CHANGEME.pem;
  • ssl_key_file: Path to SSL private key file. Default: /etc/temboard-agent/temboard-agent_CHANGEME.key;
  • home: Path to agent home directory, it contains files used to store temporary data. When running multiple agents on the same host, each agent must have its own home directory. Default: /var/lib/temboard-agent/main.
  • hostname: Overrides real machine hostname. Must be a valid FQDN. Default: None;

postgresql section

  • host: Path to PostgreSQL unix socket. Default: /var/run/postgresql;
  • port: PostgreSQL port number. Default: 5432;
  • user: PostgreSQL user. Must be a super-user. Default: postgres;
  • password: User password. Default: None;
  • dbname: Database name for the connection. Default: postgres;
  • instance: Cluster name. Default: main.
  • key: Authentication key used to send data to the UI. Default: None;

logging section

  • method: Method used to send the logs: stderr, syslog or file. Default: syslog;
  • facility: Syslog facility. Default: local0;
  • destination: Path to the log file. Default: /dev/log;
  • level: Log level, can be set to DEBUG, INFO, WARNING, ERROR or CRITICAL. Default: INFO.
  • debug: A comma separated list of loggers to which level will be set to DEBUG.

dashboard plugin

  • scheduler_interval: Time interval, in second, between each run of the process collecting data used to render the dashboard. Default: 2;
  • history_length: Number of record to keep. Default: 150.

monitoring plugin

  • dbnames: Database name list (comma separated) to supervise. * for all. Default: *;
  • collector_url: Collector URL. Default: None;
  • probes: List of probes to run (comma separated). * for all. Default: *;
  • scheduler_interval: Interval, in second, between each run of the process executing the probes. Default: 60;
  • ssl_ca_cert_file: File where to store collector’s SSL certificate. Default: None.

administration plugin

  • pg_ctl: External command used to start/stop PostgreSQL. Default: None.

Contributing

Reporting Issue & Submitting a Patch

We use dalibo/temboard-agent to track issue and review contribution. Fork the main repository and open a PR against master as usual.

Docker Development Environment

With Docker & Compose, you can run your code like this:

$ docker-compose up -d
$ docker-compose exec agent bash
# pip install -e /usr/local/src/temboard-agent/
# sudo -u postgres temboard-agent

Goto https://0.0.0.0:8888/ to add your instance with address agent, port 2345 and key key_for_agent_dev.

That’s it !

The make shell target is a shorthand to docker-compose exec agent bash if you prefer.

Editing Documentation

Sphinx generates temBoard agent documentation.

$ cd docs/
$ pip install -r requirements-doc.txt
$ make watch

Now run make serve in another terminal and point your web browser at http://0.0.0.0:8000/. There is no auto-refresh.

Releasing

Releasing a new version of temBoard agent requires write access to master on main repository, PyPI project and Docker Hub repository.

For the tooling, you need Git 1.8+, a recent setuptools with wheel, and twine. For debian packaging, see below.

Please follow these steps:

  • Checkout the release branch, e.g. v2.
  • Choose the next version according to PEP 440 .
  • Update temboardagent/version.py, without committing.
  • Generate commit and tag with make release.
  • Push Python egg to PyPI using make upload.
  • Build and push RPM packages using make -C packaging/rpm all push.
  • Build and push debian packages using make -C packaging/deb all push.
  • Trigger docker master build from https://hub.docker.com/r/dalibo/temboard-agent/~/settings/automated-builds/.

Other documentation for maintainers

Packaging for Debian GNU/Linux

The packaging/deb directory contains debian packaging of temBoard agent from released tarball on PyPI.

Building and uploading

The all target builds packages for every supported distributions while push targets run dput on the latest .changes. Once you have setup your host for building, just run:

make all push

You may be prompted for a passphrase to open your private key. The packages are stored in dist/ at the root of the project.

Setup

Package building requires Docker and Docker Compose for isolation. For signing, you need the devscripts package and a GPG private key. For uploading, you require dput.

sudo apt install devscripts dput

Ensure dput is configured to send to Dalibo Labs APT repository with the configuration named labs.

Now, export your full name and email address in DEBFULLNAME and DEBEMAIL env vars before building the packages. The maintainer field of the package is formatted as $DEBFULLNAME <$DEBEMAIL>.

debsign signs .changes with the GPG signature matching the maintainer field $DEBFULLNAME <$DEBEMAIL>.

Development

First, run docker container for interactive usage:

docker-compose run --rm stretch /bin/bash

If you get no output just after the run, type ENTER or CTRL+L to redraw.

Top srcdir is mounted as /workspace/ and dist/ is mounted as /dist/. Just call /workspace/packaging/deb/mkdeb.sh to build debian package.

Once you quit the shell, the container is destroyed.

Packaging for RHEL / CentOS

The packaging/deb directory contains debian packaging of temBoard agent from released tarball on PyPI or from a snapshot.

Building and uploading

The all target builds packages for every supported distributions and put them in upload directory. push target effectively upload RPMs to Dalibo Labs YUM repository. Once you have setup your host for building, just run:

make all push

The packages are stored in dist/rpm/ at the root of the project.

Building a snapshot

You can override the version to be built using VERSION env var. Ensure you have the corresponding source tarball in dist/ directory, otherwise, the script will try to download the sources from PyPI.

python setup.py sdist
VERSION=$(python setup.py --version) make -C packaging/rpm/ all push
Setup

Package building requires Docker and Docker Compose for isolation. For uploading, you need to have yum-labs project aside temboard-agent clone.

Development

The RPM spec file supports building a package for RHEL / CentOS version 6 and 7. To do so, it uses tests on the version, provided by the %{rhel} macro.

First, run docker container for interactive usage:

docker-compose run --rm centos7 /bin/bash

If you get no output just after the run, type ENTER or CTRL+L to redraw.

Top srcdir is mounted as /workspace/. Just call /workspace/packaging/rpm/build.sh to build the RPM package.

Once you quit the shell, the container is destroyed.

REST API Documentation

Core API

POST /login

User login

Request Headers:
 
Status Codes:

Example request:

POST /login HTTP/1.1
Content-Type: application/json

{
    "username": "alice",
    "password": "foo!!"
}

Example response:

HTTP/1.0 200 OK
Server: temboard-agent/0.0.1 Python/2.7.8
Date: Wed, 22 Apr 2015 12:19:48 GMT
Content-type: application/json

{"session": "fa452548403ac53f2158a65f5eb6db9723d2b07238dd83f5b6d9ca52ce817b63"}

Error responses:

HTTP/1.0 404 Not Found
Server: temboard-agent/0.0.1 Python/2.7.8
Date: Wed, 22 Apr 2015 12:20:33 GMT
Content-type: application/json

{"error": "Invalid username/password."}

HTTP/1.0 406 Not Acceptable
Server: temboard-agent/0.0.1 Python/2.7.8
Date: Wed, 22 Apr 2015 12:21:01 GMT
Content-type: application/json

{"error": "Parameter 'password' is malformed."}
GET /logout

User logout

Request Headers:
 
  • X-Session – Session ID
Status Codes:

Example request:

GET /logout HTTP/1.1
X-Session: 3b28ed94743e3ada57b217bbf9f36c6d1eb45e669a1ab693e8ca7ac3bd070b9e

Example response:

HTTP/1.0 200 OK
Server: temboard-agent/0.0.1 Python/2.7.8
Date: Wed, 22 Apr 2015 12:33:19 GMT
Content-type: application/json

{"logout": true}

Error responses:

HTTP/1.0 401 Unauthorized
Server: temboard-agent/0.0.1 Python/2.7.8
Date: Wed, 22 Apr 2015 12:36:33 GMT
Content-type: application/json

{"error": "Invalid session."}

HTTP/1.0 406 Not Acceptable
Server: temboard-agent/0.0.1 Python/2.7.8
Date: Wed, 22 Apr 2015 12:37:23 GMT
Content-type: application/json

{"error": "Parameter 'X-Session' is malformed."}
GET /discovery

Get global informations about the environment

Status Codes:

Example request:

GET /discover HTTP/1.1

Example response:

HTTP/1.0 200 OK
Server: temboard-agent/0.0.1 Python/2.7.8
Date: Wed, 22 Apr 2015 12:33:19 GMT
Content-type: application/json

{
    "hostname": "neptune",
    "pg_data": "/var/lib/postgresql/9.4/main",
    "pg_port": 5432,
    "plugins": ["monitoring", "dashboard", "pgconf", "administration", "activity"],
    "memory_size": 8241508352,
    "pg_version": "PostgreSQL 9.4.5 on x86_64-unknown-linux-gnu, compiled by gcc (Ubuntu 4.9.2-10ubuntu13) 4.9.2, 64-bit",
    "cpu": 4
}
GET /profile

Get current username

Request Headers:
 
  • X-Session – Session ID
Status Codes:

Example request:

GET /profile HTTP/1.1
X-Session: 3b28ed94743e3ada57b217bbf9f36c6d1eb45e669a1ab693e8ca7ac3bd070b9e

Example response:

HTTP/1.0 200 OK
Server: temboard-agent/0.0.1 Python/2.7.8
Date: Wed, 22 Apr 2015 12:33:19 GMT
Content-type: application/json

{
    "username": "alice"
}

Error responses:

HTTP/1.0 401 Unauthorized
Server: temboard-agent/0.0.1 Python/2.7.8
Date: Wed, 22 Apr 2015 12:36:33 GMT
Content-type: application/json

{"error": "Invalid session."}

HTTP/1.0 406 Not Acceptable
Server: temboard-agent/0.0.1 Python/2.7.8
Date: Wed, 22 Apr 2015 12:37:23 GMT
Content-type: application/json

{"error": "Parameter 'X-Session' is malformed."}
GET /notifications

Get all notifications from the agent.

Request Headers:
 
  • X-Session – Session ID
Status Codes:

Example request:

GET /notifications HTTP/1.1
X-Session: 3b28ed94743e3ada57b217bbf9f36c6d1eb45e669a1ab693e8ca7ac3bd070b9e

Example response:

HTTP/1.0 200 OK
Server: temboard-agent/0.0.1 Python/2.7.8
Date: Wed, 22 Apr 2015 12:33:19 GMT
Content-type: application/json

[
    {"date": "2016-04-11T16:12:38", "username": "alice", "message": "Login"},
    {"date": "2016-04-11T16:02:03", "username": "alice", "message": "Login"},
    {"date": "2016-04-11T15:51:15", "username": "alice", "message": "HBA file version '2016-04-11T15:32:53' removed."},
    {"date": "2016-04-11T15:51:10", "username": "alice", "message": "HBA file version '2016-04-11T15:47:26' removed."},
    {"date": "2016-04-11T15:51:04", "username": "alice", "message": "HBA file version '2016-04-11T15:48:50' removed."},
    {"date": "2016-04-11T15:50:57", "username": "alice", "message": "PostgreSQL reload"},
    {"date": "2016-04-11T15:50:57", "username": "alice", "message": "HBA file updated"},
    {"date": "2016-04-11T15:48:50", "username": "alice", "message": "PostgreSQL reload"}
]

Error responses:

HTTP/1.0 401 Unauthorized
Server: temboard-agent/0.0.1 Python/2.7.8
Date: Wed, 22 Apr 2015 12:36:33 GMT
Content-type: application/json

{"error": "Invalid session."}

HTTP/1.0 406 Not Acceptable
Server: temboard-agent/0.0.1 Python/2.7.8
Date: Wed, 22 Apr 2015 12:37:23 GMT
Content-type: application/json

{"error": "Parameter 'X-Session' is malformed."}
GET /status

Get informations about the agent

Status Codes:

Example request:

GET /status HTTP/1.1

Example response:

HTTP/1.0 200 OK
Server: temboard-agent/2.0+master Python/2.7.5
Date: Fri, 15 Jun 2018 13:42:57 GMT
Access-Control-Allow-Origin: *
Content-type: application/json

{
    "start_datetime": "2018-06-15T15:42:42",
    "version": "2.0+master",
    "user": "postgres",
    "reload_datetime": "2018-06-15T15:42:42",
    "pid": 32669,
    "configfile": "/etc/temboard-agent/temboard-agent.conf"
}

Administration plugin API

POST /administration/control

Control PostgreSQL server. Supported actions are start, stop, restart and reload.

Request Headers:
 
  • X-Session – Session ID
Status Codes:

Example request:

POST /administration/control HTTP/1.1
X-Session: 3b28ed94743e3ada57b217bbf9f36c6d1eb45e669a1ab693e8ca7ac3bd070b9e
Content-Type: application/json

{
    "action": "restart"
}

Example response:

HTTP/1.0 200 OK
Server: temboard-agent/0.0.1 Python/2.7.8
Date: Wed, 22 Apr 2015 09:57:52 GMT
Content-type: application/json

{
    "action": "restart",
    "state": "ok"
}

Error responses:

HTTP/1.0 401 Unauthorized
Server: temboard-agent/0.0.1 Python/2.7.8
Date: Wed, 22 Apr 2015 09:58:00 GMT
Content-type: application/json

{"error": "Invalid session."}

HTTP/1.0 406 Not Acceptable
Server: temboard-agent/0.0.1 Python/2.7.8
Date: Wed, 22 Apr 2015 09:58:00 GMT
Content-type: application/json

{"error": "Parameter 'action' is malformed."}

Activity plugin API

GET /activity

Get list of PostgreSQL backends.

Request Headers:
 
  • X-Session – Session ID
Status Codes:

Example request:

GET /activity HTTP/1.1
X-Session: 3b28ed94743e3ada57b217bbf9f36c6d1eb45e669a1ab693e8ca7ac3bd070b9e

Example response:

HTTP/1.0 200 OK
Server: temboard-agent/0.0.1 Python/2.7.8
Date: Wed, 22 Apr 2015 09:57:52 GMT
Access-Control-Allow-Origin: *
Content-type: application/json

{
    "rows":
    [
        {
            "pid": 6285,
            "database": "postgres",
            "user": "postgres",
            "client": null,
            "cpu": 0.0,
            "memory": 0.13,
            "read_s": "0.00B",
            "write_s": "0.00B",
            "iow": "N",
            "wait": "N",
            "duration": "1.900",
            "state": "idle",
            "query": "SELECT 1;"
        }
    ]
}

Error responses:

HTTP/1.0 401 Unauthorized
Server: temboard-agent/0.0.1 Python/2.7.8
Date: Wed, 22 Apr 2015 09:58:00 GMT
Content-type: application/json

{"error": "Invalid session."}

HTTP/1.0 406 Not Acceptable
Server: temboard-agent/0.0.1 Python/2.7.8
Date: Wed, 22 Apr 2015 09:58:00 GMT
Content-type: application/json

{"error": "Parameter 'X-Session' is malformed."}
GET /activity/waiting

Get list of PostgreSQL backends waiting for lock acquisition.

Request Headers:
 
  • X-Session – Session ID
Status Codes:

Example request:

GET /activity/waiting HTTP/1.1
X-Session: 3b28ed94743e3ada57b217bbf9f36c6d1eb45e669a1ab693e8ca7ac3bd070b9e

Example response:

HTTP/1.0 200 OK
Server: temboard-agent/0.0.1 Python/2.7.8
Date: Wed, 22 Apr 2015 09:57:52 GMT
Access-Control-Allow-Origin: *
Content-type: application/json

{
    "rows":
    [
        {
            "pid": 13532,
            "database": "test",
            "user": "postgres",
            "cpu": 0.0,
            "memory": 0.16,
            "read_s": "0.00B",
            "write_s": "0.00B",
            "iow": "N",
            "relation": " ",
            "type": "transactionid",
            "mode": "ShareLock",
            "state": "active",
            "duration": 4.35,
            "query": "DELETE FROM t1 WHERE id = 1;"
        }
    ]
}
GET /activity/blocking

Get list of PostgreSQL backends blocking other backends due to lock acquisition.

Request Headers:
 
  • X-Session – Session ID
Status Codes:

Example request:

GET /activity/blocking HTTP/1.1
X-Session: 3b28ed94743e3ada57b217bbf9f36c6d1eb45e669a1ab693e8ca7ac3bd070b9e

Example response:

HTTP/1.0 200 OK
Server: temboard-agent/0.0.1 Python/2.7.8
Date: Wed, 22 Apr 2015 09:57:52 GMT
Access-Control-Allow-Origin: *
Content-type: application/json

{
    "rows":
    [
        {
            "pid": 13309,
            "database": "test",
            "user": "postgres",
            "cpu": 0.0,
            "memory": 0.2,
            "read_s": "0.00B",
            "write_s": "0.00B",
            "iow": "N",
            "relation": " ",
            "type": "transactionid",
            "mode": "ExclusiveLock",
            "state": "idle in transaction",
            "duration": 4126.98,
            "query": "UPDATE t1 SET id = 100000000 where id =1;"
        }
    ]
}
POST /activity/activity/kill

Terminate (kill) a list of PostgreSQL backends.

Request Headers:
 
  • X-Session – Session ID
Status Codes:

Example request:

POST /activity/kill HTTP/1.1
X-Session: 3b28ed94743e3ada57b217bbf9f36c6d1eb45e669a1ab693e8ca7ac3bd070b9e
Content-Type: application/json

{
    "pids":
    [
        13309
    ]
}

Example response:

HTTP/1.0 200 OK
Server: temboard-agent/0.0.1 Python/2.7.8
Date: Wed, 22 Apr 2015 09:57:52 GMT
Access-Control-Allow-Origin: *
Content-type: application/json

{
    "backends":
    [
        {"pid": 13309, "killed": true},
    ]
}

Dashboard plugin API

GET /dashboard

Get the whole last data set used to render dashboard view. Data have been collected async.

Request Headers:
 
  • X-Session – Session ID
Status Codes: 
GET /dashboard HTTP/1.1
X-Session: 3b28ed94743e3ada57b217bbf9f36c6d1eb45e669a1ab693e8ca7ac3bd070b9e

Example response:

HTTP/1.0 200 OK
Server: temboard-agent/0.0.1 Python/2.7.8
Date: Wed, 22 Apr 2015 09:57:52 GMT
Content-type: application/json

{
    "active_backends":
    {
        "nb": 1,
        "time": 1429617751.29224
    },
    "loadaverage": 0.28,
    "os_version": "Linux 3.16.0-34-generic x86_64",
    "pg_version": "9.4.1",
    "n_cpu": "4",
    "hitratio": 98.0,
    "databases":
    {
        "total_size": "1242 MB",
        "time": "14:02",
        "databases": 4,
        "total_commit": 16728291,
        "total_rollback": 873
    },
    "memory": {
        "total": 3950660,
        "active": 46.9,
        "cached": 20.2,
        "free": 32.9
    },
    "hostname": "neptune",
    "cpu":
    {
        "iowait": 0.0,
        "idle": 97.5,
        "steal": 0.0,
        "user": 2.5,
        "system": 0.0
    },
    "buffers":
    {
        "nb": 348247,
        "time": 1429617751.276508
    }
}

Error responses:

HTTP/1.0 401 Unauthorized
Server: temboard-agent/0.0.1 Python/2.7.8
Date: Wed, 22 Apr 2015 09:58:00 GMT
Content-type: application/json

{"error": "Invalid session."}

HTTP/1.0 406 Not Acceptable
Server: temboard-agent/0.0.1 Python/2.7.8
Date: Wed, 22 Apr 2015 09:58:00 GMT
Content-type: application/json

{"error": "Parameter 'X-Session' is malformed."}
GET /dashboard/config

Get the dashboard plugin config.

Request Headers:
 
  • X-Session – Session ID
Status Codes: 
GET /dashboard HTTP/1.1
X-Session: 3b28ed94743e3ada57b217bbf9f36c6d1eb45e669a1ab693e8ca7ac3bd070b9e

Example response:

HTTP/1.0 200 OK
Server: temboard-agent/0.0.1 Python/2.7.8
Date: Wed, 22 Apr 2015 09:57:52 GMT
Content-type: application/json

{
    "history_length": 150,
    "scheduler_interval": 2
}

Error responses:

HTTP/1.0 401 Unauthorized
Server: temboard-agent/0.0.1 Python/2.7.8
Date: Wed, 22 Apr 2015 09:58:00 GMT
Content-type: application/json

{"error": "Invalid session."}

HTTP/1.0 406 Not Acceptable
Server: temboard-agent/0.0.1 Python/2.7.8
Date: Wed, 22 Apr 2015 09:58:00 GMT
Content-type: application/json

{"error": "Parameter 'X-Session' is malformed."}
GET /dashboard/live

Synchronous version of /dashboard. Please refer to /dashboard API documentation for details.

GET /dashboard/history

Get the last n sets of dashboard data. n is defined by parameter history_length from the dashboard section of configuration file. Default value is 150.

Request Headers:
 
  • X-Session – Session ID
Status Codes: 
GET /dashboard/history HTTP/1.1
X-Session: 3b28ed94743e3ada57b217bbf9f36c6d1eb45e669a1ab693e8ca7ac3bd070b9e

Example response:

HTTP/1.0 200 OK
Server: temboard-agent/0.0.1 Python/2.7.12
Date: Thu, 20 Apr 2017 15:56:56 GMT
Access-Control-Allow-Origin: *
Content-type: application/json

[
    {
        "active_backends":
        {
            "nb": 1,
            "time": 1492703660.798522
        },
        "max_connections": 100,
        "databases":
        {
            "total_rollback": 1081,
            "total_size": "158 MB",
            "timestamp": 1492703660.913077,
            "time": "17:54",
            "total_commit": 2825374,
            "databases": 6
        },
        "hostname": "poseidon.home.priv",
        "pg_version": "PostgreSQL 9.5.5 on x86_64-pc-linux-gnu, compiled by x86_64-pc-linux-gnu-gcc (Gentoo 4.9.4 p1.0, pie-0.6.4) 4.9.4, 64-bit",
        "memory":
        {
            "active": 51.0,
            "cached": 29.5,
            "total": 8082124,
            "free": 19.5
        },
        "cpu":
        {
            "iowait": 0.0,
            "idle": 100.0,
            "steal": 0.0,
            "user": 0.0,
            "system": 0.0
        },
        "os_version": "Linux 4.9.6-gentoo-r1",
        "loadaverage": 0.18,
        "hitratio": 99.0,
        "pg_uptime": "01:50:31.573788",
        "pg_port": "5432",
        "n_cpu": 4,
        "pg_data": "/var/lib/postgresql/9.5/data",
        "buffers":
        {
            "nb": 27670,
            "time": 1492703660.784254
        }
    }
]
GET /dashboard/buffers

Get the number of buffers allocated by PostgreSQL background writer process.

Request Headers:
 
  • X-Session – Session ID
Status Codes: 
GET /dashboard/buffers HTTP/1.1
X-Session: 3b28ed94743e3ada57b217bbf9f36c6d1eb45e669a1ab693e8ca7ac3bd070b9e

Example response:

HTTP/1.0 200 OK
Server: temboard-agent/0.0.1 Python/2.7.12
Date: Thu, 20 Apr 2017 16:09:58 GMT
Access-Control-Allow-Origin: *
Content-type: application/json

{"buffers": {"nb": 27696, "time": 1492704598.784161}}
GET /dashboard/hitratio

Get PostgreSQL global cache hit ratio.

Request Headers:
 
  • X-Session – Session ID
Status Codes: 
GET /dashboard/hitratio HTTP/1.1
X-Session: 3b28ed94743e3ada57b217bbf9f36c6d1eb45e669a1ab693e8ca7ac3bd070b9e

Example response:

HTTP/1.0 200 OK
Server: temboard-agent/0.0.1 Python/2.7.12
Date: Thu, 20 Apr 2017 16:28:33 GMT
Access-Control-Allow-Origin: *
Content-type: application/json

{"hitratio": 99.0}
GET /dashboard/active_backends

Get the total number of active backends.

Request Headers:
 
  • X-Session – Session ID
Status Codes: 
GET /dashboard/active_backends HTTP/1.1
X-Session: 3b28ed94743e3ada57b217bbf9f36c6d1eb45e669a1ab693e8ca7ac3bd070b9e

Example response:

HTTP/1.0 200 OK
Server: temboard-agent/0.0.1 Python/2.7.12
Date: Thu, 20 Apr 2017 16:35:55 GMT
Access-Control-Allow-Origin: *
Content-type: application/json

{
    "active_backends":
    {
        "nb": 1,
        "time": 1492706155.986045
    }
}
GET /dashboard/cpu

Get CPU usage.

Request Headers:
 
  • X-Session – Session ID
Status Codes: 
GET /dashboard/cpu HTTP/1.1
X-Session: 3b28ed94743e3ada57b217bbf9f36c6d1eb45e669a1ab693e8ca7ac3bd070b9e

Example response:

HTTP/1.0 200 OK
Server: temboard-agent/0.0.1 Python/2.7.12
Date: Thu, 20 Apr 2017 16:40:46 GMT
Access-Control-Allow-Origin: *
Content-type: application/json

{
    "cpu":
    {
        "iowait": 0.0,
        "idle": 100.0,
        "steal": 0.0,
        "user": 0.0,
        "system": 0.0
    }
}
GET /dashboard/loadaverage

System loadaverage.

Request Headers:
 
  • X-Session – Session ID
Status Codes: 
GET /dashboard/loadaverage HTTP/1.1
X-Session: 3b28ed94743e3ada57b217bbf9f36c6d1eb45e669a1ab693e8ca7ac3bd070b9e

Example response:

HTTP/1.0 200 OK
Server: temboard-agent/0.0.1 Python/2.7.12
Date: Thu, 20 Apr 2017 16:44:04 GMT
Access-Control-Allow-Origin: *
Content-type: application/json

{
    "loadaverage": 0.06
}
GET /dashboard/memory

Memory usage.

Request Headers:
 
  • X-Session – Session ID
Status Codes: 
GET /dashboard/memory HTTP/1.1
X-Session: 3b28ed94743e3ada57b217bbf9f36c6d1eb45e669a1ab693e8ca7ac3bd070b9e

Example response:

HTTP/1.0 200 OK
Server: temboard-agent/0.0.1 Python/2.7.12
Date: Thu, 20 Apr 2017 16:46:39 GMT
Access-Control-Allow-Origin: *
Content-type: application/json

{
    "memory":
    {
        "active": 50.1,
        "cached": 29.5,
        "total": 8082124,
        "free": 20.4
    }
}
GET /dashboard/hostname

Machine hostname.

Request Headers:
 
  • X-Session – Session ID
Status Codes: 
GET /dashboard/hostname HTTP/1.1
X-Session: 3b28ed94743e3ada57b217bbf9f36c6d1eb45e669a1ab693e8ca7ac3bd070b9e

Example response:

HTTP/1.0 200 OK
Server: temboard-agent/0.0.1 Python/2.7.12
Date: Thu, 20 Apr 2017 16:48:49 GMT
Access-Control-Allow-Origin: *
Content-type: application/json

{
    "hostname": "poseidon.home.priv"
}
GET /dashboard/os_version

Operating system version.

Request Headers:
 
  • X-Session – Session ID
Status Codes: 
GET /dashboard/os_version HTTP/1.1
X-Session: 3b28ed94743e3ada57b217bbf9f36c6d1eb45e669a1ab693e8ca7ac3bd070b9e

Example response:

HTTP/1.0 200 OK
Server: temboard-agent/0.0.1 Python/2.7.12
Date: Thu, 20 Apr 2017 16:55:44 GMT
Access-Control-Allow-Origin: *
Content-type: application/json

{
    "os_version": "Linux 4.9.6-gentoo-r1"
}
GET /dashboard/pg_version

Get PostgreSQL server version.

Request Headers:
 
  • X-Session – Session ID
Status Codes: 
GET /dashboard/pg_version HTTP/1.1
X-Session: 3b28ed94743e3ada57b217bbf9f36c6d1eb45e669a1ab693e8ca7ac3bd070b9e

Example response:

HTTP/1.0 200 OK
Server: temboard-agent/0.0.1 Python/2.7.12
Date: Thu, 20 Apr 2017 16:59:26 GMT
Access-Control-Allow-Origin: *
Content-type: application/json

{
    "pg_version": "PostgreSQL 9.5.5 on x86_64-pc-linux-gnu, compiled by x86_64-pc-linux-gnu-gcc (Gentoo 4.9.4 p1.0, pie-0.6.4) 4.9.4, 64-bit"
}
GET /dashboard/n_cpu

Number of CPU.

Request Headers:
 
  • X-Session – Session ID
Status Codes: 
GET /dashboard/n_cpu HTTP/1.1
X-Session: 3b28ed94743e3ada57b217bbf9f36c6d1eb45e669a1ab693e8ca7ac3bd070b9e

Example response:

HTTP/1.0 200 OK
Server: temboard-agent/0.0.1 Python/2.7.12
Date: Thu, 20 Apr 2017 17:03:55 GMT
Access-Control-Allow-Origin: *
Content-type: application/json

{
    "n_cpu": 4
}
GET /dashboard/databases

PostgreSQL cluster size & number of databases.

Request Headers:
 
  • X-Session – Session ID
Status Codes: 
GET /dashboard/databases HTTP/1.1
X-Session: 3b28ed94743e3ada57b217bbf9f36c6d1eb45e669a1ab693e8ca7ac3bd070b9e

Example response:

HTTP/1.0 200 OK
Server: temboard-agent/0.0.1 Python/2.7.12
Date: Thu, 20 Apr 2017 17:08:59 GMT
Access-Control-Allow-Origin: *
Content-type: application/json

{
    "databases":
    {
        "total_rollback": 1087,
        "total_size": "159 MB",
        "timestamp": 1492708139.981268,
        "databases": 6,
        "total_commit": 2848707,
        "time": "19:08"
    }
}
GET /dashboard/info

Get a bunch of global informations about system and PostgreSQL.

Request Headers:
 
  • X-Session – Session ID
Status Codes: 
GET /dashboard/info HTTP/1.1
X-Session: 3b28ed94743e3ada57b217bbf9f36c6d1eb45e669a1ab693e8ca7ac3bd070b9e

Example response:

HTTP/1.0 200 OK
Server: temboard-agent/0.0.1 Python/2.7.12
Date: Thu, 20 Apr 2017 17:17:57 GMT
Access-Control-Allow-Origin: *
Content-type: application/json

{
    "hostname": "poseidon.home.priv",
    "os_version": "Linux 4.9.6-gentoo-r1",
    "pg_port": "5432",
    "pg_uptime": "03:14:08.029574",
    "pg_version": "PostgreSQL 9.5.5 on x86_64-pc-linux-gnu, compiled by x86_64-pc-linux-gnu-gcc (Gentoo 4.9.4 p1.0, pie-0.6.4) 4.9.4, 64-bit",
    "pg_data": "/var/lib/postgresql/9.5/data"
}
GET /dashboard/max_connections

Get the max_connections settings value.

Request Headers:
 
  • X-Session – Session ID
Status Codes: 
GET /dashboard/active_backends HTTP/1.1
X-Session: 3b28ed94743e3ada57b217bbf9f36c6d1eb45e669a1ab693e8ca7ac3bd070b9e

Example response:

HTTP/1.0 200 OK
Server: temboard-agent/0.0.1 Python/2.7.12
Date: Thu, 20 Apr 2017 16:35:55 GMT
Access-Control-Allow-Origin: *
Content-type: application/json

{
    "max_connections": 100
}

Monitoring plugin API

GET /monitoring/probe/sessions

Run sessions monitoring probe.

Request Headers:
 
  • X-Session – Session ID
Status Codes:

Example request:

GET /monitoring/probe/sessions HTTP/1.1
X-Session: 3b28ed94743e3ada57b217bbf9f36c6d1eb45e669a1ab693e8ca7ac3bd070b9e

Example response:

HTTP/1.0 200 OK
Server: temboard-agent/0.0.1 Python/2.7.12
Date: Fri, 21 Apr 2017 06:24:45 GMT
Access-Control-Allow-Origin: *
Content-type: application/json

{
    "sessions":
    [
        {
            "idle_in_xact": 0,
            "idle_in_xact_aborted": 0,
            "no_priv": 0,
            "idle": 0,
            "datetime": "2017-04-21 08:24:45.003511+02",
            "disabled": 0,
            "waiting": 0,
            "port": 5432,
            "active": 0,
            "dbname": "temboard_test",
            "fastpath": 0
        }
    ]
}

Error responses:

HTTP/1.0 401 Unauthorized
Server: temboard-agent/0.0.1 Python/2.7.8
Date: Wed, 22 Apr 2015 09:58:00 GMT
Content-type: application/json

{"error": "Invalid session."}

HTTP/1.0 406 Not Acceptable
Server: temboard-agent/0.0.1 Python/2.7.8
Date: Wed, 22 Apr 2015 09:58:00 GMT
Content-type: application/json

{"error": "Parameter 'X-Session' is malformed."}
GET /monitoring/probe/xacts

Run xacts monitoring probe.

Request Headers:
 
  • X-Session – Session ID
Status Codes:

Example request:

GET /monitoring/probe/xacts HTTP/1.1
X-Session: 3b28ed94743e3ada57b217bbf9f36c6d1eb45e669a1ab693e8ca7ac3bd070b9e

Example response:

HTTP/1.0 200 OK
Server: temboard-agent/0.0.1 Python/2.7.12
Date: Fri, 21 Apr 2017 06:24:45 GMT
Access-Control-Allow-Origin: *
Content-type: application/json

{
    "xacts":
    [
        {
            "port": 5432,
            "n_commit": 0,
            "n_rollback": 0,
            "dbname": "template1",
            "datetime": "2017-04-21 08:42:12.092111+02"
        }
    ]
}
GET /monitoring/probe/locks

Run locks monitoring probe.

Request Headers:
 
  • X-Session – Session ID
Status Codes:

Example request:

GET /monitoring/probe/locks HTTP/1.1
X-Session: 3b28ed94743e3ada57b217bbf9f36c6d1eb45e669a1ab693e8ca7ac3bd070b9e

Example response:

HTTP/1.0 200 OK
Server: temboard-agent/0.0.1 Python/2.7.12
Date: Fri, 21 Apr 2017 06:24:45 GMT
Access-Control-Allow-Origin: *
Content-type: application/json

{
    "locks":
    [
        {
            "exclusive": 0,
            "waiting_share_row_exclusive": 0,
            "waiting_share": 0,
            "row_share": 0,
            "waiting_row_exclusive": 0,
            "share_row_exclusive": 0,
            "port": 5432,
            "share": 0,
            "waiting_access_share": 0,
            "dbname": "test",
            "row_exclusive": 0,
            "share_update_exclusive": 0,
            "access_share": 0,
            "access_exclusive": 0,
            "waiting_exclusive": 0,
            "siread": 0,
            "datetime": "2017-04-21 08:55:11.768602+02",
            "waiting_share_update_exclusive": 0,
            "waiting_row_share": 0,
            "waiting_access_exclusive": 0
        }
    ]
}
GET /monitoring/probe/blocks

Run blocks monitoring probe.

Request Headers:
 
  • X-Session – Session ID
Status Codes:

Example request:

GET /monitoring/probe/blocks HTTP/1.1
X-Session: 3b28ed94743e3ada57b217bbf9f36c6d1eb45e669a1ab693e8ca7ac3bd070b9e

Example response:

HTTP/1.0 200 OK
Server: temboard-agent/0.0.1 Python/2.7.12
Date: Fri, 21 Apr 2017 06:24:45 GMT
Access-Control-Allow-Origin: *
Content-type: application/json

{
    "blocks":
    [
        {
            "blks_read": 382,
            "dbname": "postgres",
            "hitmiss_ratio": 99.9998294969873,
            "blks_hit": 224042580,
            "datetime": "2017-04-21 08:57:32.11277+02",
            "port": 5432
        }
    ]
}
GET /monitoring/probe/bgwriter

Run bgwriter monitoring probe.

Request Headers:
 
  • X-Session – Session ID
Status Codes:

Example request:

GET /monitoring/probe/bgwriter HTTP/1.1
X-Session: 3b28ed94743e3ada57b217bbf9f36c6d1eb45e669a1ab693e8ca7ac3bd070b9e

Example response:

HTTP/1.0 200 OK
Server: temboard-agent/0.0.1 Python/2.7.12
Date: Fri, 21 Apr 2017 06:24:45 GMT
Access-Control-Allow-Origin: *
Content-type: application/json

{
    "bgwriter":
    [
        {
            "checkpoint_write_time": 15113301.0,
            "checkpoints_timed": 1960,
            "buffers_alloc": 29369,
            "buffers_clean": 0,
            "buffers_backend_fsync": 0,
            "checkpoint_sync_time": 177464.0,
            "checkpoints_req": 0,
            "port": 5432,
            "buffers_backend": 42258,
            "maxwritten_clean": 0,
            "datetime": "2017-04-21 08:59:20.171443+02",
            "buffers_checkpoint": 149393,
            "stats_reset": "2017-04-14 13:37:15.288701+02"
        }
    ]
}
GET /monitoring/probe/db_size

Run db_size monitoring probe.

Request Headers:
 
  • X-Session – Session ID
Status Codes:

Example request:

GET /monitoring/probe/db_size HTTP/1.1
X-Session: 3b28ed94743e3ada57b217bbf9f36c6d1eb45e669a1ab693e8ca7ac3bd070b9e

Example response:

HTTP/1.0 200 OK
Server: temboard-agent/0.0.1 Python/2.7.12
Date: Fri, 21 Apr 2017 06:24:45 GMT
Access-Control-Allow-Origin: *
Content-type: application/json

{
    "db_size":
    [
        {
            "port": 5432,
            "size": 7021060,
            "dbname": "template1",
            "datetime": "2017-04-21 09:00:47.528365+02"
        },
        {
            "port": 5432,
            "size": 7168172,
            "dbname": "postgres",
            "datetime": "2017-04-21 09:00:47.528365+02"
        }
    ]
}
GET /monitoring/probe/tblspc_size

Run tblspc_size monitoring probe.

Request Headers:
 
  • X-Session – Session ID
Status Codes:

Example request:

GET /monitoring/probe/tblspc_size HTTP/1.1
X-Session: 3b28ed94743e3ada57b217bbf9f36c6d1eb45e669a1ab693e8ca7ac3bd070b9e

Example response:

HTTP/1.0 200 OK
Server: temboard-agent/0.0.1 Python/2.7.12
Date: Fri, 21 Apr 2017 06:24:45 GMT
Access-Control-Allow-Origin: *
Content-type: application/json

{
    "tblspc_size":
    [
        {
            "size": 181067120,
            "port": 5432,
            "spcname": "pg_default",
            "datetime": "2017-04-21 09:13:55.196718+02"
        },
        {
            "size": 622400,
            "port": 5432,
            "spcname": "pg_global",
            "datetime": "2017-04-21 09:13:55.196718+02"
        },
        {
            "size": null,
            "port": 5432,
            "spcname": "tbs",
            "datetime": "2017-04-21 09:13:55.196718+02"
        }
    ]
}
GET /monitoring/probe/filesystems_size

Run filesystems_size monitoring probe.

Request Headers:
 
  • X-Session – Session ID
Status Codes:

Example request:

GET /monitoring/probe/filesystems_size HTTP/1.1
X-Session: 3b28ed94743e3ada57b217bbf9f36c6d1eb45e669a1ab693e8ca7ac3bd070b9e

Example response:

HTTP/1.0 200 OK
Server: temboard-agent/0.0.1 Python/2.7.12
Date: Fri, 21 Apr 2017 06:24:45 GMT
Access-Control-Allow-Origin: *
Content-type: application/json

{
    "filesystems_size":
    [
        {
            "device": "udev",
            "total": 10485760,
            "mount_point": "/dev",
            "used": 4096,
            "datetime": "2017-04-21 07:16:25 +0000"
        },
        {
            "device": "/dev/sda4",
            "total": 21003628544,
            "mount_point": "/",
            "used": 11889070080,
            "datetime": "2017-04-21 07:16:25 +0000"
        }
    ]
}
GET /monitoring/probe/cpu

Run cpu monitoring probe.

Request Headers:
 
  • X-Session – Session ID
Status Codes:

Example request:

GET /monitoring/probe/cpu HTTP/1.1
X-Session: 3b28ed94743e3ada57b217bbf9f36c6d1eb45e669a1ab693e8ca7ac3bd070b9e

Example response:

HTTP/1.0 200 OK
Server: temboard-agent/0.0.1 Python/2.7.12
Date: Fri, 21 Apr 2017 06:24:45 GMT
Access-Control-Allow-Origin: *
Content-type: application/json

{
    "cpu":
    [
        {
            "time_system": 140,
            "time_steal": 0,
            "time_iowait": 10,
            "datetime": "2017-04-21 08:09:27 +0000",
            "measure_interval": 27.88518500328064,
            "time_idle": 27410,
            "cpu": "cpu0",
            "time_user": 290
        },
        {
            "time_system": 110,
            "time_steal": 0,
            "time_iowait": 10,
            "datetime": "2017-04-21 08:09:27 +0000",
            "measure_interval": 27.885642051696777,
            "time_idle": 27410,
            "cpu": "cpu1",
            "time_user": 290
        },
        {
            "time_system": 170,
            "time_steal": 0,
            "time_iowait": 1390,
            "datetime": "2017-04-21 08:09:27 +0000",
            "measure_interval": 27.885895013809204,
            "time_idle": 26040,
            "cpu": "cpu2",
            "time_user": 220
        },
        {
            "time_system": 130,
            "time_steal": 0,
            "time_iowait": 20,
            "datetime": "2017-04-21 08:09:27 +0000",
            "measure_interval": 27.88606309890747,
            "time_idle": 27370,
            "cpu": "cpu3",
            "time_user": 320
        }
    ]
}
GET /monitoring/probe/process

Run process monitoring probe.

Request Headers:
 
  • X-Session – Session ID
Status Codes:

Example request:

GET /monitoring/probe/process HTTP/1.1
X-Session: 3b28ed94743e3ada57b217bbf9f36c6d1eb45e669a1ab693e8ca7ac3bd070b9e

Example response:

HTTP/1.0 200 OK
Server: temboard-agent/0.0.1 Python/2.7.12
Date: Fri, 21 Apr 2017 06:24:45 GMT
Access-Control-Allow-Origin: *
Content-type: application/json

{
    "process":
    [
        {
            "measure_interval": 55.731096029281616,
            "procs_total": "486",
            "forks": 165,
            "procs_blocked": 0,
            "context_switches": 31453,
            "procs_running": 4,
            "datetime": "2017-04-21 08:13:56 +0000"
        }
    ]
}
GET /monitoring/probe/memory

Run memory monitoring probe.

Request Headers:
 
  • X-Session – Session ID
Status Codes:

Example request:

GET /monitoring/probe/memory HTTP/1.1
X-Session: 3b28ed94743e3ada57b217bbf9f36c6d1eb45e669a1ab693e8ca7ac3bd070b9e

Example response:

HTTP/1.0 200 OK
Server: temboard-agent/0.0.1 Python/2.7.12
Date: Fri, 21 Apr 2017 06:24:45 GMT
Access-Control-Allow-Origin: *
Content-type: application/json

{
    "memory":
    [
        {
            "mem_used": 7268151296,
            "swap_used": 0,
            "swap_total": 4026527744,
            "mem_total": 8276094976,
            "mem_cached": 2464796672,
            "mem_free": 1007943680,
            "mem_buffers": 558067712,
            "datetime": "2017-04-21 08:15:06 +0000"
        }
    ]
}
GET /monitoring/probe/loadavg

Run loadavg monitoring probe.

Request Headers:
 
  • X-Session – Session ID
Status Codes:

Example request:

GET /monitoring/probe/loadavg HTTP/1.1
X-Session: 3b28ed94743e3ada57b217bbf9f36c6d1eb45e669a1ab693e8ca7ac3bd070b9e

Example response:

HTTP/1.0 200 OK
Server: temboard-agent/0.0.1 Python/2.7.12
Date: Fri, 21 Apr 2017 06:24:45 GMT
Access-Control-Allow-Origin: *
Content-type: application/json

{
    "loadavg":
    [
        {
            "load1": "0.07",
            "load15": "0.09",
            "load5": "0.16",
            "datetime": "2017-04-21 08:16:16 +0000"
        }
    ]
}
GET /monitoring/probe/wal_files

Run wal_files monitoring probe.

Request Headers:
 
  • X-Session – Session ID
Status Codes:

Example request:

GET /monitoring/probe/wal_files HTTP/1.1
X-Session: 3b28ed94743e3ada57b217bbf9f36c6d1eb45e669a1ab693e8ca7ac3bd070b9e

Example response:

HTTP/1.0 200 OK
Server: temboard-agent/0.0.1 Python/2.7.12
Date: Fri, 21 Apr 2017 06:24:45 GMT
Access-Control-Allow-Origin: *
Content-type: application/json

{
    "wal_files":
    [
        {
            "archive_ready": 0,
            "total_size": 201326592.0,
            "written_size": 13648,
            "datetime": "2017-04-21 08:17:12 +0000",
            "measure_interval": 9.273101091384888,
            "current_location": "53/700035B0",
            "total": 12,
            "port": 5432
        }
    ]
}

PgConf plugin API

GET /pgconf/configuration

Get PostgreSQL settings from pg_settings system view and configuration files.

Request Headers:
 
  • X-Session – Session ID
Status Codes:

Example request:

GET /pgconf/configuration HTTP/1.1
X-Session: 3b28ed94743e3ada57b217bbf9f36c6d1eb45e669a1ab693e8ca7ac3bd070b9e

Example response:

HTTP/1.0 200 OK
Server: temboard-agent/0.0.1 Python/2.7.8
Date: Wed, 22 Apr 2015 09:57:52 GMT
Access-Control-Allow-Origin: *
Content-type: application/json

[
    {
        "category": "Autovacuum",
        "rows":
        [
            {
                "context": "sighup",
                "enumvals": null,
                "max_val": null,
                "vartype": "bool",
                "auto_val": "off",
                "auto_val_raw": "off",
                "boot_val": "on",
                "unit": null,
                "desc": "Starts the autovacuum subprocess.",
                "name": "autovacuum",
                "min_val": null,
                "setting": "off",
                "setting_raw": "off",
                "file_val": null,
                "file_val_raw": null
            }
        ]
    }
]

Error responses:

HTTP/1.0 401 Unauthorized
Server: temboard-agent/0.0.1 Python/2.7.8
Date: Wed, 22 Apr 2015 09:58:00 GMT
Content-type: application/json

{"error": "Invalid session."}

HTTP/1.0 406 Not Acceptable
Server: temboard-agent/0.0.1 Python/2.7.8
Date: Wed, 22 Apr 2015 09:58:00 GMT
Content-type: application/json

{"error": "Parameter 'X-Session' is malformed."}
GET /pgconf/configuration/categories

Get list of settings categories.

Request Headers:
 
  • X-Session – Session ID
Status Codes:

Example request:

GET /pgconf/configuration/categories HTTP/1.1
X-Session: 3b28ed94743e3ada57b217bbf9f36c6d1eb45e669a1ab693e8ca7ac3bd070b9e

Example response:

HTTP/1.0 200 OK
Server: temboard-agent/0.0.1 Python/2.7.8
Date: Wed, 22 Apr 2015 09:57:52 GMT
Access-Control-Allow-Origin: *
Content-type: application/json

{
    "categories":
    [
        "Autovacuum",
        "Client Connection Defaults / Locale and Formatting",
        "Client Connection Defaults / Other Defaults"
    ]
}
POST /pgconf/configuration

Update one or many PostgreSQL settings values. This API issues ALTER SYSTEM SQL statements.

Request Headers:
 
  • X-Session – Session ID
Status Codes:

Example request:

POST /pgconf/configuration HTTP/1.1
Content-Type: application/json
X-Session: 3b28ed94743e3ada57b217bbf9f36c6d1eb45e669a1ab693e8ca7ac3bd070b9e

{
    "settings":
    [
        {
            "name": "autovacuum",
            "setting": "on"
        }
    ]
}

Example response:

HTTP/1.0 200 OK
Server: temboard-agent/0.0.1 Python/2.7.8
Date: Wed, 22 Apr 2015 09:57:52 GMT
Access-Control-Allow-Origin: *
Content-type: application/json

{
    "settings":
    [
        {
            "setting": "on",
            "restart": false,
            "name": "autovacuum",
            "previous_setting": "off"
        }
    ]
}
GET /pgconf/configuration/category/(category_name)

Get list of settings for one category, based on category name.

Request Headers:
 
  • X-Session – Session ID
Parameters:
  • category_name – Setting category name
Status Codes:

Example request:

GET /pgconf/configuration/category/Autovacuum HTTP/1.1
X-Session: 3b28ed94743e3ada57b217bbf9f36c6d1eb45e669a1ab693e8ca7ac3bd070b9e

Example response:

HTTP/1.0 200 OK
Server: temboard-agent/0.0.1 Python/2.7.8
Date: Wed, 22 Apr 2015 09:57:52 GMT
Access-Control-Allow-Origin: *
Content-type: application/json

[
    {
        "category": "Autovacuum",
        "rows":
        [
            {
                "context": "sighup",
                "enumvals": null,
                "max_val": null,
                "vartype": "bool",
                "auto_val": "on",
                "auto_val_raw": "on",
                "boot_val": "on",
                "unit": null,
                "desc": "Starts the autovacuum subprocess. ",
                "name": "autovacuum",
                "min_val": null,
                "setting": "on",
                "setting_raw": "on",
                "file_val": null,
                "file_val_raw": null
            }
        ]
    }
]
GET /pgconf/configuration/status

Shows settings waiting for PostgreSQL server reload and/or restart

Request Headers:
 
  • X-Session – Session ID
Status Codes:

Example request:

GET /pgconf/configuration/status HTTP/1.1
X-Session: 3b28ed94743e3ada57b217bbf9f36c6d1eb45e669a1ab693e8ca7ac3bd070b9e

Example response:

HTTP/1.0 200 OK
Server: temboard-agent/0.0.1 Python/2.7.8
Date: Wed, 22 Apr 2015 09:57:52 GMT
Access-Control-Allow-Origin: *
Content-type: application/json

{
    "restart_changes":
    [
        {
            "context": "postmaster",
            "setting_raw": "128MB",
            "enumvals": null,
            "max_val": 1073741823,
            "vartype": "integer",
            "auto_val": 32768,
            "file_val_raw": "128MB",
            "boot_val": 1024,
            "unit": "8kB",
            "desc": "Sets the number of shared memory buffers used by the server. ",
            "name": "shared_buffers",
            "auto_val_raw": "256MB",
            "min_val": 16,
            "setting": 16384,
            "file_val": 16384,
            "pending_val": "256MB"
        }
    ],
    "restart_pending": true,
    "reload_pending": false,
    "reload_changes": []
}
GET /pgconf/hba

Get records from the pg_hba.conf file.

Query Parameters:
 
  • version – pg_hba.conf file version to get. Ex: 2017-03-06T16:34:07. If not set then the current version is read.
Request Headers:
 
  • X-Session – Session ID
Status Codes:

Example requests:

GET /pgconf/hba HTTP/1.1
X-Session: 3b28ed94743e3ada57b217bbf9f36c6d1eb45e669a1ab693e8ca7ac3bd070b9e

GET /pgconf/hba?version=2017-03-06T16:34:07 HTTP/1.1
X-Session: 3b28ed94743e3ada57b217bbf9f36c6d1eb45e669a1ab693e8ca7ac3bd070b9e

Example response:

HTTP/1.0 200 OK
Server: temboard-agent/0.0.1 Python/2.7.8
Date: Wed, 22 Apr 2015 09:57:52 GMT
Access-Control-Allow-Origin: *
Content-type: application/json

{
    "entries":
    [
        {
            "comment": " \"local\" is for Unix domain socket connections only"
        },
        {
            "database": "all",
            "auth_options": "",
            "connection": "local",
            "user": "alice",
            "address": "",
            "auth_method": "trust"
        },
        {
            "database": "all",
            "auth_options": "",
            "connection": "local",
            "user": "all",
            "address": "",
            "auth_method": "trust"
        }
    ],
    "version": null,
    "filepath": "/etc/postgresql-9.5/pg_hba.conf"
}

Error responses:

HTTP/1.0 404 Not Found
Server: temboard-agent/0.0.1 Python/2.7.9
Date: Thu, 11 Feb 2016 09:04:02 GMT
Access-Control-Allow-Origin: *
Content-type: application/json

{"error": "Version 2016-01-29T08:46:09 of file /etc/postgresql/9.4/main/pg_hba.conf does not exist."}
GET /pgconf/hba/raw

Get raw content of pg_hba.conf file.

Query Parameters:
 
  • version – pg_hba.conf file version to get. Ex: 2017-03-06T16:34:07. If not set then the current version is read.
Request Headers:
 
  • X-Session – Session ID
Status Codes:

Example requests:

GET /pgconf/hba/raw HTTP/1.1
X-Session: 3b28ed94743e3ada57b217bbf9f36c6d1eb45e669a1ab693e8ca7ac3bd070b9e

GET /pgconf/hba/raw?version=2017-03-06T16:34:07 HTTP/1.1
X-Session: 3b28ed94743e3ada57b217bbf9f36c6d1eb45e669a1ab693e8ca7ac3bd070b9e

Example response:

HTTP/1.0 200 OK
Server: temboard-agent/0.0.1 Python/2.7.8
Date: Wed, 22 Apr 2015 09:57:52 GMT
Access-Control-Allow-Origin: *
Content-type: application/json

{
    "content": "# \"local\" is for Unix domain socket connections only\r\nlocal  all  julien  trust \r\nlocal  all  all  trust \r\n# IPv4 local connections:\r\nhost  all  all 127.0.0.1/32 trust \r\n# IPv6 local connections:\r\nhost  all  all ::1/128 trust \r\n",
    "version": null,
    "filepath": "/etc/postgresql-9.5/pg_hba.conf"
}

Error responses:

HTTP/1.0 404 Not Found
Server: temboard-agent/0.0.1 Python/2.7.9
Date: Thu, 11 Feb 2016 09:04:02 GMT
Access-Control-Allow-Origin: *
Content-type: application/json

{"error": "Version 2016-01-29T08:46:09 of file /etc/postgresql/9.4/main/pg_hba.conf does not exist."}
POST /pgconf/hba

Writes pg_hba.conf file content.

Request Headers:
 
  • X-Session – Session ID
Status Codes:

Example request:

POST /pgconf/hba HTTP/1.1
X-Session: 3b28ed94743e3ada57b217bbf9f36c6d1eb45e669a1ab693e8ca7ac3bd070b9e
Content-Type: application/json

{
    "entries":
    [
        {
            "connection": "local",
            "user": "all",
            "database": "all",
            "auth_method": "peer"
        }
    ],
    "new_version": true
}

Example response:

HTTP/1.0 200 OK
Server: temboard-agent/0.0.1 Python/2.7.8
Date: Wed, 22 Apr 2015 09:57:52 GMT
Access-Control-Allow-Origin: *
Content-type: application/json

{
    "last_version": "2016-02-11T15:26:19",
    "filepath": "/etc/postgresql/9.4/main/pg_hba.conf"
}
POST /pgconf/hba/raw

Writes pg_hba.conf file content. Raw mode.

Request Headers:
 
  • X-Session – Session ID
Status Codes:

Example request:

POST /pgconf/hba/raw HTTP/1.1
X-Session: 3b28ed94743e3ada57b217bbf9f36c6d1eb45e669a1ab693e8ca7ac3bd070b9e
Content-Type: application/json

{
    "content": "local all all md5\r\n ... ",
    "new_version": true
}

Example response:

HTTP/1.0 200 OK
Server: temboard-agent/0.0.1 Python/2.7.8
Date: Wed, 22 Apr 2015 09:57:52 GMT
Access-Control-Allow-Origin: *
Content-type: application/json

{
    "last_version": "2016-02-11T15:26:19",
    "filepath": "/etc/postgresql/9.4/main/pg_hba.conf"
}
DELETE /pgconf/hba

Remove a version of pg_hba.conf file.

Query Parameters:
 
  • version – pg_hba.conf file version to remove. Ex: 2017-03-06T16:34:07.
Request Headers:
 
  • X-Session – Session ID
Status Codes:

Example requests:

DELETE /pgconf/hba?version=2017-03-06T16:34:07 HTTP/1.1
X-Session: 3b28ed94743e3ada57b217bbf9f36c6d1eb45e669a1ab693e8ca7ac3bd070b9e

Example response:

HTTP/1.0 200 OK
Server: temboard-agent/0.0.1 Python/2.7.8
Date: Wed, 22 Apr 2015 09:57:52 GMT
Access-Control-Allow-Origin: *
Content-type: application/json

{
    "deleted": true,
    "version": "2016-01-29T08:44:26"
}

Error responses:

HTTP/1.0 404 Not Found
Server: temboard-agent/0.0.1 Python/2.7.9
Date: Thu, 11 Feb 2016 09:04:02 GMT
Access-Control-Allow-Origin: *
Content-type: application/json

{"error": "Version 2016-01-29T08:46:09 of file /etc/postgresql/9.4/main/pg_hba.conf does not exist."}
GET /pgconf/hba/versions

Get the list of pg_hba.conf versions.

Request Headers:
 
  • X-Session – Session ID
Status Codes:

Example requests:

GET /pgconf/hba/version HTTP/1.1
X-Session: 3b28ed94743e3ada57b217bbf9f36c6d1eb45e669a1ab693e8ca7ac3bd070b9e

Example response:

HTTP/1.0 200 OK
Server: temboard-agent/0.0.1 Python/2.7.8
Date: Wed, 22 Apr 2015 09:57:52 GMT
Access-Control-Allow-Origin: *
Content-type: application/json

{
    "versions":
    [
        "2016-02-11T18:01:35",
        "2016-02-11T16:43:51",
        "2016-02-11T16:43:36"
    ],
    "filepath": "/etc/postgresql/9.4/main/pg_hba.conf"
}
GET /pgconf/pg_ident

Get raw content of pg_ident.conf file

Request Headers:
 
  • X-Session – Session ID
Status Codes:

Example requests:

GET /pgconf/pg_ident HTTP/1.1
X-Session: 3b28ed94743e3ada57b217bbf9f36c6d1eb45e669a1ab693e8ca7ac3bd070b9e

Example response:

HTTP/1.0 200 OK
Server: temboard-agent/0.0.1 Python/2.7.8
Date: Wed, 22 Apr 2015 09:57:52 GMT
Access-Control-Allow-Origin: *
Content-type: application/json

{
    "content": "# PostgreSQL User Name Maps\r\n# =========================\r\n ... ",
    "filepath": "/etc/postgresql/9.4/main/pg_ident.conf"
}
POST /pgconf/pg_ident

Write pg_ident.conf file content. Raw mode.

Request Headers:
 
  • X-Session – Session ID
Status Codes:

Example request:

POST /pgconf/pg_ident HTTP/1.1
X-Session: 3b28ed94743e3ada57b217bbf9f36c6d1eb45e669a1ab693e8ca7ac3bd070b9e
Content-Type: application/json

{
    "content": "# PostgreSQL User Name Maps\r\n ..."
}

Example response:

HTTP/1.0 200 OK
Server: temboard-agent/0.0.1 Python/2.7.8
Date: Wed, 22 Apr 2015 09:57:52 GMT
Access-Control-Allow-Origin: *
Content-type: application/json

{
    "update": true
}
GET /pgconf/hba/options

Get HBA potential values for each column.

Request Headers:
 
  • X-Session – Session ID
Status Codes:

Example requests:

GET /pgconf/hba/options HTTP/1.1
X-Session: 3b28ed94743e3ada57b217bbf9f36c6d1eb45e669a1ab693e8ca7ac3bd070b9e

Example response:

HTTP/1.0 200 OK
Server: temboard-agent/0.0.1 Python/2.7.8
Date: Wed, 22 Apr 2015 09:57:52 GMT
Access-Control-Allow-Origin: *
Content-type: application/json

{
    "connection": [ "local", "host", "hostssl", "hostnossl" ],
    "database": [ "all", "sameuser", "samerole", "db1" ],
    "user": [ "all", "user1", "+group1" ],
    "auth_method": [ "trust", "reject" ]
}