Installing a collector

The installation of the collector is done by running the install command on the collector binary. The install process will copy the binary to the correct directory and create a service on the host system (=server running the collector).

Requirements

Access and permissions

Permissions in Factry Historian to manage collectors. See PrivilegesPrivileges.

Configured Factry Historian APIAPI settings.

Administration rights on the host system where the collector will run.

Host system

Host operating system:

Linux (32-bit, 64-bit or ARM architecture)

Windows ≥ 10 (32-bit or 64-bit architecture)

Preferably the same machine that hosts the data source, or as close to the production data source as possible. This keeps latency to a minimum when collecting data points.

Depending on the type of collector, a specific OS/CPU build may not be available. Refer to the Download section in the Factry portal for a list of build architectures available for each collector.

Server resources

At least 5GB free disk space (3GB for collector buffering / store and forward, plus 2GB head room).

At least 2GB free RAM (up to 500MB per collector depending on the collector type, plus 1.5GB head room).

Time synchronisation

Access from the collector server to a local or public NTP server.

NTP time synchronisation configured on the collector server, typically handled by a domain controller.

Network

Ability to open a TCP connection from the host system to the Factry Historian server on port 8001 (using gRPC).

Connectivity from the host system to the data source endpoint, e.g. OPC-UA server, MQTT broker, REST API.

The connection from the host system to Factry Historian is outbound only for security purposes

Creating a collector in Factry Historian

In Factry Historian, visit the Collectors page and click the + Create collector button.

Enter a unique name

Optionally enter a description

Optionally choose a default database

Click Submit

A success message should appear signifying the collector has been created. If something went wrong, an error message will appear.

Generate a token

Select the collector you have just created

Press the Generate token button

After pressing the button a modal will open with the generated collector token.

Click Copy to clipboard. You will pass this token as a flag with the install command.

For your information: the collector token contains 4 pieces of important information for the collector

Historian server URL

Historian server REST port

Historian server GRPC port

Collector UUID

Collectors are linked to a corresponding collector user. You can invalidate the generated token in the user overview. Creating a new token will also invalidate the old token after 24 hours.

Getting the binary

Navigate to https://portal.factry.cloud

Once logged in, click Downloads in the header menu

In the Downloads panel:

Select a release channel (Stable)

Select a product (collector type)

Select a version

Select the OS/Platform of the host system

Click Download to download the binary

Manually copy it to the host system (location does not matter).

Start the binary with the collector token

Now that the collector binary is on the host system and a collector token is generated, the collector can be installed.

Open a terminal with administrator rights (powershell or CMD) and navigate to the folder where the collector binary is located e.g. C:\Users\MyUser\Documents\factry

cd "C:\Users\MyUser\Documents\factry"

The following command will register the collector as a system service and start the collector. Using the information in the token, the collector will establish a connection with the Factry Historian server:

replace the filename with your collector binary filename

replace the token after -t with your token (use the surrounding ")

Example on windows

  .\factry-opcua-collector_v2.2.1_windows-x64 install -t "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJhdWQiOiJodHRwOi8vbG9jYWxob3N0OjgwMDAiLCJleHAiOjI0MzcyMDI0MDcsImdycGMtcG9ydCI6IjgwMDEiLCJpYXQiOjE2NDg4MDI0MDcsImlzcyI6ImZhY3RyeS5pbyIsInJlc3QtcG9ydCI6IjgwMDAiLCJ1dWlkIjoiNjgxZmZiNjQtYjE4Ny0xMWVjLWJlNWYtMDI0MmFjMTgwMDAzIn0.RQlzFoi7I-793-sRIe8bGcQAM5fxQ7lHHkUCVcwxNu8"

Example on linux

  chmod +x factry-opcua-collector_v2.2.1_linux-x64
  sudo ./factry-opcua-collector_v2.2.1_linux-x64 install -t "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJhdWQiOiJodHRwOi8vbG9jYWxob3N0OjgwMDAiLCJleHAiOjI0MzcyMDI0MDcsImdycGMtcG9ydCI6IjgwMDEiLCJpYXQiOjE2NDg4MDI0MDcsImlzcyI6ImZhY3RyeS5pbyIsInJlc3QtcG9ydCI6IjgwMDAiLCJ1dWlkIjoiNjgxZmZiNjQtYjE4Ny0xMWVjLWJlNWYtMDI0MmFjMTgwMDAzIn0.RQlzFoi7I-793-sRIe8bGcQAM5fxQ7lHHkUCVcwxNu8"

Install help

Usage:
  opc-ua-collector-v2.2.1 install [flags]

Flags:
  -e, --env stringToString   Environmental value overrides e.g. BATCH_SIZE=200 (default [])
  -h, --help                 help for install
  -i, --installDir string    the directory where the collector will be installed (default "/opt/factry")
  -t, --token string         Collector token
  -u, --user string          The user used to run the service (default "factry-system-user")
  -w, --workDir string       the working directory for the collector (default "/var/opt/factry")

Expected outcome

When the collector is successfully installed and connected to Factry Historian, in the Factry Historian webpage > Collectors, the collector shows an initial state.

See the Troubleshooting section below if this is not the case.

When wanting to move the collector to another host system, refer to the Moving a collector documentation.

Configure the collector

See Collectors, protocols and data formats to configure your collector, depending on the collector type.

Troubleshooting

The collector does not show an Initial state in Factry Historian

Plausible causes:

The URL in the Factry Historian APIAPI settings is not the URL used by the collector. The collector connection URL is configured under Configuration > General > API > URL. If this URL is incorrect, update it, regenerate the collector token, and rerun the installation command.

The API URL of Factry Historian may be correct but not reachable from the collector host. Verify the required network rules with your IT department.

Can't spot your error? Contact Factry support.