Teneo Log Data Manager
Introduction
In order to properly use and benefit from the Log Data features, certain settings and parameters need to be accurately configured and maintained in several components throughout the Teneo Platform, such as Teneo Manager or the Teneo Log Data Manager, both when the solution is published and at any time Log Data Sources (LDSs) are created or modified.
This section is aimed at users performing the role of system administrator or data manager, and whose main responsibility is to ensure that log data is correctly set and kept in the Teneo Platform.
This page contains the following sections:
- Log handing in the Teneo Platform provides background information about how logs are stored using the Message Queue function
- The data manager's role gives an overview of the tasks to be executed by the data manager (and when)
- Log data management in Teneo Manager provides a description of the tasks to carry out in Teneo Manager, including how Log Archives and Log Data Sources are set and updated in the Platform
- Teneo Log Data Manager gives a description of the tasks to carry out in the Teneo Log Data Manager module.
Log handling in the Teneo Platform
In a published environment, the Teneo Engine logs a user's interaction with the published solution; these logs can later be accessed, queried and analyzed through the Log Data Source in Teneo Studio (Solution tab > Optimization > Log Data).
Before logs are available to a Teneo Studio user, these are transported and stored by different elements of the Platform.
Very briefly:
- When transported, logs are kept together at session level, that is, the "transport log unit" is the session
- Once a session is completed, all its logs are immediately sent to the Message Queue (MQ), which moves them to their corresponding Log Archive and Log Data Source, already set in Cassandra and Elasticsearch
- Logs are then accessible from the Log Data Source set in Elasticsearch; each Log Data Source is configured to contain the logs belonging to a specific period.
Note that while the Message Queue always moves all logs to the Log Archive, logs are only moved to an Log Data Source if the configuration allows it, that is, if the transported logs belong to the time span of any of the available Log Data Sources.
Message Queue
The Message Queue is, in short, a predefined and productized architecture for transporting Engine Session Logs from the running Engine instance to Log Storage.
By using the Message Queue, each session is processed individually as it ends, which has the following benefits:
- Logs available in seconds
- (Near) real-time reporting
- Central log store improves data security.
Log Storage: Log archives and Log Data Source
The Message Queue function will automatically drop all logs in a pre-defined Log Archive in Cassandra. However, these logs are not yet queryable using Teneo Studio since queries are not run on the Log Archives but on the Log Data Sources. The Log Data Sources, which are kept in Elasticsearch, contain the logs of a configurable period of time, thus representing a snippet of all the logs available in Cassandra.
Both Log Archives and Log Data Sources are configured in Teneo Manager.
Keeping log content up-to-date
Once created, Log Archives are automatically updated with new logs as soon as a session ends. Users do not need to carry out any further actions.
For Log Data Sources, updating the log content depends on how the Until field is configured in Teneo Manager.
If Now is selected, the Log Data Source is set with a dynamic time range, meaning that the logs contained in the Log Data Source are configured between Now (the current week) and a specific number of weeks to the past. In other words, the Log Data Source time window shifts. An automatic maintenance task updates the Log Data Source daily (default parameter, the frequency of updates is configurable), so no further action from the user is required.
If Now is not selected, then the Log Data Source has a static time-range and is therefore configured between a particular week and a number of weeks to the past. Once imported to Elasticsearch, the content of this type of Log Data Sources is never updated unless actively synchronized.
Note that, in any case, a Log Data Source can be updated at any time using the Synchronization tab in the Log Data Manager.
Limitations in Import and Synch
To prevent inconsistencies between the content in Log Achieves and Log Data Sources, the system does not allow to perform a synch of a Log Data Source while a Log Archive is importing logs and vice versa; these tasks need to be executed sequentially.
If there is an attempt to execute them at the same time, the system will provide a set of warning and error messages to inform of what is happening.
The data manager’s role
A user in Teneo Studio performs queries on the Log Data Sources made available to them, but cannot create or modify said Log Data Source, nor perform other tasks such as creating Augmenters or managing Saved Queries. These duties, among others, are carried out by the data manager.
The data manager is responsible for the following tasks, illustrated in the diagram below, and described in the upcoming subsections.
Before the solution is published
Before the solution is published, the data manager needs to set up at least one Log Archive and one Log Data Source where the logs generated by the solution will be stored. If the Log Archive is not created, logs will simply not be stored in Cassandra and will be lost.
Other than the configuration in Teneo Manager, before publication the data manager also needs to check with the system administrator or hosting responsible that the following are ready:
- A created Publish Environment ready to publish the solution
- The pipeline configuration file, this file describes how the conversational AI application and the Log Archives are connected.
Once the solution is live
Once the solution has been published, logs will be stored in the configured Log Archive automatically. The Log Data Sources will be updated depending on how they have been configured.
It is also necessary to set up user permissions so that Teneo Studio users will be able to access and/or manage the Log Data Sources for querying. User permissions are managed in Teneo Manager. Note that this task may also be performed before the solution is published, although it is not compulsory.
Working with the Log Data Source
Finally, the Log Data Manager frontend allows to perform certain tasks, such as:
- Synchronize logs after modifying Log Data Sources in Teneo Manager
- Import logs from previous versions of Teneo Studio
- See and import saved results
- Get an overview of the sessions stored in a Log Data Source
- Create and manage Augmenters.
Log data management in Teneo Manager
Log Archives and Log Data Sources, as well as user permissions, are configurable from Teneo Manager.
In Teneo Manager, the user can perform the following tasks:
- Set up, manage, edit, or delete a Log Archive
- To do so, go to Teneo Manager and select the Log Archives menu under Common
- It is recommended setting one independent Log Archive for each published solution
- Set up, manage, edit, or delete a Log Data Source
- This is done at the LDSs menu under Log Archives
- The Until timeframe parameter on a Log Data Source is set in this menu
- Configure user and group permissions to access and edit the Log Data Source
- This is done by clicking the editing button under User/Group Access Roles columns in each Log Data Source.
Log Data Source set-up example
While the specific Log Data Source setup will depend on the project needs and resources available, a standard setup would consist of two Log Data Sources for different types of queries:
- a recent data Log Data Source with 12 weeks of data, this is the default span for a Log Data Source
- a historical data Log Data Source with 52 weeks of data.
Remember that it is always possible to configure an ad-hoc Log Data Source for longer ranges or a specific time period.
Teneo Log Data Manager
Once the Log Data Sources have been configured in Teneo Manager, the Teneo Log Data Manager allows to perform the following tasks:
- Overview the sessions contained in a Log Data Source and its corresponding Log Archive
- Import and manage logs from older Teneo Studio versions
- Create and manage Augmenters.
By default, the Teneo Log Data Manager opens at the Synchronize tab.
Sessions
The Sessions tab in the Teneo Log Data Manager allows to overview all the sessions contained in a particular Log Data Source and the associated Log Archive.
The user may select any of the available Log Data Sources using the dropdown menu in the tab.
The system will display the sessions, organized weekly, available both in Elasticsearch and Cassandra. The user can select to see 10, 25, 50 or 100 weeks at a time using the menu at the bottom.
Synchronize
The Synchronize tab allows you to synchronize any Log Data Source to the latest log content stored in the Log Archive in Cassandra.
To do so, select the Log Data Source to update using the dropdown menu.
The Log Data Manager frontend will summarize the contents of the Log Data Source, mainly the range of logs contained in it.
To start the synchronization, simply press the blue Sync button.
The Teneo Log Data Manager will start the process and displays the synchronization progress in the view.
Note that Augmenters are applied each time a Log Data Source is synchronized.
Synchronization errors
Should any errors occur during synchronization, the system will show an informative message and displays a list of the errors.
Clear LDS contents
Finally, it is possible to clear the contents in the Log Data Source using the Clear button.
The system will ask the user to confirm the deletion and requires the user to type the name of the Log Data Source to proceed with the clear operation.
Import
Log Data was integrated into the Teneo Platform for the 5.0 release, and therefore the log management described here only applies to logs generated by Teneo Studio 5.0 or superior versions.
However, it is possible to work with logs from older versions of Teneo Studio by importing them into an existing Log Archive. To do so, go to the Import tab of the Teneo Log Data Manager, select the destination Log Archive using the dropdown menu and click Import.
The user will need to enter the path (in the hosting machine's file system) for the log data to import. Ask the system administrator for this information.
Note that this functionality replaces the deprecated log importer tool available in previous versions of the Platform.
Import errors
Sessions which, for any reason, fail to import to a Log Archive will be displayed on the screen.
Saved Results
In Teneo Studio, a user can save query results to be able to reuse these in subsequent queries. Note that Saved Results are static, i.e. they are not updated when a Log Data Source is synched or its configuration is changed.
In the Saved Results tab, the user can manage the Saved Results available in each Log Data Source.
Export Saved Results
It is possible to export any of the Saved Results to a .csv or .json file using the Export to menu on the right side of each Saved Result.
The user can also export any or all of the available Saved Results as a .zip file using the Export selected or Export all menus available in the left side of the view.
Import new Saved Results
The user can also import new Saved Results, if these have been exported by the Teneo Studio user in the .json format, by using the Import Result Data.
The system will prompt the user to type the name of the new Saved Results and select the file to import.
Augmenters
Augmenters are applied to logs each time a session is imported to Elasticsearch or when a Log Data Source is synchronized to enrich or summarize log data in a format that can later be accessed by standard queries.
There are two types of Augmenters: Adorners and Aggregators, which are created and managed in the Augmenters tab.
At the Augmenters tab, the user can:
A. Select the Log Data Source to work on using the dropdown menu
B. Import and Export augmenters
C. Manage the Adorners in the Log Data Source
D. Manage the Aggregators in the Log Data Source
E. Manage Pending actions.
Manage augmenters
The following information related to Augmenters is available:
- Applied:
- if 100% is displayed, the current configuration of the Augmenter is applied in the Log Data Source
- if 0% is displayed, the Log Data Source needs to be updated to reflect the latest changes in the Augmenter (see the section Apply, Update and Pending actions for more information)
- Name refers to the name of the Augmenter
- Version is the version of the Augmenter, any time the Augmenter is modified (including enable and disable actions), the version is incremented
- Type states if the Augmenter is TQL or Groovy script
- Keys refers to the Augmenter's queryable properties, they are generated when the Augmenter is created and are unique
- Created specifies the date of creation
- Updated specifies the date of the last update to the Augmenter, this dos not imply that the Log Data Source contains the latest version of the augmented data, see the section Apply, Update and Pending actions for more information
- Status: Enabled or Disabled; if disabled, the Augmenter will not be applied the next time the Log Data Source is updated, see the section Apply, Update and Pending actions for more information.
Note that it is possible to Disable/Enable, Edit and Delete an Augmenter by using the dropdown menu in the right-end of the view of Augmenters.
Import and Export
The Import and Export buttons allow the user to either import or export augmenters to a .zip file.
To import, the user will be requested to select a file; and an informative message will be displayed to confirm when the import has been completed successfully.
Exporting of augmenters will be executed automatically when pressing the Export button.
Create a new augmenter
Adorners and aggregators are created very similarly and therefore this process will be described together.
To create a new adorner or aggregator, click the Add button and select which type of adorner/aggregator to create: TQL (Teneo Query Language) or Groovy script.
TQL adorner/aggregator
To create a new TQL adorner or aggregator, the user has to fill in the following fields:
- Name of the adorner/aggregator
- Solution Revision the augmenter will only be applied to logs belonging to these versions of the solution
- Date Range the augmenter will only be applied to logs belonging to these date ranges
- TQL the command in Teneo Query Language that will create the augmenter(s)
- The keys, selections and constraints of the adorner/aggregator are generated after clicking Preview or Save.
Note on keys:
- Keys are generated automatically based on the TQL command
- It is recommended to follow the naming conventions
- Keys need to be unique, otherwise the augmenter will not be created.
Groovy script adorner/aggregator
Groovy script augmenters have the following fields:
- Name of the adorner/aggregator
- Solution Revision the augmenter will only be applied to logs belonging to these versions of the solution
- Date Range the augmenter will only be applied to logs belonging to these date ranges
- Groovy script the command in Groovy that will create the augmenter(s)
- Adornment Keys these cannot use the words
count,date,weekorversion - Adorner Selection (optional)
- Adorner Constraints (optional)
Apply Update and Pending actions
When an augmenter is created, imported, edited or enabled/disabled, usually the changes are automatically applied to the Augmenter configuration stored in Elasticsearch. However, the data generated by the Augmenter is not modified in the Log Data Source until it is manually updated in the Pending actions menu.
Similarly, every session that is generated on a published solution is imported and augmented with the version of the augmenters that are configured at that point in time. As a result, if a user updates an augmenter but doesn't apply the changes on the Log Data Source, new sessions will be augmented using the new version of the augmenter while all the old sessions already imported will remain augmented with the old version. To apply the new augmenter to older sessions, the user needs to do it manually using the Sync task.