Telegraf Oracle Telemetry Plugin

A Telegraf output plugin that enables Oracle telemetry and streaming metrics to be sent from Telegraf into Oracle Database through Oracle REST Data Services (ORDS).

This plugin allows users to connect Telegraf to Oracle telemetry and streaming infrastructure and publish observability data for monitoring, dashboarding, and operational analytics use cases.

---

Overview

This repository contains a Telegraf output plugin composed of:

• A Telegraf output plugin implemented in Go
• A plugin registration file under plugins/outputs/all
• Plugin documentation and configuration examples

The plugin enables secure metric delivery from Telegraf into Oracle telemetry and streaming infrastructure.

The plugin sends metrics to Oracle through ORDS HTTPS endpoints and uses OAuth2 client credentials for authentication.

---

Authentication

Security is handled by the Torrent DB deployment via OAuth2. The plugin itself only stores and forwards credentials obtained during client registration.

1. Client registration – Torrent DB administrators issue a client_id and client_secret.
2. Secure storage – Store these values in a secure location on the Telegraf host (for example, the Telegraf secret-store).
3. Token acquisition – Telegraf calls the ORDS OAuth endpoint with the client credentials and obtains a short-lived access token.
4. Token refresh – When ORDS returns 401 Unauthorized, the plugin automatically re-requests a fresh access token.
5. Data submission – Telegraf includes the Bearer token on subsequent POST requests to the ingest endpoint, ensuring encrypted data transport.

This repository contains the plugin files that must be merged into a Telegraf 1.35.1 source tree before building Telegraf.

---

Installation

System Requirements

Telegraf Requirements

• Telegraf source version 1.35.1
• Go installed and available in PATH
• GNU Make
• Git
• curl
• tar

Verify:

go version
make --version
git --version
curl --version
tar --version

Oracle Runtime Requirements

• ORDS-enabled Oracle Database
• ORDS workspace configured for telemetry ingest
• ORDS handler that accepts metric payloads
• OAuth2 client credentials for the ORDS workspace

The plugin communicates with ORDS over HTTPS and does not require Oracle Instant Client libraries on the Telegraf host.

Oracle Network Configuration

The Telegraf host must be able to reach the ORDS endpoint.

Verify network access to the ORDS host and port:

curl -k https://<ORDS_HOST>:<ORDS_PORT>/

If a corporate proxy or firewall is used, configure network access before starting Telegraf.

Cloning the Plugin Repository

git clone https://github.com/oracle-samples/telegraf-oracle-telemetry-plugin.git
cd telegraf-oracle-telemetry-plugin

---

Build Instructions

Download Telegraf 1.35.1

Create a clean build directory and download the Telegraf 1.35.1 source archive:

export TELEGRAF_VERSION=1.35.1

mkdir -p telegraf-oracle-build
cd telegraf-oracle-build

curl -LO "https://github.com/influxdata/telegraf/archive/refs/tags/v${TELEGRAF_VERSION}.tar.gz"
tar -xzf "v${TELEGRAF_VERSION}.tar.gz"

Merge the OracleDB Output Plugin

Clone this plugin repository beside the extracted Telegraf source:

git clone https://github.com/oracle-samples/telegraf-oracle-telemetry-plugin.git

Merge the plugin into Telegraf by copying the plugins/outputs files:

