Add a file tail stream

In a file tail stream, the Formant agent monitors a specified file for changes. Each line appended to the end of the file is ingested as a text datapoint. You can also use regular expressions to ingest data only when a given expression is matched in the file.

This guide will teach you how to add a file tail stream.

Prerequisite: Grant file access

Ensure that the Formant agent has access to the file you want to monitor. You may need to use the chmod command to modify the file's access permissions.

Step 1: Create a file tail stream

In Formant, in the upper-left corner, open the menu and click Settings.
Click Devices, and then click on the device you want to configure.
Click the Telemetry tab, and then click Add Stream.
Click File Tail. This will open the New File Tail Stream configuration window:

Property	Usage
Telemetry stream name	Give the stream a name.
On demand	If ON, this stream will store data locally on your device, and only upload data to Formant when you click Retrieve on-demand data. `Rate limit` controls the rate at which datapoints are added to the on-device buffer. For more information, see On demand streams. If OFF, this stream will ingest periodically. `Rate limit` controls the rate of data ingestion.
Video encoding	Only applicable for `sensor_msgs/Image` and `sensor_msgs/CompressedImage` streams. Choose whether you want images ingested on this stream to be encoded as a video.
Validation schema	Only applicable for JSON and text streams. Choose a configuration schema for this stream.
File name	Provide the the absolute path to the file you want Formant to monitor for changes. Formant must have read access to this file.
Regular expression (optional)	If you provide a regular expression, each new line in this file will be searched. If the regular expression is matched, it will be ingested. You can use this to filter for specific data. For example, `ERROR*` will only ingest lines with the string `ERROR` and everything after it on that line. For more information on matching regular expressions and syntax, see GitHub: Google re2 syntax. If this field is left blank, the entire line will be ingested.
Add tags (e.g. `key: value`) (optional)	Add tags to each datapoint of this stream. For more information on tags, see Configure access levels.
Rate limit (Hz) (optional)	If `On demand` is ON: Set the rate at which data is added to the on-device buffer. Data in the on-device buffer will be ingested by the agent when you click Retrieve on-demand data. For more information, see On demand streams. If `On demand` is OFF: Set the rate at which data is ingested. The default rate is 0.5 Hz.

📘
File tracking behavior
You can configure whether a file tail stream will ingest any file with the name specified, or follow the file specified, even if it later changes name. This is controlled by the FORMANT_POLL_FILE_TAILING environment variable.
When FORMANT_POLL_FILE_TAILING is set to true, file tail streams will ingest from any file with the file name specified, even if the original file is renamed and a new file is created with the same name
When FORMANT_POLL_FILE_TAILING is set to false, file tail streams will follow the original file specified, even if it is later renamed.
For more information, see Environment variables for the agent.

When you're finished configuring your stream, click Done, and then Save.

Step 2: Add stream to a view

Once you've added a stream to your device, your next step is to add it to a view in Formant.

Add the streams you want to visualize, and then move on to Viewing data in Formant.

👋
If you notice an issue with this page or need help, please reach out to us! Use the 'Did this page help you?' buttons below, or get in contact with our Customer Success team via the Intercom messenger in the bottom-right corner of this page, or at [email protected].

Updated 3 days ago