Skip to content

Commit 8e76041

Browse files
kyounghokyoungho
committed
feat(dds): Add DDS Consumer input plugin with installation guide and example configurations
1 parent d5e8ab6 commit 8e76041

File tree

9 files changed

+772
-0
lines changed

9 files changed

+772
-0
lines changed

‎go.mod‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -184,6 +184,7 @@ require (
184184
github.com/riemann/riemann-go-client v0.5.1-0.20211206220514-f58f10cdce16
185185
github.com/robbiet480/go.nut v0.0.0-20220219091450-bd8f121e1fa1
186186
github.com/robinson/gos7 v0.0.0-20240315073918-1f14519e4846
187+
github.com/rticommunity/rticonnextdds-connector-go v1.3.5
187188
github.com/safchain/ethtool v0.6.2
188189
github.com/santhosh-tekuri/jsonschema/v5 v5.3.1
189190
github.com/seancfoley/ipaddress-go v1.7.1

‎go.sum‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -2245,6 +2245,8 @@ github.com/rs/cors v1.11.1/go.mod h1:XyqrcTp5zjWr1wsJ8PIRZssZ8b/WMcMf71DJnit4EMU
22452245
github.com/rs/xid v1.2.1/go.mod h1:+uKXf+4Djp6Md1KODXJxgGQPKngRmWyn10oCKFzNHOQ=
22462246
github.com/rs/zerolog v1.13.0/go.mod h1:YbFCdg8HfsridGWAh22vktObvhZbQsZXe4/zB0OKkWU=
22472247
github.com/rs/zerolog v1.15.0/go.mod h1:xYTKnLHcpfU2225ny5qZjxnj9NvkumZYjJHlAThCjNc=
2248+
github.com/rticommunity/rticonnextdds-connector-go v1.3.5 h1:A8dRxKah++XkzMzP5GZa2qlK0Bo8ZS7BA5AuQpQi1mg=
2249+
github.com/rticommunity/rticonnextdds-connector-go v1.3.5/go.mod h1:9AyzIQCg0kF481B98kgpxfYlrx450YXso2dl26NCFHs=
22482250
github.com/russross/blackfriday/v2 v2.0.1/go.mod h1:+Rmxgy9KzJVeS9/2gXHxylqXiyQDYRxCVz55jmeOWTM=
22492251
github.com/russross/blackfriday/v2 v2.1.0 h1:JIOH55/0cWyOuilr9/qlrm0BSXldqnqwMsf35Ld67mk=
22502252
github.com/russross/blackfriday/v2 v2.1.0/go.mod h1:+Rmxgy9KzJVeS9/2gXHxylqXiyQDYRxCVz55jmeOWTM=

‎plugins/inputs/all/dds_consumer.go‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
//go:build !custom || inputs || inputs.dds_consumer
2+
3+
package all
4+
5+
import _ "github.com/influxdata/telegraf/plugins/inputs/dds_consumer" // register plugin

‎plugins/inputs/dds_consumer/INSTALL.md‎

Lines changed: 133 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,133 @@
1+
# DDS Plugin Installation Guide
2+
3+
This guide provides step-by-step instructions for installing and configuring the DDS Consumer input plugin for Telegraf.
4+
5+
## Prerequisites
6+
7+
1. **RTI Connext DDS**: You must have RTI Connext DDS installed on your system
8+
- Download from [RTI Website](https://www.rti.com/free-trial)
9+
- Follow RTI's installation instructions for your platform
10+
11+
2. **Go Environment**: Ensure Go is properly installed and configured
12+
- Go 1.18 or later is recommended
13+
14+
## Installation Steps
15+
16+
### 1. Set RTI Environment Variables
17+
18+
Before running Telegraf, ensure RTI environment is configured:
19+
20+
#### Linux/macOS:
21+
```bash
22+
# Add to your .bashrc or .profile
23+
export NDDSHOME=/path/to/rti_connext_dds
24+
export RTI_LICENSE_FILE=/path/to/rti_license.dat
25+
export LD_LIBRARY_PATH=$NDDSHOME/lib/<arch>:$LD_LIBRARY_PATH
26+
```
27+
28+
#### Windows:
29+
```cmd
30+
set NDDSHOME=C:\path\to\rti_connext_dds
31+
set RTI_LICENSE_FILE=C:\path\to\rti_license.dat
32+
set PATH=%NDDSHOME%\bin;<arch>;%PATH%
33+
```
34+
35+
### 3. Build Telegraf with DDS Plugin
36+
37+
```bash
38+
cd /path/to/telegraf
39+
go build ./cmd/telegraf
40+
```
41+
42+
### 4. Verify Installation
43+
44+
Test that the plugin is available:
45+
46+
```bash
47+
./telegraf --input-list | grep dds_consumer
48+
```
49+
50+
## Configuration
51+
52+
### 1. Create DDS XML Configuration
53+
54+
Create an XML file describing your DDS configuration (see `example_config.xml`):
55+
56+
```xml
57+
<?xml version="1.0"?>
58+
<dds>
59+
<types>
60+
<!-- Define your data types -->
61+
</types>
62+
<domain_participant_library name="MyParticipantLibrary">
63+
<!-- Define participants and readers -->
64+
</domain_participant_library>
65+
</dds>
66+
```
67+
68+
### 2. Configure Telegraf
69+
70+
Add the DDS consumer plugin to your Telegraf configuration:
71+
72+
```toml
73+
[[inputs.dds_consumer]]
74+
config_path = "/path/to/your/dds_config.xml"
75+
participant_config = "MyParticipantLibrary::MyParticipant"
76+
reader_config = "MySubscriber::MyReader"
77+
tag_keys = ["field1", "field2"]
78+
name_override = "my_metrics"
79+
data_format = "json"
80+
```
81+
82+
### 3. Test Configuration
83+
84+
```bash
85+
./telegraf --config /path/to/your/telegraf.conf --test
86+
```
87+
88+
## Troubleshooting
89+
90+
### Common Issues
91+
92+
1. **RTI License Error**: Ensure `RTI_LICENSE_FILE` points to a valid license
93+
2. **Library Not Found**: Verify `LD_LIBRARY_PATH` includes RTI libraries
94+
3. **XML Parse Error**: Validate XML syntax and participant/reader names
95+
4. **Network Issues**: Check DDS domain ID and network connectivity
96+
97+
### Debug Commands
98+
99+
```bash
100+
# Test DDS connectivity
101+
rtiddsping -domainId 0
102+
103+
# Check environment
104+
echo $NDDSHOME
105+
echo $RTI_LICENSE_FILE
106+
107+
# Validate XML configuration
108+
rtiddsgen -validate your_config.xml
109+
```
110+
111+
## Platform-Specific Notes
112+
113+
### Linux
114+
- May require additional network configuration for multicast
115+
- Check firewall settings for DDS traffic
116+
117+
### Windows
118+
- Ensure Visual C++ Redistributable is installed
119+
- Check Windows Firewall for DDS traffic
120+
121+
### Docker
122+
- Use host networking mode for DDS multicast
123+
- Mount RTI installation and license file
124+
125+
## Support
126+
127+
For RTI Connext DDS specific issues:
128+
- [RTI Community Forums](https://community.rti.com)
129+
- [RTI Documentation](https://community.rti.com/documentation)
130+
131+
For Telegraf specific issues:
132+
- [Telegraf GitHub Repository](https://github.com/influxdata/telegraf)
133+
- [InfluxData Community](https://community.influxdata.com)

‎plugins/inputs/dds_consumer/README.md‎

Lines changed: 134 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,134 @@
1+
# DDS Consumer Input Plugin
2+
3+
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.
4+
5+
## Configuration
6+
7+
```toml
8+
[[inputs.dds_consumer]]
9+
## XML configuration file path
10+
config_path = "example_configs/ShapeExample.xml"
11+
12+
## Configuration name for DDS Participant from a description in XML
13+
participant_config = "MyParticipantLibrary::Zero"
14+
15+
## Configuration name for DDS DataReader from a description in XML
16+
reader_config = "MySubscriber::MySquareReader"
17+
18+
# Tag key is an array of keys that should be added as tags.
19+
tag_keys = ["color"]
20+
21+
# Override the base name of the measurement
22+
name_override = "shapes"
23+
24+
## Data format to consume.
25+
data_format = "json"
26+
```
27+
28+
## Prerequisites
29+
30+
- RTI Connext DDS Connector for Go must be installed on the system
31+
- Valid DDS XML configuration file with defined participants, topics, and data readers
32+
- Network connectivity to DDS domain
33+
34+
## How it Works
35+
36+
1. The plugin creates a DDS participant using the specified XML configuration
37+
2. It establishes a DataReader using the configured reader settings
38+
3. The plugin continuously waits for and processes incoming DDS samples
39+
4. Each DDS sample is converted to JSON format
40+
5. The JSON data is parsed into Telegraf metrics using the configured tag keys
41+
6. Metrics are forwarded to configured Telegraf output plugins
42+
43+
## XML Configuration
44+
45+
The plugin requires an XML configuration file that defines:
46+
47+
- Domain participants
48+
- Publishers and subscribers
49+
- Topics and data types
50+
- QoS settings
51+
- DataReaders and DataWriters
52+
53+
Example XML structure:
54+
```xml
55+
<?xml version="1.0"?>
56+
<dds>
57+
<types>
58+
<!-- Define your data types here -->
59+
</types>
60+
61+
<domain_participant_library name="MyParticipantLibrary">
62+
<domain_participant name="Zero" domain_ref="MyDomainLibrary::MyDomain">
63+
<subscriber name="MySubscriber">
64+
<data_reader name="MySquareReader" topic_ref="Square"/>
65+
</subscriber>
66+
</domain_participant>
67+
</domain_participant_library>
68+
</dds>
69+
```
70+
71+
## Tag Processing
72+
73+
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:
74+
75+
- Categorizing data by source, type, or other identifiers
76+
- Creating time series with different tag combinations
77+
- Filtering and grouping data in downstream processing
78+
79+
## Example Usage
80+
81+
Example configuration files are provided in this directory:
82+
- `example_config.xml` - Sample DDS XML configuration
83+
- `example_telegraf.conf` - Sample Telegraf configuration using the DDS plugin
84+
85+
### Generate config with DDS input & InfluxDB output plugins:
86+
87+
```bash
88+
./telegraf --input-filter dds_consumer --output-filter influxdb config
89+
```
90+
91+
### Generate a config file with DDS input & file output plugins:
92+
```bash
93+
./telegraf --input-filter dds_consumer --output-filter file config > dds_to_file.conf
94+
```
95+
96+
### Run Telegraf with DDS consumer:
97+
```bash
98+
./telegraf --config ./dds_to_file.conf
99+
```
100+
101+
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.
102+
103+
## Testing
104+
105+
You can test the plugin with the [RTI Shapes Demo](https://www.rti.com/free-trial/shapes-demo) by:
106+
107+
1. Publishing data with "Square" topic using Shapes Demo
108+
2. Configuring the plugin to read from the "Square" topic
109+
3. Observing metrics in your configured output
110+
111+
## Troubleshooting
112+
113+
### Common Issues
114+
115+
1. **DDS Domain Connectivity**: Ensure all participants are on the same DDS domain
116+
2. **XML Configuration**: Verify XML file path and participant/reader names
117+
3. **Topic Matching**: Confirm topic names and data types match between publishers and subscribers
118+
4. **QoS Compatibility**: Check that QoS settings are compatible between writers and readers
119+
120+
### Debug Tips
121+
122+
- Enable debug logging in Telegraf to see detailed plugin operation
123+
- Use RTI tools like `rtiddsping` to verify DDS connectivity
124+
- Validate XML configuration with RTI tools before using with Telegraf
125+
- Check that the RTI Connext DDS environment is properly configured
126+
127+
## Metrics
128+
129+
The plugin generates metrics based on the DDS data received. The metric name can be:
130+
- Automatically derived from the DDS topic name
131+
- Overridden using the `name_override` configuration
132+
- Dynamically set based on data content (if using `json_name_key`)
133+
134+
Fields are created from all numeric data in the DDS samples, while configured tag keys become metric tags for categorization and filtering.

0 commit comments

Comments
 (0)