cp -R telegraf-oracle-telemetry-plugin/plugins/outputs/* \
  "telegraf-${TELEGRAF_VERSION}/plugins/outputs/"

The copy adds:

telegraf-1.35.1/plugins/outputs/oracledb/
telegraf-1.35.1/plugins/outputs/all/oracledb.go

Build Telegraf

Install Go module dependencies:

cd "telegraf-${TELEGRAF_VERSION}"
go mod download

Build the Telegraf executable:

make telegraf

This generates the Telegraf binary in the current directory:

./telegraf

Verify:

./telegraf version

---

Oracle Database Setup

1. Provision or identify the target ORDS workspace and handler that will receive metrics.
2. Register Telegraf as an OAuth2 client and obtain the client_id and client_secret.
3. Install Telegraf and enable the OracleDB output plugin (see configuration below).
4. Restart Telegraf and monitor the logs to confirm successful token negotiation and metric delivery.

Note: This repository assumes you already have Oracle Database Telemetry Streaming or a similar ingest pipeline available.

Running Telegraf with the Plugin

Create a Telegraf configuration file:

cat > telegraf-oracledb.conf <<'EOF'
[[outputs.oracledb]]
  ## ORDS workspace configuration
  user      = "tsdb"
  workspace = "wksp1"
  handler   = "INGEST"

  ## Endpoint for ORDS
  url  = "https://example.com"
  port = 8085

  ## OAuth client credentials (use secret-store entries when possible)
  client_id     = "@{secretstore:client_id}"
  client_secret = "@{secretstore:client_secret}"

  ## Optional request tuning
  # batch_size = 1000
  # timeout    = "5s"
  # trace      = 0
EOF

Run Telegraf with the configuration file:

./telegraf --config telegraf-oracledb.conf

Run in background:

nohup ./telegraf --config telegraf-oracledb.conf > telegraf-oracledb.log 2>&1 &

Verify logs:

tail -f telegraf-oracledb.log

---

Configuration

[[outputs.oracledb]]
  ## ORDS workspace configuration
  user      = "tsdb"
  workspace = "wksp1"
  handler   = "INGEST"

  ## Endpoint for ORDS
  url  = "https://example.com"
  port = 8085

  ## OAuth client credentials
  client_id     = "@{secretstore:client_id}"
  client_secret = "@{secretstore:client_secret}"

  ## Optional request tuning
  # batch_size = 1000
  # timeout    = "5s"
  # trace      = 0

Configuration Notes

• user, workspace, and handler must match the ORDS objects created during setup.
• url and port identify the ORDS HTTPS endpoint.
• When running on untrusted networks, configure tls_ca and use HTTPS endpoints for the url field.
• client_id and client_secret are OAuth2 client credentials issued for the ingest workspace.
• Use Telegraf secret-store support where available instead of storing plain-text credentials in configuration files.
• batch_size controls how many Telegraf metrics are submitted per ORDS request. Larger batches reduce HTTPS overhead but can delay error feedback.
• timeout controls the HTTP request timeout.
• trace controls plugin trace logging.

---

Project Structure

.
├── .github/                         # GitHub pull request template
├── plugins/
│   └── outputs/
│       ├── all/
│       │   └── oracledb.go          # Registers the OracleDB output plugin
│       └── oracledb/
│           ├── README.md            # Plugin-specific configuration details
│           ├── oracledb.go          # OracleDB output plugin implementation
│           └── oracledb_test.go     # Plugin tests
├── CHANGELOG.md                     # Release history
├── CONTRIBUTING.md                  # Contribution guidelines
├── LICENSE.txt                      # License information
├── README.md                        # Main project README
├── SECURITY.md                      # Security disclosure policy
└── THIRD_PARTY_LICENSES.txt         # Third-party license information

---

Documentation

Telegraf plugin documentation:

• https://github.com/influxdata/telegraf
• https://github.com/influxdata/telegraf/tree/master/docs
• https://github.com/influxdata/telegraf/tree/master/plugins/outputs

Additional plugin-specific documentation is available in:

plugins/outputs/oracledb/README.md

---

Contributing

Contributions are welcome.

To submit improvements or fixes, please follow the steps below:

1. Clone the Repository

   git clone https://github.com/oracle-samples/telegraf-oracle-telemetry-plugin.git
   cd telegraf-oracle-telemetry-plugin

2. Create a New Branch

   git checkout -b <your-branch-name>

3. Download Telegraf 1.35.1 and merge the plugin.

   export TELEGRAF_VERSION=1.35.1
   curl -LO "https://github.com/influxdata/telegraf/archive/refs/tags/v${TELEGRAF_VERSION}.tar.gz"
   tar -xzf "v${TELEGRAF_VERSION}.tar.gz"
   
   cp -R plugins/outputs/* "telegraf-${TELEGRAF_VERSION}/plugins/outputs/"
   cd "telegraf-${TELEGRAF_VERSION}"

4. Build Telegraf.

   go mod download
   make telegraf

5. Run Tests.

   go test ./plugins/outputs/oracledb

6. Commit and Push Your Changes

   git add .
   git commit -m "Describe your changes clearly"
   git push origin <your-branch-name>

7. Open a Pull Request

Create a pull request from your branch to the main branch.

Please ensure:

• The plugin builds successfully with Telegraf 1.35.1.
• Tests pass.
• Add tests whenever possible.
• No unintended files are committed.
• Generated build artifacts are not committed.

Before submitting a pull request, please review the contribution guide.

---

Security

If you discover a security vulnerability, please follow the responsible disclosure process described in the security guide.

---

License

Copyright (c) 2026 Oracle and/or its affiliates.

Released under the Universal Permissive License v1.0

https://oss.oracle.com/licenses/upl/

See:

LICENSE.txt