Adabas Analytics can be used to analyze the performance of an Adabas database; it is possible to examine the performance data of each Adabas call executed in the database.

The current version of Adabas Analytics is delivered with the third-party product Elasticsearch (and its visualization component Kibana) to store and visualize the Adabas performance data. The combination of the Adabas nucleus, the Adabas Analytics server, Elasticsearch and Kibana lets you analyze Adabas performance data in near-realtime.

• Getting Started with Elasticsearch/Kibana

• Troubleshooting

• Frequently Asked Questions

---

Getting Started with Elasticsearch/Kibana

Prerequisites

Adabas Version 6.5.1 and Adabas Analytics Version 2.1.0 must already be installed before you install and use Elasticsearch/Kibana.

The following default TCP ports are used:

• 6521, 6522 - Adabas Analytics server

• 9200, 9300 - Elasticsearch

• 5601 - Kibana

Please ensure that these ports are not already in use. Depending on your configuration and/or firewall settings, open this ports for inbound communications.

Installing, Configuring and Starting Elasticsearch

To install, configure and start Elasticsearch

1. Install the third-party software Elasticsearch from $EALPROGDIR/third-party by extracting the file elasticsearch-5.1.2.zip to a directory <ELASTICSEARCH_INSTALL_DIR> of your choice (Windows), or by extracting the file elasticsearch-5.1.2.tar to a directory <ELASTICSEARCH_INSTALL_DIR> of your choice (Unix).

2. Edit the Elasticsearch configuration file: the configuration file elasticsearch.yml is located in the config subdirectory of <ELASTICSEARCH_INSTALL_DIR>.

   Change the line

   #cluster.name: my-application

   to

   cluster.name: AdabasAnalyticsData

   If the Adabas Analytics server and Elasticsearch are running on different hosts, change the line:

   #network.host: 192.168.0.1

   to

   network.host: 0.0.0.0

   Otherwise Elasticsearch will not be able to connect with the remote Adabas Analytics server.

   You can find detailed information about configuring Elasticsearch here: https://www.elastic.co/guide/en/elasticsearch/reference/current/settings.html.

3. Start Elasticsearch by executing ELASTICSEARCH_INSTALL_DIR\bin\elasticsearch.bat (Windows), or ELASTICSEARCH_INSTALL_DIR/bin/elasticsearch (UNIX).

   Elasticsearch should now be up and running on localhost:9200.

4. If Elasticsearch is running on a different host to the Adabas Analytics server, edit the Adabas Analytics configuration file EALPROGDIR/configuration/config.xml.

   Change the line

   <Location host="localhost" port="9300" />

   to

   <Location host="<ELASTICSEARCH_HOST>" port="9300" />

   where <ELASTICSEARCH_HOST> is the name of the host on which Elasticsearch is running.

Installing, Configuring and Starting Kibana

To install, configure and start Kibana

1. Install the third-party software Kibana from $EALPROGDIR/third-party by extracting the file kibana-5.1.2-windows-x86.zip a to a directory <KIBANA_INSTALL_DIR> of your choice (Windows), or by extracting the file kibana-5.1.2-linux-x86_64.tar.gz to a directory <KIBANA_INSTALL_DIR> of your choice (UNIX).

2. Edit the Kibana configuration file: the configuration file kibana.yml is located in the config subdirectory of <KIBANA_INSTALL_DIR>.

   Change the line

   #elasticsearch.ssl.verify: true

   to

   elasticsearch.ssl.verify: false

   If Kibana is installed on a different host to Elasticsearch, change the following lines (leave them unchanged if Kibana is installed on the same host as Elasticsearch):

   Change

   #server.host: "localhost"

   to

   server.host: <KIBANA_HOSTNAME>

   where <KIBANA_HOSTNAME> is the name of the host on which Kibana is installed.

   Change

   #elasticsearch.url: "http://localhost:9200"

   to

   elasticsearch.url: "http://<HOSTNAME>:9200"

   where <HOSTNAME> is the name of the host on which Elasticsearch is installed.

   Change

   #server.name: "your-hostname"

   to

   server.name: "your name"

   You can find detailed information about configuring Kibana here: https://www.elastic.co/guide/en/kibana/current/settings.html.

3. Start Kibana by executing KIBANA_INSTALL_DIR\bin\kibana.bat (Windows), or KIBANA_INSTALL_DIR/bin/kibana (UNIX).

   Kibana should now be up and running on localhost:5601.

Visualizing Adabas Analytics Data using Elasticsearch/Kibana

You can use the example Kibana dashboard provided with the installation to display Adabas/Natural performance data in near-realtime. The following section describes how to import and use the dashboard.

To visualize Adabas Analytics data using Elasticsearch/Kibana

1. Start the Adabas Analytics server.

   On Windows:

   EALPROGDIR/bin/AdabasAnalyticsServer.bat start

   On UNIX:

   EALPROGDIR/bin/AdabasAnalyticsServer.sh start

