Birst Cloud Agent

Note: With each major Birst release, you must upgrade your Birst Cloud Agents to ensure access to the latest functionality as well as proper SQL database connectivity. Birst Cloud Agents must run the same Birst version as your Birst server. Starting with 7.8, Birst Cloud Agents must run the same Birst version as your Birst server.

The Birst Cloud Agent is a lightweight cloud managed Java application that enables you to make connections to sources behind your organization's firewall for extract to Birst or for Live Access to the sources behind a firewall.

The Birst Cloud Agent is an account level agent that you can use for multiple spaces.

Birst Connect 2.0 is a Java command line application that helps extract data from JDBC data sources into Birst.

Important: Birst Connect 2.0 should only be run with Java JDK 8.

It can enable Birst Live Access connections to sources in other networks. It uses HTTPS as the means of transferring data to Birst. Birst Connect 2.0 runs behind your firewall to access your organization’s data sources. Birst Connect 2.0 agents can be downloaded and run on both Windows and Linux machines. Currently, JDBC data sources are supported.

Birst supplies a MSSQL Server JDBC driver with Birst Connect 2.0. You will need to download and install the appropriate JDBC driver for your data source(s). (i.e. Oracle, SAP, MYSQL, etc.)

Birst Cloud agents enable Birst Connect 2.0 to support multiple configurations for the same space. This is useful when multiple data sources are distributed across the network, such that they are not all accessible from a single machine. Having multiple configurations allow users to run separate instances of Birst Connect 2.0 from different machines within the network. In addition, you can employ multiple Birst Cloud Agents per connection for enhanced performance via load balancing. A single Birst Cloud Agent can serve multiple spaces. The Agent default thread pool size is set to 8 but can be modified up to 12 by editing the agent properties file.

A connection defined with Birst Connect 2.0 can pull data from several different sources for which extraction can be scheduled using Birst’s cloud connector scheduler. For more information about Scheduling Extraction and Data Processing for Cloud Applications, see Scheduling Extraction and Data Processing for Cloud Applications

When pulling data from a database, users can select entire database tables and views for upload or pull subsets of data via custom SQL select statements (Query Objects).

Installing the Birst Cloud Agent

Click the Download Local Agent button to download the zipped file for the agent.

You can retrieve the zipped file for the Birst Cloud Agent from your download directory.
Extract the contents of the zipped file to the desired location. (On your local machine or to a remote dedicated server)
Open the BirstCloudAgent directory.
Open the bin directory and run the Agent For Windows Batch File, Mac XXX file) by double-clicking.(For Windows: execute the “Agent.bat”, for Mac/UNIX/Linux, run the “Agent” script).
1. MAC users may get a security pop up saying, “Agent is a Unix application downloaded from the Internet". If this occurs, click Open on this dialog box, or go to your Mac System Preferences > Security and Privacy > General Tab to open the application from there. Alternatively, you can run the Agent by opening a Terminal window, navigating to the /bin directory in the folder in which you unzipped the Agent files, and run the command: “./Agent” without the quotes. Note: Birst Connect requires the installation of Java JDK 8 on the machine where the Agent is running. The Birst Connect 2.0 agent is not certified on Java JDK 9.

With the Agent running, select your local agent from the Create Connection panel. Note: By default, the agent name is inherited from the machine name where the agent is running. You can rename the agent if desired. See Rename a Birst Cloud Agent for more details. Note: Agent name should be unique in case of multiple agents on the same machine.

Tip: To close the Local Agent Selection box, click the drop-down arrow again.

Birst can delete unwanted or duplicate BirstCloud Agents. Note: Users will only be able to delete their own Birst Cloud Agents unless they are a Birst Account Administrator. Account Administrators will have permissions to delete any Birst cloud Agent.

Users can now filter out inactive agents.

Users can reduce the number of displayed cloud agents based on their selection.

Rename a Birst Cloud Agent

To rename your Birst Cloud Agent, click the Manage Agent button to open the Administer Cloud Agent page.

Select the agent you want to rename, right-hand click and select the Rename option. Then provide the new name for the selected agent.

Running a Birst Cloud Agent as a Windows Service

It is possible to run a Birst Cloud Agent as a Windows service so that you can ensure the Agent can serve requests if the machine is up and running, or upon a restart if the service / machine goes down.

This means:

The Agent will automatically start in case of failure
The agent will keep running regardless of who is logged into the machine running the Birst cloud Agent

Note: See the Birst Cloud Agent Readme.txt file for more details in the Birst Cloud Agent directory.

