feat(dds): Add DDS Consumer input plugin with installation guide and …

go.mod

@@ -184,6 +184,7 @@ require (
 	github.com/riemann/riemann-go-client v0.5.1-0.20211206220514-f58f10cdce16
 	github.com/robbiet480/go.nut v0.0.0-20220219091450-bd8f121e1fa1
 	github.com/robinson/gos7 v0.0.0-20240315073918-1f14519e4846
+	github.com/rticommunity/rticonnextdds-connector-go v1.3.5
 	github.com/safchain/ethtool v0.6.2
 	github.com/santhosh-tekuri/jsonschema/v5 v5.3.1
 	github.com/seancfoley/ipaddress-go v1.7.1

go.sum

@@ -2245,6 +2245,8 @@ github.com/rs/cors v1.11.1/go.mod h1:XyqrcTp5zjWr1wsJ8PIRZssZ8b/WMcMf71DJnit4EMU
 github.com/rs/xid v1.2.1/go.mod h1:+uKXf+4Djp6Md1KODXJxgGQPKngRmWyn10oCKFzNHOQ=
 github.com/rs/zerolog v1.13.0/go.mod h1:YbFCdg8HfsridGWAh22vktObvhZbQsZXe4/zB0OKkWU=
 github.com/rs/zerolog v1.15.0/go.mod h1:xYTKnLHcpfU2225ny5qZjxnj9NvkumZYjJHlAThCjNc=
+github.com/rticommunity/rticonnextdds-connector-go v1.3.5 h1:A8dRxKah++XkzMzP5GZa2qlK0Bo8ZS7BA5AuQpQi1mg=
+github.com/rticommunity/rticonnextdds-connector-go v1.3.5/go.mod h1:9AyzIQCg0kF481B98kgpxfYlrx450YXso2dl26NCFHs=
 github.com/russross/blackfriday/v2 v2.0.1/go.mod h1:+Rmxgy9KzJVeS9/2gXHxylqXiyQDYRxCVz55jmeOWTM=
 github.com/russross/blackfriday/v2 v2.1.0 h1:JIOH55/0cWyOuilr9/qlrm0BSXldqnqwMsf35Ld67mk=
 github.com/russross/blackfriday/v2 v2.1.0/go.mod h1:+Rmxgy9KzJVeS9/2gXHxylqXiyQDYRxCVz55jmeOWTM=

plugins/inputs/all/dds_consumer.go

@@ -0,0 +1,5 @@
+//go:build !custom || inputs || inputs.dds_consumer
+
+package all
+
+import _ "github.com/influxdata/telegraf/plugins/inputs/dds_consumer" // register plugin

plugins/inputs/dds_consumer/INSTALL.md

@@ -0,0 +1,133 @@
+# DDS Plugin Installation Guide
+
+This guide provides step-by-step instructions for installing and configuring the DDS Consumer input plugin for Telegraf.
+
+## Prerequisites
+
+1. **RTI Connext DDS**: You must have RTI Connext DDS installed on your system
+   - Download from [RTI Website](https://www.rti.com/free-trial)
+   - Follow RTI's installation instructions for your platform
+
+2. **Go Environment**: Ensure Go is properly installed and configured
+   - Go 1.18 or later is recommended
+
+## Installation Steps
+
+### 1. Set RTI Environment Variables
+
+Before running Telegraf, ensure RTI environment is configured:
+
+#### Linux/macOS:
+```bash
+# Add to your .bashrc or .profile
+export NDDSHOME=/path/to/rti_connext_dds
+export RTI_LICENSE_FILE=/path/to/rti_license.dat
+export LD_LIBRARY_PATH=$NDDSHOME/lib/<arch>:$LD_LIBRARY_PATH
+```
+
+#### Windows:
+```cmd
+set NDDSHOME=C:\path\to\rti_connext_dds
+set RTI_LICENSE_FILE=C:\path\to\rti_license.dat
+set PATH=%NDDSHOME%\bin;<arch>;%PATH%
+```
+
+### 3. Build Telegraf with DDS Plugin
+
+```bash
+cd /path/to/telegraf
+go build ./cmd/telegraf
+```
+
+### 4. Verify Installation
+
+Test that the plugin is available:
+
+```bash
+./telegraf --input-list | grep dds_consumer
+```
+
+## Configuration
+
+### 1. Create DDS XML Configuration
+
+Create an XML file describing your DDS configuration (see `example_config.xml`):
+
+```xml
+<?xml version="1.0"?>
+<dds>
+    <types>
+        <!-- Define your data types -->
+    </types>
+    <domain_participant_library name="MyParticipantLibrary">
+        <!-- Define participants and readers -->
+    </domain_participant_library>
+</dds>
+```
+
+### 2. Configure Telegraf
+
+Add the DDS consumer plugin to your Telegraf configuration:
+
+```toml
+[[inputs.dds_consumer]]
+  config_path = "/path/to/your/dds_config.xml"
+  participant_config = "MyParticipantLibrary::MyParticipant"
+  reader_config = "MySubscriber::MyReader"
+  tag_keys = ["field1", "field2"]
+  name_override = "my_metrics"
+  data_format = "json"
+```
+
+### 3. Test Configuration
+
+```bash
+./telegraf --config /path/to/your/telegraf.conf --test
+```
+
+## Troubleshooting
+
+### Common Issues
+
+1. **RTI License Error**: Ensure `RTI_LICENSE_FILE` points to a valid license
+2. **Library Not Found**: Verify `LD_LIBRARY_PATH` includes RTI libraries
+3. **XML Parse Error**: Validate XML syntax and participant/reader names
+4. **Network Issues**: Check DDS domain ID and network connectivity
+
+### Debug Commands
+
+```bash
+# Test DDS connectivity
+rtiddsping -domainId 0
+
+# Check environment
+echo $NDDSHOME
+echo $RTI_LICENSE_FILE
+
+# Validate XML configuration
+rtiddsgen -validate your_config.xml
+```
+
+## Platform-Specific Notes
+
+### Linux
+- May require additional network configuration for multicast
+- Check firewall settings for DDS traffic
+
+### Windows
+- Ensure Visual C++ Redistributable is installed
+- Check Windows Firewall for DDS traffic
+
+### Docker
+- Use host networking mode for DDS multicast
+- Mount RTI installation and license file
+
+## Support
+
+For RTI Connext DDS specific issues:
+- [RTI Community Forums](https://community.rti.com)
+- [RTI Documentation](https://community.rti.com/documentation)
+
+For Telegraf specific issues:
+- [Telegraf GitHub Repository](https://github.com/influxdata/telegraf)
+- [InfluxData Community](https://community.influxdata.com)

plugins/inputs/dds_consumer/README.md

@@ -0,0 +1,134 @@
+# DDS Consumer Input Plugin
+
+The DDS consumer plugin reads metrics over DDS by creating readers defined in [XML App Creation](https://community.rti.com/static/documentation/connext-dds/5.3.1/doc/manuals/connext_dds/xml_application_creation/RTI_ConnextDDS_CoreLibraries_XML_AppCreation_GettingStarted.pdf) configurations. This plugin converts received DDS data to JSON data and adds to a Telegraf output plugin.
+
+## Configuration
+
+```toml
+[[inputs.dds_consumer]]
+  ## XML configuration file path
+  config_path = "example_configs/ShapeExample.xml"
+
+  ## Configuration name for DDS Participant from a description in XML
+  participant_config = "MyParticipantLibrary::Zero"
+
+  ## Configuration name for DDS DataReader from a description in XML
+  reader_config = "MySubscriber::MySquareReader"
+
+  # Tag key is an array of keys that should be added as tags.
+  tag_keys = ["color"]
+
+  # Override the base name of the measurement
+  name_override = "shapes"
+
+  ## Data format to consume.
+  data_format = "json"
+```
+
+## Prerequisites
+
+- RTI Connext DDS Connector for Go must be installed on the system
+- Valid DDS XML configuration file with defined participants, topics, and data readers
+- Network connectivity to DDS domain
+
+## How it Works
+
+1. The plugin creates a DDS participant using the specified XML configuration
+2. It establishes a DataReader using the configured reader settings
+3. The plugin continuously waits for and processes incoming DDS samples
+4. Each DDS sample is converted to JSON format
+5. The JSON data is parsed into Telegraf metrics using the configured tag keys
+6. Metrics are forwarded to configured Telegraf output plugins
+
+## XML Configuration
+
+The plugin requires an XML configuration file that defines:
+
+- Domain participants
+- Publishers and subscribers
+- Topics and data types
+- QoS settings
+- DataReaders and DataWriters
+
+Example XML structure:
+```xml
+<?xml version="1.0"?>
+<dds>
+    <types>
+        <!-- Define your data types here -->
+    </types>
+
+    <domain_participant_library name="MyParticipantLibrary">
+        <domain_participant name="Zero" domain_ref="MyDomainLibrary::MyDomain">
+            <subscriber name="MySubscriber">
+                <data_reader name="MySquareReader" topic_ref="Square"/>
+            </subscriber>
+        </domain_participant>
+    </domain_participant_library>
+</dds>
+```
+
+## Tag Processing
+
+The `tag_keys` configuration allows you to specify which fields from the DDS data should be treated as tags rather than fields in the resulting metrics. This is useful for:
+
+- Categorizing data by source, type, or other identifiers
+- Creating time series with different tag combinations
+- Filtering and grouping data in downstream processing
+
+## Example Usage
+
+Example configuration files are provided in this directory:
+- `example_config.xml` - Sample DDS XML configuration
+- `example_telegraf.conf` - Sample Telegraf configuration using the DDS plugin
+
+### Generate config with DDS input & InfluxDB output plugins:
+
+```bash
+./telegraf --input-filter dds_consumer --output-filter influxdb config
+```
+
+### Generate a config file with DDS input & file output plugins:
+```bash
+./telegraf --input-filter dds_consumer --output-filter file config > dds_to_file.conf
+```
+
+### Run Telegraf with DDS consumer:
+```bash
+./telegraf --config ./dds_to_file.conf
+```
+
+When running with the `dds_consumer` plugin, ensure that the XML file for DDS configurations is located at the `config_path` specified in your Telegraf TOML config.
+
+## Testing
+
+You can test the plugin with the [RTI Shapes Demo](https://www.rti.com/free-trial/shapes-demo) by:
+
+1. Publishing data with "Square" topic using Shapes Demo
+2. Configuring the plugin to read from the "Square" topic
+3. Observing metrics in your configured output
+
+## Troubleshooting
+
+### Common Issues
+
+1. **DDS Domain Connectivity**: Ensure all participants are on the same DDS domain
+2. **XML Configuration**: Verify XML file path and participant/reader names
+3. **Topic Matching**: Confirm topic names and data types match between publishers and subscribers
+4. **QoS Compatibility**: Check that QoS settings are compatible between writers and readers
+
+### Debug Tips
+
+- Enable debug logging in Telegraf to see detailed plugin operation
+- Use RTI tools like `rtiddsping` to verify DDS connectivity
+- Validate XML configuration with RTI tools before using with Telegraf
+- Check that the RTI Connext DDS environment is properly configured
+
+## Metrics
+
+The plugin generates metrics based on the DDS data received. The metric name can be:
+- Automatically derived from the DDS topic name
+- Overridden using the `name_override` configuration
+- Dynamically set based on data content (if using `json_name_key`)
+
+Fields are created from all numeric data in the DDS samples, while configured tag keys become metric tags for categorization and filtering.