Yes, You Subscribed Correctly. The OPC UA Client Listener Plugin Has Been Released!

By Jay Clifford / Use Cases, Product
Nov 17, 2022

This article would not be possible without the contribution of Lars Stegman. The OPC UA Client Listener Plugin was his own contribution to a long-standing issue.

Telegraf now includes a new plugin highly anticipated by the community. The OPC UA Client Listener Plugin. So you might be asking yourself: what is the big deal? There was already an OPC UA Plugin — how is this different?

In this blog post, we will discuss the problems solved by the OPC UA subscription plugin and how to set up your first example config.

What is the OPC UA Client Listener Plugin?

The OPC UA Client Listener is an alternative input plugin to the OPC UA Client Reader. The new plugin adds a new feature called a subscription. The best way to describe the role of a listener is through an example.

Let’s suppose we have a robot transporting goods from Sector A to Sector B within a factory. In this instance, the robot writes its state to an OPC UA server. The robot has four states:

1. Loading
2. Unloading
3. Moving
4. Blocked

Here was the last run:

As you can see the transport robot stopped 4 times. However, When using the original OPC UA Input Plugin, Telegraf only reported 2 out of 4 of these events. Why is this? This is due to the fact that the original OPC UA Plugin polled the OPC UA server on each Telegraf interval cycle for new tag readings.

This is one of the fundamental flaws with poll-based solutions working with event data. The OPC UA Client Listener behaves differently. Instead of polling the OPC UA server at each collection interval, the OPC UA client creates a subscription to each node/tag of interest. The OPC UA server will then monitor these nodes/tags for changes and notify the client of these changes. This looks a little more like this:

Then the plugin will be notified of each state change like so:

Loading -> Moving -> Stopped -> Running -> Stopped -> Running -> Stopped -> Running -> Stopped -> Running -> Unloading

There are two primary benefits to subscriptions:

1. As we discovered above, this is the primary way of working with event-based data. The responsibility lies with the OPC UA server to perform the checks on the states of nodes/tags. This greatly guarantees the integrity of your data.
2. Subscriptions also greatly improve network performance. Since you are only reading event changes, it greatly reduces duplicate node/tag state entries.

Although subscriptions are highly recommended as the most performant way to read data from nodes/tags from an OPC UA server, this does not make the OPC UA Client Reader plugin obsolete. There are some use cases which require polling instead — for instance, if you wanted to poll the given state of a tag at a specific time interval. This is mostly for visualization purposes for nodes/tags that have very infrequent state changes. Pick a solution which works for your use case.

Now let’s build a working example!

A working example

For this working example, I will be making use of the Prosys OPC UA Simulation Server. It is a great tool for testing your OPC UA Clients against a real server.

Here are my server connection details:

Let’s start by configuring the connection details of the OPC UA Client Listener plugin:

# Retrieve data from OPCUA devices
[[inputs.opcua_listener]]
  ## Metric name
   name = "Robots"
  #
  ## OPC UA Endpoint URL
   endpoint = "opc.tcp://Jays-MacBook-Pro.local:53530/OPCUA/SimulationServer"
  #
  ## Maximum time allowed to establish a connect to the endpoint.
   connect_timeout = "10s"
  #
  ## Maximum time allowed for a request over the established connection.
   request_timeout = "5s"
  #
  ## The interval at which the server should at least update its monitored items
   #subscription_interval = "100ms"
  #
  ## Security policy, one of "None", "Basic128Rsa15", "Basic256",
  ## "Basic256Sha256", or "auto"
   security_policy = "None"
  #
  ## Security mode, one of "None", "Sign", "SignAndEncrypt", or "auto"
   security_mode = "None"
  #
  ## Path to cert.pem. Required when security mode or policy isn't "None".
  ## If cert path is not supplied, self-signed cert and key will be generated.
  # certificate = "/etc/telegraf/cert.pem"
  #
  ## Path to private key.pem. Required when security mode or policy isn't "None".
  ## If key path is not supplied, self-signed cert and key will be generated.
  # private_key = "/etc/telegraf/key.pem"
  #
  ## Authentication Method, one of "Certificate", "UserName", or "Anonymous".  To
  ## authenticate using a specific ID, select 'Certificate' or 'UserName'
   auth_method = "Anonymous"

If you have worked with the original OPC UA plugin, then most of this will be familiar to you. We essentially:

• Define a name for our measurement. In this case, we will name our measurement “Robot” and use tags to distinguish each robot.
• Define the OPC UA server URL we wish to connect to along with the port.
• The important one to note here is the subscription interval. This setting defines how regularly the server should notify the client of a change. Many OPC UA servers now deploy queues to store monitored state changes. These changes are notified to the client no later than the subscription interval.
• Lastly, define our connection security. Currently, this is set to Anonymous since we are deploying a sample server. If you would like an example of using certificates, you can find that here.

Now that we have defined our Client to Server connection parameters, let’s subscribe to our Robot state. Here is the node/tag we are going to be subscribing to:

For this example, I will be using the simple method of subscribing to this tag. We will look at best practices in another blog post:

## Node ID configuration
  ## name              - field name to use in the output
  ## namespace         - OPC UA namespace of the node (integer value 0 thru 3)
  ## identifier_type   - OPC UA ID type (s=string, i=numeric, g=guid, b=opaque)
  ## identifier        - OPC UA ID (tag as shown in opcua browser)
  ## default_tags      - extra tags to be added to the output metric (optional)
  ##
  ## Use either the inline notation or the bracketed notation, not both.
  #
  ## Inline notation (default_tags not supported yet)
   nodes = [
     {name="status", namespace="3", identifier_type="i", identifier="1008"}
   ]

Again if you have worked with the original OPC UA plugin, this should be equivalent to your current configs:

• Define a list of objects which describe the node/tag we want to subscribe to:
  • Name: used at the field output name. We call this status since the numeric value describes the current state of the robot.
  • Namespace: The namespace is like a container for node/tag ids. In most OPC UA servers it’s defined within the Node/tag ID with the initial ns. ns=3;i=1008
  • Identifier type: Used to describe the OPC UA ID type. This is again usually found within the NodeID address. ns=3;i=1008
  • Identifier: The unique identifier for the node/tag. ns=3;i=1008

You can find the full Telegraf configuration here.

If we now run our config with the following command:

telegraf --debug --config opcua/opc_ua_subscription.conf

You can now see the OPC UA Listener is subscribed to each state change of the node/tag. These changes are collected with the Telegraf buffer until the next flush cycle.

Extra credit

In this instance our robot state changes are mapped to an enumerated value:

• 0 = “Unloading/Reloading”
• 1 = “Stopped”
• 2 = “Running”

We can use the Enum Processor Plugin to convert the numerical representations of these states into a human-readable label. This works great if you are visualizing the state using the Mosaic visualization.

Conclusion

The OPC UA Client Listener Plugin has been a long-expected feature for many community members. We would like to thank Lars Stagman for his contribution to the project once again. I hope this blog helps to illustrate the importance of the new contribution and progressed new use cases with Telegraf.

The new plugin is scheduled to be released in December 2022. If you cannot wait till then, you can build from source or download Telegraf using one of the nightly builds.

If you have any questions, make sure to join our Slack and continue the conversation with the rest of the Telegraf community there!