Set up the PI extractor

The Cognite PI extractor is distributed as a Windows installer (.msi file). When you run the .msi file, a setup wizard guides you through the installation process. The installer creates a Windows service and installs the binary files needed to run the extractor.

Before you start

1. Check the server requirements for the extractor.

2. Make sure the extractor has the following access capabilities in a Cognite Data Fusion (CDF) project:

   • timeseries:read and timeseries:write

   • raw:read, raw:write, and raw:list for state store configured to use CDF RAW.

   • events:read and events:write for logging extractor incidents as events in CDF.

   Tip

   You can use OpenID Connect and your existing identity provider (IdP) framework to manage access to CDF data securely. Read more.

3. Set up a Windows Update schedule. Note that the update may reboot the machine, causing extractor downtime.

4. Download and run the installation files for the extractor from CDF.

   Set Modify permissions

   Set Modify permission under Properties in the installation folder to avoid permission issues.

5. Create a configuration file according to the configuration settings. The file must be in YAML format.

Run as a Windows service

1. Start the PI extractor service using the Windows service or with a command line:

    net start PiExtractor

   The Windows service is named Cognite Pi Extractor 4.3.0, and the command line for the net start and net stop commands is named PiExtractor.

2. Verify that the service is running.

3. Open the Properties for the service and set the Startup type to Automatic (Delayed Start):

4. Verify that the extractor is running.

   If you've configured the extractor to log messages to a file, you'll find the log files in the configured path, for instance, logs/log.txt. These should contain progress messages similar to the example below:

Tip

If you've configured the extractor to push metrics, you can inspect the extractor operation and health in real-time using a Grafana board.

Run the extractor behind a proxy

1. Open and edit the PiExtractor.exe.config file from the installation directory.

2. Add the system.net section under configuration with this content:

   <system.net>
       <defaultProxy>
           <proxy  proxyaddress=""
                   bypassonlocal="True"
           />
           <bypasslist>
               <add address="[a-z]+\.contoso\.com$" />
           </bypasslist>
       </defaultProxy>
   </system.net>

3. Configure the proxy address and bypass rules according to the proxy server you want to use.

4. Restart the extractor service. Read more about the default-proxy-element.

Upgrade the extractor

To upgrade the current extractor version, download and run the .msi file for the new version. The installer detects the current installation directory, updates the software, and keeps the configuration as-is. The sample configuration file is a part of the software package and is overwritten during an extractor upgrade.

1. Download the PI extractor .msi file from CDF.

2. Take note of the currently installed version in case of a rollback and of the service properties in the Properties dialog.

   Resetting custom service properties

   During the upgrade, the installer resets all custom service properties to their default values, such as the service recovery settings.

3. Run the installer.

4. Update the custom service properties you noted in step 2.

5. Verify that the extractor is running and that the version displayed in the Starting PI Extractor logline matches the upgraded version.

6. Check the metrics and verify that the extractor resumes operation.

If you've configured additional services to extract from multiple sources, the installer won't change the settings for these services during upgrades. If you've created multiple services, the following dialog appears during the upgrade:

The installer uses the default options, stops the services, and restarts the services after the upgrade. Otherwise, a server reboot is required to complete the upgrade process.

Uninstall the extractor

1. Run the installer > select Remove the extractor or open Add or remove programs from the control panel.
2. Remove Cognite PI extractor.
3. Optionally, remove the installation directory with the configuration file and logs.
4. Optionally, delete the .msi file.