Configuring the Telegraf Data Collector

Overview#

The Telegraf Collector operates as a WebSocket server that accepts connections from Telegraf agents configured with the WebSocket output plugin. It parses incoming InfluxDB Line Protocol (ILP) messages, creates historian tags based on measurements and fields, and buffers the data for storage in Timebase Historian.

Reference the article General Configuration of the Data Collector to learn how to target a historian and dataset and apply security. This article focuses on the specific configuration of the Telegraf data type.

Telegraf Connection#

Connection#

The Telegraf settings are the Settings tab of the instance's Edit drawer. The whole form fits on one page: the listener, the field option and the filter.

Port: The TCP port number on which the WebSocket server listens for incoming Telegraf connections. The standard InfluxDB port is 8086, making it easy to transition from InfluxDB to Timebase Historian without reconfiguring your Telegraf agents. A blank port stops the instance from starting, and it reads Config Fault with the reason.

Bind Address: The network address the listener binds to. A new instance starts on 127.0.0.1, so only a Telegraf agent on the same machine can reach it. Enter the address of a network interface, or leave it blank to listen on every interface, when agents on other machines send to this collector. An instance saved before this setting existed has it blank and keeps listening on every interface.

Access Token: When set, every Telegraf agent must present it, and a connection without it or with a different one is refused. Leave it blank only for a listener that is not reachable from other machines: the collector logs a warning at start when it accepts connections from the network with no token, because anything that can reach the port can then write measurements. The token is stored as a secret and is not shown again after it is saved; leave the field blank when editing to keep the stored one.

Field#

Use Measurement as Field: When enabled, this option adds the InfluxDB measurement name as a field on the created historian tags. This can be useful for organizing and filtering tags when multiple measurements are being collected.

Filter#

Exclusion Filter (Regex): A .NET regular expression (regex) used to exclude metrics from logging; the collector evaluates the regex against each tag name and excludes any tag that matches the pattern, allowing broad subscriptions while preventing unwanted tags from being written to the historian.

How .NET Regex Filtering Works

The .NET regex engine matches your pattern against the full metric name provided in each message; if the name matches the pattern, the collector does not log that metric, which helps keep the historian focused on meaningful operational data.

Simple Contains Match

To exclude any metric containing the word Debug, simply enter Debug into the filter.

Prefix Based Filtering

To exclude all metrics beginning with a specific device prefix, use: ^Filler02_.* which removes Filler02_Speed, Filler02_Temp, and all other metrics starting with Filler02_.

Excluding Classes of Metrics

If alarm metrics follow a known prefix such as Alarm_, you can exclude them using: ^Alarm_.* which keeps the historian from filling with high-frequency alarm chatter.

Matching Multiple Patterns

To exclude metrics belonging to either of two prefixes, use: ^(Filler02_|Capper01_).* which uses .NET grouping and alternation.

Using Negative Lookahead

To keep all metrics except those containing the word Test, use: ^(?!.*Test).* which is a .NET negative lookahead pattern and excludes any name containing Test while allowing everything else.

For a online tutorial in regex or to learn more, we recommend the website RegExr - https://regexr.com/

Telegraf Configuration#

The settings above complete the configuration of the Timebase Telegraf Collector itself. The collector is now ready to accept incoming WebSocket connections and log data to the target historian. What follows in this next section is not configuration of the Collector, but configuration of Telegraf.

Telegraf is the external agent that publishes metrics. It must be pointed at the Collector’s WebSocket endpoint so that the data you are collecting is actually transmitted to Timebase.

To send data to the Timebase Telegraf Collector, configure the Telegraf WebSocket output plugin:

[[outputs.websocket]]
  ## WebSocket endpoint URL: the collector's address and Port
  url = "ws://localhost:8086"

  ## Data format (must be influx for Line Protocol)
  data_format = "influx"

  ## Required when the collector has an Access Token
  [outputs.websocket.headers]
    Authorization = "Bearer <access token>"

  ## Optional: Connection settings
  # connect_timeout = "30s"
  # write_timeout = "10s"

When the agent runs on another machine, url names that machine's route to the collector, and the collector's Bind Address must be an address reachable from it rather than 127.0.0.1. A connection the collector refuses is logged on the collector's side with the reason: a missing or wrong token, or a browser's Origin header.