Help us improve your experience.

Let us know what you think.

Do you have time for a two-minute survey?

 
ON THIS PAGE
 

Preparations

Enabling Ingestion into TimescaleDB and Publishing of Metrics to Kafka

To enable ingestion of Paragon Active Assurance data into TimescaleDB, enable and start the services netrounds-metrics and netrounds-timescaledb:

To be able to use TimescaleDB in conjunction with the Streaming API (see the Streaming API Guide), you must enable publishing of database metrics to the Kafka event-streaming platform. In the file /etc/netrounds/netrounds.conf, set:

Note:

Don't forget to uncomment this line.

Then restart all services:

Connecting to TimescaleDB

Connecting an external client to the TimescaleDB database is done in two steps:

  • Setting up SSH tunneling between the database client node and the TimescaleDB node
  • Defining a connection in the database client using the parameters for TimescaleDB

The subsequent sections describe these operations in more detail.

Note:

The definition of the SSH tunnel depends on the database client in use and the underlying operating system: in some circumstances (for example, with PgAdmin), both the SSH tunnel and the connection parameters can be defined within the database client itself.

Please refer to the documentation of the database client in use for more information.

SSH Tunneling configuration

To establish an SSH tunnel between the database client and TimescaleDB, the following information is required:

  • SSH port (default value 22)
  • OS user in the Control Center node
  • FQDN/Public IP of the Control Center node
  • Location of the Control Center public key and its password
  • The database port number to which TimescaleDB listens (7432)
  • The port number local to the database client that will forward the traffic to TimescaleDB. Its value depends on the port number available in the database client node and might differ from the listening port for TimescaleDB.

The section below shows how to set up an SSH tunnel on Linux.

Example: SSH Tunneling on Linux

Note:

The instructions below refer to a database client running in a Linux environment outside Control Center.

This example describes how to define an SSH tunnel between the database client and the TimescaleDB server.

Definitions:

  • Client: The computer running the database client which you want to connect to the TimescaleDB database server.
  • Server: The Control Center instance running the TimescaleDB database server.

Below, <Control Center IP/FQDN> is the IP address or Fully Qualified Domain Name of the node where Control Center is running. It is assumed that TimescaleDB on the server listens to the default port 7432.

Prerequisites:

  • You have a private SSH key paa_cc.key created on the client, and you have copied the public key to the server.
  • openssh-server is installed on the server.

Do the following:

  • Open a terminal window on the client.

  • Run this command to set up background SSH port forwarding:

    where <os_user> is the OS user on the TimescaleDB server and <local_port> is the port in the client node that forwards the traffic to the TimescaleDB listening port.

Database Configuration

Once there is an active SSH tunnel between the database client and the TimescaleDB database, you can establish a connection from the database client towards the TimescaleDB database using the following connection parameters:

  • Hostname: 127.0.0.1
  • Port: <local_port> (port number in the database client node that forwards the traffic to the TimescaleDB listening port)
  • Database: paa-metrics
  • Username: (paaread or database user with paaread role assigned)
  • Password: (password of the database user given as Username)
  • TLS/SSL Mode: prefer

Please refer to the documentation of the database client in use for the exact names of the above options.

For example, if psql is the database client in use and there is an SSH tunnel defined as in the section Example: SSH Tunneling on Linux, the command

will successfully create a connection towards TimescaleDB. You will be prompted for a password, which is paaread.

Managing Database Users

Default User

By default, TimescaleDB in Control Center has a user paaread, with password paaread, which is allowed to access all the database objects related to metrics in read-only mode.

For security reasons, it is strongly recommended that you alter the default password of this user after logging in for the first time as user paaread. How to do this is described in the Operations Guide, chapter Updating Databases with New User Passwords.

Additional Users

If multiple database users need to access the TimescaleDB database to query metrics data, log in as superuser paa, with password paa. You can then create new users and grant them the same privileges as the paaread user.

Configuring Data Retention Periods

You can change the data retention periods for raw data and rollups in the file /etc/netrounds/metrics.yaml. The relevant properties are laid out in the table below:

Property name Retention period for Default retention period
retain-duration-raw 10-second interval 72.0h (3 days)
retain-duration-1min 1-minute rollups 168.0h (7 days)
retain-duration-5min 5-minute rollups 720.0h (30 days)
retain-duration-30min 30-minute rollups 4320.0h (180 days)
retain-duration-hour 60-minute rollups 8760.0h (365 days)

In addition, there is a property cleanup-poll-duration which governs how soon any changes to the retention periods will take effect. If you set a retention period lower than cleanup-poll-duration, the change will come into effect only after cleanup-poll-duration. In such a situation, it is best to lower cleanup-poll-duration as well.

Durations must be specified as decimal numbers with one of the following unit suffixes: ns, us, ms, s, m, h, as in the above table. (There is no "day" suffix.)

Troubleshooting

Problem: No data in the TimescaleDB tables when running queries.

  • Solution:

    Make sure you have followed all the steps in the guide for turning on TimescaleDB ingestion (see the section Enabling Ingestion into TimescaleDB).

    You can also make sure that the metrics are being published to Kafka by using the kafkacat tool in Control Center:

    If nothing is published, make sure that KAFKA_METRICS_ENABLED=True in /etc/netrounds/netrounds.conf, and after updating that file restart all services with