Birst Cloud Agent Installation and Upgrade Notes

Birst Connect 2.0 must run in a location that can access the data that you want to extract and then post that data to the Birst server.
Birst Cloud Agents can run on Windows, Mac, or Unix systems.
There are no specific hardware requirements for Birst Connect 2.0. The processing and memory requirements are small.
Communication runs over HTTPS using TLS 1.2.
Server name, database name, user name, and generic connection strings can use single-value constant variables. See Creating Variables

Important: We recommend updating your Agent(s) after each major Birst release. For more details on how to upgrade your Birst Cloud Agent, see Upgrade a Birst Cloud Agent.

Starting Birst Cloud Agent on a Linux environment with version 7.7.2 or later

If you start Birst Cloud Agent with a version of 7.7.2 or later on aLinux environment, it is possible for Birst Cloud Agent to fail and become stuck during startup. Customers must install rng-tools on the Unix environment where Birst Cloud Agent is running. Use these steps to launch and use a version of Birst Cloud Agent of 7.7.2 of later on a Unix environment:

Open the terminal.
Specify and run the command yum install rng-tools.
Run service rngd start to start the service.
Run service rngd status to check the status of the rngd service.
Run service rngd stop to stop the service.
After the rngd service is started, you can launch Birst Cloud Agent 7.7.2 or later.

BirstCloud Agent Memory

The Birst Cloud Agent streams data to the server without requiring a large amount of memory.

Birst requires a 64-bit JVM (Java Virtual Machine) for running the Agent with a minimum of 2 GB RAM (system memory) for optimum performance. The Agent uses default minimum and maximum memory available to a java process (which is based on the available RAM). Higher RAM can be helpful as it reduces the garbage collection frequency, but it will not have any other impact.

Birst Cloud Agent Properties

Property	Default Value	Description
com.birst.thread.poolsize	8	Maximum concurrent execution of extraction tasks on the Agent. Increasing the pool size increases the load on the Agent especially during extraction (CPU and memory usage). Doing higher number of concurrent operations could also increase the load on the database. A minimum of 1 thread should be set to allow upgrading the agent.
com.birst.thread.priority.poolsize	8	Maximum concurrent execution of Live Access query, preview, fetch schema/table tasks on the Agent.
com.birst.url	See description	The server that the Agent sends response to. This is defaulted to the URL from where the Agent is downloaded. It is not usual to change this property. Advanced users can do this if necessary in consultation with support.
com.birst.agent.name	See description	The name of the Agent as seen in the Birst HTML user interface. The user selects/identifies an agent based on the Agent name. If not provided, the name defaults to the machine name from which the Agent is launched. It is strongly recommended to provide a name before starting up the Agent.
com.birst.agent.description	See description	Text which helps user provide description about the Agent.
com.birst.agent.id	See description	The Agent id is empty when an Agent is downloaded. When starting the Agent, the server registers the Agent and assigns an id to it which will automatically be updated in the properties file. The Agent uses the id for internal mapping of Agent usage in connections. This field should not be updated by the user.
com.birst.sslcontext.protocol	TLSv1.2	The SSL protocol used, this should be changed only when Java supports a higher updated protocol above the default.
com.birst.request.ignoreSSLCertificates	false	Update is needed only on Birst appliance if the Birst server doesn't have valid certificates for HTTPS. In such a case the property should be set to true. When using Java 1.7 (as compared to Java 8), certain SSL certificate authorities (e.g. COMODO CA Limited) are not recognized and this property would be needed to be set to true, even if browser shows the connection as valid SSL connection.
com.birst.request.retry.count	5	If the Birst server isn’t available when the Agent tries to communicate with it, a re-try mechanism exists. The number of re-tries attempted is controlled by this property.
com.birst.request.retry.basesleep	10	Time in milliseconds after which the first re-try will be done. Subsequent re-tries will happen after exponential time duration (e.g 10, 100, 1000, 10000).
com.birst.request.retry.maxsleep	60000	Maximum time between two re-retries.
com.birst.request.timeout	60000	Time duration allowed for HTTP operations to the server (preview response, LA response, get table/schema response), after which the operation will be marked as failed as and a re-try will be attempted. This should only be increased if you are on a slow network and communication to Birst servers is taking longer than normal.
com.birst.upload.timeout	300000	Time duration allowed for HTTP operations to the server (upload of extract request), after which the operation will be marked as failed as and a re-try will be attempted. This should be increased only if you are on a slow network and communication to Birst servers is taking longer than normal.