2. Create a demo Adabas database with the crdemodb utility.

   crdemodb <dbid>

3. Run the configuration utility EALCONFIG, which is located in the directory ADAPROGDIR. When you are prompted for filter events, select ADA_NAT_PERF from the list of available event types.

   For further information about the EALCONFIG utility, see the section EALCONFIG (Event Analytics Configuration Tool).

4. Start the demo Adabas database that you created earlier.

   adastart <dbid>

5. Generate some activity on the demo Adabas database. For example, run getdbinfo <dbid>, or run the c_example.exe on your database (c_example.exe is located in the /bin/examples subdirectory of AdabasClient)

   This step sends event data to Elasticsearch, and allows Elasticsearch to build the initial index structure.

6. Access Kibana from a browser (for example Firefox or Chrome) with the following URL:

   http://<KIBANA_HOSTNAME>:5601

7. Create an index pattern for your event data:

   1. In Kibana, go to Management->Index Patterns->Add new.

   2. Keep the checkbox Index contains time-based events checked.

   3. Enter the index name adabas_analytics-*.

   4. Wait for a few seconds and leave the time field selection at event_timestamp.

   5. Click on the Create button.

   Note:
   You can validate this step by going to DevTools->Console and entering the command GET _cat/indices. This should produce output of the following form:

   ...
   ... adabas_analytics-<CURRENT_DATE> ...  <CURRENT_SIZE>
   ... .kibana                         ...  <CURRENT_SIZE>
   ... 

8. You can now display your data in Kibana by going to Discover, and then selecting the indexadabas_analytics-* from the drop-down box.

   Note:
   If you don't see event data, try setting a longer period under review. In the top right corner of your Kibana browser window, click on last 15 minutes and select the timeframe for which you want to review the data.

9. Import the predefined Adabas/Natural dashboard for Kibana, as well as the visualization objects located in the directory AdabasAnalytics/third-party/KibanaExampleDashboard. In Kibana, go to Management->Saved Objects->Import and select the delivered json files (one at a time).

   Note:
   The visualization objects can only be imported if index data already exists in ElasticSearch. A corresponding message is displayed if problems occur.

Troubleshooting

If an error occurs, check the contents of the ealserver.log file in the log subdirectory of your AdabasAnalytics installation. Look for the entry "Elastic Search Sink "ElasticSearch" sending events to cluster <YOUR_CLUSTER_NAME>" where YOUR_CLUSTER_NAME matches the cluster.name entry in the elasticsearch.yml configuration file. If the log file contains the above entry and if the problem still persists, check your firewall settings.

If Elasticsearch doesn't start on your system, check the log files in the logs directory under your <ELASTICSEARCH_INSTALL_DIR> for configuration errors. If any configuration error is fixed but Elasticsearch still refuses to start, the Elasticsearch documentation recommends that you deactivate the system call filters at your own risk. This is done by setting bootstrap.system_call_filter to false in the elasticsearch.yml config file.

Frequently Asked Questions

How can I share dashboards without Kibana administration features?

1. Click on Dashboard in the side navigation.

2. Open the dashboard you want to share.

3. Add &embed=true at the end of the address line of your Kibana dashboard URL.

4. Click on Share.

5. Copy the link you want to share. We recommend that you use use shortened snapshot URL.

How can I protect the Kibana index located in ElasticSearch?

1. Click on Dev Tools in the side navigation.

2. Execute the console command GET _cat/indices to get a list of existing indices.

3. Execute the console command PUT /<yourKibanaIndexName>/_settings {"index.blocks.read_only": true} to disable any modifications to your Kibana index.

4. Execute the console command GET /<yourKibanaIndexName>/_settings to check your current settings.

   Note:
   In case of protection, a fatal error message will be returned

   "Request to Elasticsearch failed: ...
                   ... [FORBIDDEN/5/index read-only (api)];"

How can I backup and restore an individual ElasticSearch index?

1. Refer to the section Elasticsearch Reference [5.1] | Modules | Snapshot And Restore in the online documentaton https://www.elastic.co/guide/en/elasticsearch/reference/5.1/modules-snapshots.html.

How can I delete a daily index generated by receiving events from the Adabas Analytics Server?

1. Click on Dev Tools in the side navigation.

2. Execute the console command GET _cat/indices/adabas_analytics-* to get a list of existing daily Adabas Analytics indices.

3. Execute the console command DELETE /adabas_analytics-<yourSelectedDailyIndex>.

4. Execute the console command GET _cat/indices/adabas_analytics-* again to validate the result.

Note:
Refer to the section Elasticsearch Reference [5.1] | Indices APIs | Delete Index in the online documentation.

How can I develop my own dashboards?

We recommend that you refer to Kibana's "Getting Started" Tutorial - see https://www.elastic.co/guide/en/kibana/current/getting-started.html