This guide shows how to configure and use Tetra OpenLab Agent versions 1.0.x after an Agent is installed.

To install the Agent, see the Tetra OpenLab Agent Installation Guide (v1.0.x).

Agent Management Console Configuration

You can use the Agent Management Console to do the following:

• Configure Agent settings
• Configure OpenLab connection settings
• Run commands

To get started, do the following.

Open the Agent Management Console

To open the Agent Management Console on the host server, do the following:

1. On the Agent's host server, open Windows Programs.
2. In the Windows Programs menu, choose TetraScience Agent OpenLab. The Agent Management Console appears.

Configure the Agent

To configure the Tetra OpenLab Agent after it's installed, do the following:

1. In the Agent Management Console, select the menu icon in the left navigation menu. Then, choose Configuration. The Agent Configuration page appears.

📘

NOTE

The Configuration page provides settings to save, start, and stop the agent along with its connectivity settings to OpenLab software and the Tetra Data Platform (TDP).

2. Configure the Agent by filling out the fields in the following sections on the Configuration page:

• Agent Status
• Windows Task Scheduler
• TDP Connection Configuration
• Agent runtime Settings

Change the Agent's Status

The Agent Status section indicates the current state of the Agent's processing status, which can be either of the following:

• Stopped
• Running

To save, start, or stop the Agent, do the following:

• To save the Agent configuration, choose Save.
• To start the Agent after configuring new settings, choose Start. When the Agent starts, the status indicator shows Running.
• To stop a running Agent, choose Stop. When the Agent stops, the status indicator shows Stopped. (The Stop button can be selected only if the Agent is running.)

Automate Status Checks by Using Windows Task Scheduler

To avoid needing to check the Agent’s service status manually, it’s recommended that you create a Windows task to perform daily status checks.

To create a Windows task, do the following:

1. Under Windows Scheduled Task to check Agent Service Status, choose Yes.
2. For Run Time, enter the time that you want the status check to run each day. If the Agent is stopped, then the scheduled Windows task restarts the Agent service automatically. If the Agent is running, it continues to run, and the Windows task will run at the time you selected.

📘

NOTE

If you manually stop the Agent, the task is removed from Windows Task Scheduler. When you run the Agent without specifying an Agent Group User account, the task runs under the LocalSystem account.

Configure Connector Settings

The Connector section on the Configuration tab provides settings to do any of the following:

• Set the S3 Direct Upload option (activated by default).
• Set the Receive Commands option to allow the Agent to receive commands from the TDP (activated by default).
• Establish a data connection between the Agent and the TDP.
• Specify the Destination Id so that files from multiple Agents can be uploaded to the same Amazon S3 bucket. (Usually, it helps to split the load into multiple agents for scaling horizontally.)

Set the S3 Direct Upload Option

To have the Agent upload files directly to your Amazon Simple Storage Service (Amazon S3) bucket, set the S3 Direct Upload option to Yes. For new installs, Yes is the default setting. When upgrading the Agent, the setting from the previous version of the Agent is retained.

If you choose this option, keep in mind the following:

• If you use the S3 Direct Upload option with a Tetra Data Hub that uses a Generic Data Connector (GDC), you must add an L7 Proxy Connector in the same Hub where you set up the GDC. The port of the L7 Proxy Connector must also be open. For more information, see GDC Connections.

📘

SQLite Database File Backups

To have the Agent automatically perform regular backups of the SQLite database file, set the S3 Direct Upload option to Yes. When you enable this option, the SQLite database file (which stores agent configuration data) is uploaded to the backup bucket in the Tetra Data Lake. If an Agent failure occurs, you can restore the database file from the backup bucket and continue processing.

If you don't use the S3 Direct Upload option, it's recommended that you create periodic backups of the Agent database, which is typically stored in the installation folder under C:\\TetraScience\<agent>\\db. In the event of a failure (for example, if the host server drive is lost), this would enable the data extraction to continue from where it left off, without having to re-upload all of the data.

Allow the Agent to Receive Commands from the TDP

To allow the Agent to securely receive and run commands from the TDP, set the Receive Commands option to Yes. The default setting is No.

To be able to use these APIs, the Receive Commands setting must be set to Yes.

Establish a Data Connection Between the Agent and the TDP

To set up a data connection between the Agent and the TDP, enter the following information in the Connector section on the Configuration tab:

🚧

IMPORTANT

When establishing a connection between the Agent and the TDP, keep in mind the following:

• Agent ID is required.
• The connection URL is required only if you're uploading RAW files to the TDP.
• Before you use your Agent ID and connection URL, it’s strongly recommended that you verify both with your TetraScience Customer Success Team.

1. For Agent Id, enter the Agent’s ID. The Agent ID is a Universal Unique Identifier (UUID) value that’s used to connect the Agent to the TDP. To find your Agent ID, do the following:

• Sign in to the TDP.
• In the left navigation menu, choose Data Sources. Then, choose Agents. The Agents page appears.
• In the AGENT column, find the name of the Agent that you’re configuring. The Agent ID is listed below the Agent name.

2. For Connection Url, enter the complete connection URL of the Connector or integration type that you’re using:

• TDP (No Connector) URL: <https://api.tetrascience-dev.com/v1/data-acquisition/agent/>
• Hub: http://10.100.1.2:8443/generic-connector/v1/agent
• Generic Data Connector (GDC) URL: <http://10.100.1.1:8888/generic-connector/v1/agent>

3. (For “TDP (No Connector)” setups only) If you’re using an Agent without a Connector, make sure that you do the following:

• For Org Slug, enter your organizational slug. To get your organizational slug, see Viewing Organization Details. The organizational slug is required when using a JSON Web Token (JWT). Adding the slug to this field attaches it to the Agent’s API request headers.
• For Authorization, select Add/Edit. Then, enter your JWT in the dialog that appears. To get a JWT, see Generate a JWT for a Service User. Then, choose Save to encrypt and save the JWT. The Agent validates the connection immediately and displays the updated connection status next to the Connection Url field.

🚧

IMPORTANT

If the Upload Raw Files to TDP setting in the Agent Run Time section (this is described later in this page) is set to No, the Agent will not connect to the TDP to upload files. The status here will still show Connected.

Configure Advanced Settings

You can configure the following options by selecting Advanced Settings on the Configuration page:

• Data Connection status check every: Indicates how often the software checks the status of the connection (heartbeat) between the TDP and the Agent. If the TDP doesn't receive a heartbeat message for more than five minutes, the platform assumes that the Agent is offline. The default value is 30 seconds.
• Agent log files upload every: Indicates how often the Agent uploads log files to the Data Lake. The default value is 300 seconds.
• Proxy Settings: Indicates what type of proxy the Agent is using (System or Custom), or if it's not using a proxy (None).
  • System (default setting): Uses the system proxy specified in Windows for the service user. If basic authentication is required, you can specify a username and password for the proxy.
  • Custom: Makes all of the Agent's proxy options configurable, regardless of any other settings. This proxy takes precedence over any existing system proxy or L7 proxy.
  • None: Explicitly configures the Agent service to not use any proxies for web requests.

📘

NOTE

If a system proxy requires credentials, make sure that you enter them in the Proxy Username and Proxy Password fields.

Ensure to check the option Don't use the proxy server for local (internet) addresses

To keep the recommended settings, or to save the new values you entered, choose OK. Only consider changing these values if connection checks (heartbeat) frequency needs to be changed, or if logs files are needed to be uploaded to the TDP at a different frequency.

Configure OpenLab Service Settings and Agent Runtime

To provide the Agent configuration in the run time, including the access to your OpenLab database, you must provide the following information in the Service Settings section of the Configuration page:

Common Settings

• OpenLab Connection String: The connection string to connect to OpenLab. The format is net.pipe://host_name_or_IP/Agilent/OpenLab/ (For example, "net.pipe://10.176.1.241/Agilent/OpenLab").
• User Name: The user name to connect to OpenLab, required for Internal or Windows Domain authentication.
• Password: The password for the user name, required for Internal or Windows Domain authentication.
• Domain: The Windows domain for the user name, required for Windows Domain authentication.
• OpenLab Server Name: Make sure each injection is uniquely identifiable in Amazon S3. The Agent must include the OpenLab server name in the file name. You can manually enter the server name or a unique identifier, or click the Use Current Machine Name button to set it automatically.

🚧

IMPORTANT

LocalHost or 127.0.0.1 are not valid server names.

