Integrate Audit trail module with Elasticsearch and Kibana

The default logging module of Sitefinity CMS is JSON logger, but you can also integrate Sitefinity CMS Audit trail module with external logging tools.

Elasticsearch is an open-source Java-based web server, used by the Audit trail module for storing and querying logged records, instead of using the textual log files.

Kibana is Elasticsearch web server that uses static HTML pages and client-side AJAX calls for querying and visualizing records from Elasticsearch in the form of advanced reports and custom dashboard screens.

PREREQUISITES:
  • Elasticsearch is a Java-based server, which requires Java Development Kit (JDK). Download the JDK from the Oracle Downloads page and install it.
  • You set the Path Environment variable. For more information, see the Oracle JDK installation instructions.
RECOMMENDATION: To avoid issues when integrating the Audit trail module, ElasticSearch, and Kibana, we recommend that you work with the following tested version compatibility of the products: 

Install Elasticsearch module

To integrate with Elasticsearch and Kibana servers, you must install the ElasticSearchAuditTrailLogger module. You do this by installing the Telerik.Sitefinity.Audit.Elasticsearch NuGet package from Sitefinity CMS NuGet Repository.

During setup, you need to run the Elasticsearch server on the web server machine, on a dedicated machine, on premise, in the cloud, or in a cluster of machines.

Setup Elasticsearch

The Audit Trail Elasticsearch module is included in Sitefinity CMS.
To activate it, in Sitefinity CMS backend, navigate to Administration » Modules and Services. Make sure the Audit Trail and Audit Trail - Elasticsearch modules are installed and active.

Configure ElasticSearch and Kibana

  1. Depending on the Kibana version you are working with, download and extract the corresponding ElasticSearch version.  
  2. If you want the server to be started on a specific port, edit the elasticsearch.yml file, located in the <ElasticsearchPath>/config folder.
    From the Set a custom port to listen for HTTP traffic: section, uncomment and change the port to the one you want to use.

    The default port is 9200.

  3. To disable forming clusters with other running instances in the same network, edit the <ElasticsearchPath>\config\elasticsearch.yml file and uncomment the following line:

    discovery.zen.ping.multicast.enabled: false

    For example, you do this when several developers work in the same network.

  4. Start the Elasticsearch server, either as executable, or as a service:
    • To start Elasticsearch as an executable, run ~\<ElasticsearchPath>\bin\elasticsearch.bat.
      Ensure that the file is called on system startup.
    • To start Elasticsearch as a service, in ~\<ElasticsearchPath>\bin, in a command prompt, perform the following:
      • Install the service by typing service install
      • Start the service by typing service start
  5. In Sitefinity CMS backend, navigate to Administration » Settings » Advanced Settings » ElasticsearchAudit.
  6. In the ElasticsearchUri field, enter the root URL of your Elasticsearch site.
    The default value is 9200
  7. If you no longer need JSON logging, disable the default JSON logging by deselecting the EnableJsonLogging checkbox.

RECOMMENDATION: Because Sitefinity CMS Elasticsearch audit logger invokes Elasticsearch RESTful services synchronously, to improve performance, we recommend that you ensure minimum network latency between your web server and your Elasticsearch server. If this is an issue, you can install a dedicated logging agent - for examaple, Logstash, on the webserver machine, to provide out-of-process buffering and persistence of the logged messages.

Set up Kibana

Kibana 4.1.2

  1. Download and extract Kibana from the Kibana 4.1.2 download page.  
  2. Open the ~\<KibanaPath>\config\kibana.yml file for editing.
    Locate the elasticsearch_url setting and set it to the root URL of your ElasticSearch server.
  3. Navigate to the ~\<KibanaPath>\bin folder and open the kibana.bat file.
    This file hosts Kibana on the port set in the configuration file.

    NOTE: The default value is 9200. You can also set which port to be used by Kibana in the <code- code="" port<=""> setting. The default value is 5601. </code->

  4. Open your hosted Kibana site and configure an index pattern:
    1. In Index name or pattern field, type index
    2. In Time-field dropdown menu, select Timestamp.
    3. Click Create.

Kibana 3.1.0

  1. Download and extract Kibana from Kibana 3.1.0 download page.  
  2. Host the extracted folder on a web server that is accessible by the users entitled access to the audit log.      
  3. Open the ~\<KibanaPath>\config.js file for editing.
  4. Locate the elasticsearch: setting and set it to the root URL of your Elasticsearch server. The default value is 9200

NOTE: Because Kibana is a client-side HTML application, which invokes the Elasticsearch REST API directly from the client's browser, the Elasticsearch server must be accessible from the machine of every user who is allowed to view the audit log. To avoid unrestricted access to the audit log. To avoid unrestricted access to the audit log (either through Kibana or just by calling the REST services of the Elasticsearch server), employ some network protection mechanism like a firewall (for example, white listing user IPs) or a dedicated VPN. In addition, make sure that these restrictions do not prevent Sitefinity CMS from connecting to Elasticsearch.

Was this article helpful?