Elasticsearch Integration
Overview
The LRS can accelerate its dashboard and statement viewer by leveraging Elasticsearch in addition to MongoDB. When configured with the optional Elasticsearch connection, the LRS will synchronize xAPI statements in real time between these two database products in real time. The system will detect analytics queries that can be fulfilled by Elasticsearch, then translate and dispatch them automatically. This process happens under-the-hood and is invisible to both the user interface and the API. However, the effects will be obvious - on larger data sets, many queries can be hundreds of times faster when accelerated in this way.
In order to synchronize data with Elasticsearch, the LRS must be supplied a connection string to an Elasticsearch server. We current support Elastic version 7.x. The LRS will also function when connected to OpenSearch in 7.17 compatibility mode.
The ElasticSearch integration is REQUIRED for users who wish to analyze large datasets. If the number of xAPI statements in an LRS is greater than the maxVQLWindowSize setting value, some analytics queries will not consider the entire dataset. The interaction between maxVQLWindowSize and the given query is complex, and in many cases the results will be correct. However, in this state it is possible that the server will return incomplete results. If you wish to use Mongo alone to analyze large data sets, set maxVQLWindowSize to some arbitrarily large number. Also be aware of the globalMongoTimeout setting, which controls the maximum amount of time a query may process.
Configuration
There are several settings relevant to the Elasticsearch connection. As with all settings, these can be supplied as environment variables, command line parameters, or defined in the .env file.
| Setting name | Discussion |
elasticSearchServer | The connection string to Elastic. This is always a web address, for example, "http://192.168.1.2:9200". It should include the port number on which ES is listening, unless that port is the default port for the give protocol (80 for http and 443 for https). It should not include a path. If your Elastic deployment is configured to use authentication, supply the name and password as HTTP basic authentication parameters in URL form. For example, "https://username:password@myserver.org:9200" |
elasticReconnectTimeout | A human interval like "30 seconds". The time after which the server will attempt to reconnect to ES when a connection fails to be established. Default: '30 seconds' |
esIndexExtensions | Should xAPI extensions be included in the Elasticsearch mapping? Default: true. Because xAPI allows arbitrary data to be included in extensions, it is possible to generate data that ES cannot ingest. This can happen when extensions change the data type at a particular path, such as using a string in some statement, but an integer in others. In these cases, ES will drop the data. This can lead to large elasticMissingRatioError values. Eventually, if too much data fails to be stored in this way, the LRS will assume the ES index is "unhealthy" and refuse to use it. |
elasticTimeout | A human interval like "30 seconds". The maximum amount of time the LRS will wait for a response from ES. Requests longer than this time will be canceled. Default: '20 seconds'. When such a request times out, downstream effects will occurs. You may experience dashboard graphs disappear or render the "No data to display" error message. |
elasticMissingRatioError | A number between 0 and 1. Defines the ratio of the count of statements between Elastic and Mongo that is considered normal. Default: 0.99. This means that by default, an ES index containing 99% of the Mongo statements is healthy enough to use. While it may be tempting to set this value to 1.0 for maximum consistency, when under load statements are always stored in Mongo before ES. This can lead to a situation where ES never has exactly the same count as Mongo, because of the ongoing traffic. Lower this ratio if, under high load, you see a notification describing the index as unhealthy. |
esDynamicExtensions | When the LRS encounters xAPI extensions, if esIndexExtensions is true, how are they treated. Default: true. Use "true" for regular ES dynamic mapping or "runtime" to use runtime mapping. A discussion of the ramifications of each selection is beyond the scope of this document. |
esKeywordMaxLength | A Number. Strings beyond this length will be truncated in the mapping. Default: 256. Increase this value if you have identifiers that are very long. Too short a value can lead to different xAPI objects, agents or activities to be considered the same, when their IDs actually differ. |
Permissions
The LRS will create and destroy Elasticsearch indexes as LRS tenants are created and destroyed. This means that the user account the LRS users to access Elastic should have permission to create and delete indexes. The LRS will also query, update, and change the mapping of the indexes it controls.
Connectivity
As of 12.6, the LRS will attempt to reconnect to Elasticsearch if connectivity is interrupted. Normally, this should never occur, and you should endeavor to make sure Elasticsearch is always available. The reconnection feature is intended to mitigate only transient connection problems. If the Elasticsearch server must be shut down, and you cannot stop the LRS from accepting new data, the index will be out of date when connectivity is restored. Once this occurs, the index will have to be resynchronized from Mongo.
Possible Error States
Issues with the ES connection and index will be displayed in warning banners on the LRS home page, or the homepage for a particular tenant.
It looks like this server does not have an Elasticsearch connection. While optional, an Elasticsearch connection is highly recommended.
This message means that the server is not connected to Elastic. It does NOT mean that no connection is configured - it only means that one is not active. This may mean either none is configure, or, if one is configured, that configuration is incorrect or the connection could not be established. Check the server configuration and logs for more information.
The analytics index for this LRS seems to be missing data. If this persists for more than a few minutes, please use the database management page to rebuild the analytics index.
The analytics index for the LRS is unhealthy. This can mean that one does not exist, or that one exists but contain an unexpected amount of data. The index will need to be rebuilt or resynced. In this state, new data will be written to ES, but the analytics system will not accelerate queries.
The analytics index was built with a previous version of the LRS, and needs to be rebuilt. Please use the database management page to rebuild the analytics index.
The LRS can detect differences between the expected and actual configuration of the ES index for a given tenant. This message means that the LRS software was updated or downgraded, or the ES index settings were manually changed. Either way, the ES index is not in the expected state. It will need to be rebuilt.
Rebuilding the Index
Because the LRS stores data primarily in MongoDB, we can rebuild the Elasticsearch database from the information stored in Mongo. Various error conditions may require you to rebuild the index or resync the data. Each of the two options below will launch a background processing job on the LRS that will complete asynchronously. These jobs can last from seconds to hours depending on the data sizes. Expect the process to take, generally, one second for every thousand xAPI statements. You can capture new data while this process runs but note that significant server resources will be required. Plan to run this process during times of low load. Each of these processes can be launched from "All Management Tools / Database Management" in a given tenant.
Rebuild Analytics Index
This process will completely rebuild the analytics index for the given tenant. If an index exists, it will be destroyed and recreated. If no index exists, a new one will be created and configured. Use this when connecting to ES for the first time, or if the existing index is built with an incompatible version if the LRS.
Resync Analytics Index
The LRS keeps track in Mongo whether or not a statement was successfully inserted into Elastic. This process will insert into Elastic only statements that have not been successfully inserted before. Note that we do not compare actual IDs - if you manually remove data from Elastic, the LRS will be unaware of exactly what statements are missing, and a full rebuild will be required. Use this process to fix the index after an intermittent connection issue.
Related Articles
LMS Integration
The Veracity Learning offers seamless integration with your LMS to allow instructors and students to access the services of the LRS without leaving their LMS environment. This is accomplished via LTI (Learning Tools Interoperability), a standard from ...SQL Integration
SQL Integration is an Enterprise only feature Veracity LRS can synchronize your xAPI statements into an SQL database in real time. The LRS will open a connection to your SQL server, and flush out statements every 300 milliseconds. Statements are not ...Single Sign On (SSO) Integration
Veracity can integrate with your single sign on provider using OpenID Connect or Security Assertion Markup Language (SAML). This integration allows your enterprise users to log into the LRS user interface without providing a password. Integrating a ...Versions of Veracity Learning
Veracity Learning LRS comes in a few versions. The main version, and the one you're most likely looking at right now, is LRS.io. LRS.io This is our cloud hosted SaaS service, where anyone can create an LRS. You can use the free version, which is ...LRS Management
Veracity Learning LRS gives you many tools to manage your LRS and the data in it. These include backup and restore features, import and export features, as well as tools to update, migrate and modify the data in the LRS. LRS Management Basics Now ...