• Output Folder, enter a valid local path to store the outputted injection temporarily. The files will be removed after successfully uploading to the TDP.
• Project Fetch Job Interval (seconds): This setting is used to specify the interval for fetching projects. The default is 10 seconds.
• Project Scan Job Interval (seconds): This setting is used to specify the interval for scanning projects. The default is 10 seconds.
• Max Parallel Scan Jobs: This setting is used to specify the maximum number of parallel processes to scan projects. The default is 2.
• Project Scan Batch Size: This setting is used to specify the size of the batch for project scan. The batch sizes that you choose need to balance the application’s footprint and overall throughput. The default setting is 20.
• Process Timeout (Hours): This setting is to prevent the child process launched by the Agent to hang due to unhandled exceptions or unknown errors. The default is 3 Hours.
• Retry limit for Upload: This setting is to prevent the upload process from retrying indefinitely when the RAW file fails to upload to TDP. The default is 40.

📘

NOTE

Tetra OpenLab Agent v1.0.x supports exponential backoff retry policy.

Injection Generation Service

• Injection Generation Batch Size: This setting is used to specify the size of the batch for injection generation. The batch sizes that you choose need to balance the application’s footprint and overall throughput. The default setting is 5.
• Injection Generation Max Parallel: This setting is used to specify the maximum number of parallel processes to generate injections. The default is 2.
• Injection Generation Job Interval (Seconds): This setting allows you to specify the waiting period between when injections are generated. The default is 10 seconds.
• Max Retry Count: Retry count for the injection generation failures. The default is 2 times.

Manage the OpenLab Projects That the Agent Scans

To manage which projects from OpenLab the Agent scans and generates, select Project from the left navigation menu. A list of your OpenLab projects that the Agent's OpenLab User can access appears.

Projects are arranged in alphabetical order, maintaining the parent-child relationship that is set up in OpenLab. When new projects are added, the Agent detects them from its periodical scan job and adds those new projects to the Project list automatically.

As a System Administrator, you can select which projects the Agent uses to generate the RAW files. Additionally, the Agent constantly monitors any project changes to detect new and updated Injections.

Review Injection Summaries

To review a summary of injection processing, injection processing errors, result set scan errors, and system health metrics, choose Summary in the left navigation menu. The Summary page appears.

View a Processing Summary

The Processing Summary shows the scan, generation, and upload status of injections for a selected project (or all projects).

The Processing Summary displays the following information:

• Total Scanned: number of Injections scanned by the Agent
• Total Generated: number of scanned Injections for which that RAW files generated
• Failed to Generate: number of scanned Injections that failed to generate a RAW file
• Pending to Generate: number of Injections that have been scanned but not generated yet by the Agent
• Pending Upload: number of generated Injections waiting to be uploaded to the agent
• Uploaded: number of Injections that have been uploaded to the TDP successfully
• Failed to Upload: number of Injections that the Agent failed to upload to the TDP

Review Errors

To review injection and scan errors, review the following error tabs:

• Injection Generation Error tab: shows injections that were scanned but couldn't be generated because of an error (you can regenerate the failed injections by clicking the Regenerate failed injections button)
• Injection Upload Error tab: shows injections that were generated, but couldn't be uploaded to the TDP because of an error
• Result Set Scan Error tab: shows Result Sets that returned access errors during scanning

Review System Messages

The Tetra OpenLab Agent generates host server system metrics every minute and provides the following metrics:

• Available Disk Space (in GB)
• Disk Usage (as a % of the total)
• CPU Usage (as a % of the total)
• Memory Usage (in MB)
• Available Memory (in MB)
• Upload Error Rate
• Scan Access Rate
• Data Connection (connection status between the Agent and the TDP)

Run Commands

You can use the Configure Project Command and TDP Command Service to programmatically notify the Agent to configure an OpenLab project to either upload or stop uploading data to the TDP.

For more information, see Tetra OpenLab Agent Configure Project Command.

Documentation Feedback

Do you have questions about our documentation or suggestions for how we can improve it? Start a discussion in TetraConnect Hub. For access, see Access the TetraConnect Hub.

📘

NOTE

Feedback isn't part of the official TetraScience product documentation. TetraScience doesn't warrant or make any guarantees about the feedback provided, including its accuracy, relevance, or reliability. All feedback is subject to the terms set forth in the TetraConnect Hub Community Guidelines.