Telegraf on AWS User Guide

Overview

This image runs Telegraf, the open source plugin-driven server agent for collecting and reporting metrics, events and logs. With hundreds of input plugins Telegraf gathers telemetry from the host, containers, databases, message queues, cloud services and any StatsD, SNMP, Prometheus or HTTP source, processes and aggregates it, then writes it to dozens of output destinations including InfluxDB, Prometheus, Graphite, Kafka, CloudWatch, OpenTSDB and any HTTP endpoint. The image is delivered as a ready-to-use metrics appliance: telegraf.service is enabled and starts on boot running a self-contained sample pipeline, so the moment an engineer connects over SSH the agent is already collecting host metrics and serving them.

This is a headless metrics-agent service. There is no web interface and no credentials to manage. Telegraf runs as a long-lived daemon installed from the official InfluxData package repository and driven by a simple TOML configuration file at /etc/telegraf/telegraf.conf plus a drop-in directory at /etc/telegraf/telegraf.d/. The built-in Prometheus client output is enabled but bound to loopback only (127.0.0.1:9273), so the metrics endpoint answers on the instance without ever being exposed to the network. The instance security group opens port 22 only; you open whatever scrape or forward ports your own pipeline needs.

The sample file output lives on a dedicated, independently resizable EBS data volume mounted at /var/lib/telegraf. The metrics that the sample pipeline persists as line protocol sit on durable storage rather than the operating system disk, and you can point your own file or buffered outputs at the same volume.

Prerequisites

Before you deploy this image you need:

• An Amazon Web Services account where you can launch EC2 instances
• IAM permissions to launch instances, create security groups, and subscribe to AWS Marketplace products
• An EC2 key pair in the target Region for SSH access to the instance
• A VPC and subnet in the target Region, with a security group allowing inbound port 22 from your management network
• The AWS CLI (version 2) installed locally if you plan to deploy from the command line

Step 1: Launch the Instance from the AWS Marketplace

Sign in to the AWS Management Console, open the EC2 service, and select Launch instance. Under Application and OS Images choose AWS Marketplace AMIs and search for Telegraf. Select the cloudimg listing and choose Select, then Continue on the subscription summary.

Pick an instance type of t3.small or larger. Choose your EC2 key pair under Key pair (login). Under Network settings select your VPC and subnet, and either create or select a security group that opens port 22 from your management network. Leave the root volume at the default size or larger.

Select Launch instance. First boot initialisation takes a few seconds after the instance state becomes Running and the status checks pass; telegraf.service is already running its sample pipeline by the time you can connect.

Step 2: Launch the Instance from the AWS CLI

The following block launches an instance from the cloudimg Telegraf Marketplace AMI into an existing subnet and security group. Replace <ami-id> with the AMI ID shown on the Marketplace listing, <key-name> with your EC2 key pair name, <subnet-id> with your subnet ID, and <security-group-id> with a security group that opens port 22 from your management network.

aws ec2 run-instances \
  --image-id <ami-id> \
  --instance-type t3.small \
  --key-name <key-name> \
  --subnet-id <subnet-id> \
  --security-group-ids <security-group-id> \
  --tag-specifications 'ResourceType=instance,Tags=[{Key=Name,Value=telegraf}]'

When the instance reaches the Running state and its status checks pass, note its public IP address or DNS name from the EC2 console or with aws ec2 describe-instances.

Step 3: Connect to Your Instance

Connect over SSH using your key pair and the login user for your operating system variant.

ssh -i <key-name>.pem ubuntu@<public-ip>

A welcome banner prints the most useful commands, and sudo cat /root/telegraf-info.txt shows the full getting-started notes: what is running, the Prometheus endpoint, where the pipeline configuration lives, the file output path, the common input, processor and output plugins, and how to validate and reload the configuration.

Step 4: Verify the Service

Telegraf runs as a system service that is enabled and started on boot. Confirm the daemon is active:

systemctl is-active telegraf

That prints active. For the full unit status, including the main PID, memory use and the command line the daemon is running, use:

systemctl status telegraf --no-pager

Confirm the installed binary and the Telegraf version, which is pinned to 1.39.0 on this image:

telegraf --version

You should see Telegraf 1.39.0 reported. The telegraf binary is on the system path at /usr/bin/telegraf, and the package installs the telegraf.service systemd unit which runs the agent as the dedicated telegraf user.

Step 5: The Metrics Endpoint

Telegraf ships with a built-in Prometheus client output. On this image it is enabled and bound to loopback only (127.0.0.1:9273), so the metrics endpoint answers on the instance but is never exposed to the network. The endpoint serves a standard Prometheus exposition page with the live host metrics that the sample input plugins collect:

curl -s http://127.0.0.1:9273/metrics | grep -E "^(cpu_usage_idle|mem_used_percent|system_uptime)" | head

You will see the cpu_usage_idle, mem_used_percent and system_uptime measurements with their current values, each tagged with the host. That proves the input plugins are actually collecting host telemetry and the output is actually serving it, not merely loaded. List the metric families the agent is exposing with:

curl -s http://127.0.0.1:9273/metrics | grep "^# TYPE" | head -20

To scrape Telegraf from a Prometheus server, change the listen address in the outputs.prometheus_client block of the configuration to a routable interface and open port 9273 in the instance security group yourself; the read-only endpoint stays private by default.

Step 6: Edit the Pipeline

Telegraf reads its pipeline from a simple TOML configuration file at /etc/telegraf/telegraf.conf, with optional drop-in snippets under /etc/telegraf/telegraf.d/. The shipped configuration is a self-contained sample that needs no external dependencies:

ls /etc/telegraf/

The shipped sample pairs the cpu, mem, disk and system input plugins (real host telemetry on a 10 second interval) with the prometheus_client output (the loopback metrics endpoint) and a file output that persists the metrics as line protocol on the data volume. Read the input and output blocks:

grep -vE "^\s*#|^\s*$" /etc/telegraf/telegraf.conf

To build your own pipeline, enable the plugins you need. Common input plugins collect from your sources: cpu, mem, disk, net and system for the host, docker for containers, postgresql, mysql and redis for databases, kafka for queues, and snmp, prometheus, statsd, http and exec for protocols and custom sources. Chain processor and aggregator plugins (converter, regex, enum, basicstats, histogram) to transform, enrich and roll up the stream. Fan out to output plugins to ship the metrics: influxdb/influxdb_v2, prometheus_client, graphite, kafka, cloudwatch, opentsdb, http and file. The single static binary bundles the entire plugin set, so most sources and destinations need only a configuration block, no extra installs.

After editing the configuration, validate it before reloading, then restart the service to apply your changes. These customer-facing commands test and reload your pipeline:

sudo telegraf --config /etc/telegraf/telegraf.conf --test
sudo systemctl restart telegraf

The --test run loads the configuration, runs one collection cycle and prints the metrics it gathered, then exits without starting the daemon, so it is a quick way to confirm a new input is working. Open whatever scrape or forward ports your pipeline needs in the instance security group.

Step 7: The Data Volume

The sample file output writes to a dedicated EBS volume mounted at /var/lib/telegraf. This keeps the persisted metrics off the operating system disk and lets you resize or snapshot the volume independently. Confirm the mount and watch the metrics flow with:

df -h /var/lib/telegraf
sudo tail -n 4 /var/lib/telegraf/telegraf-metrics.out

The sample output appends the collected metrics as InfluxDB line protocol to /var/lib/telegraf/telegraf-metrics.out, one line per measurement per collection cycle. To grow the volume, expand the EBS volume in the AWS console, then grow the filesystem on the instance with sudo resize2fs on the underlying device. Point your own file or buffered outputs at this volume to give them the same durable, independently resizable storage.

Support

This image is published and supported by cloudimg. Support covers input and output plugin configuration, processors and aggregators, tagging and filtering, metric buffering, routing to your observability backend, the metrics endpoint, and upgrade planning. Contact cloudimg through the support channel listed on the AWS Marketplace listing.

All product and company names are trademarks or registered trademarks of their respective holders. Use of them does not imply any affiliation with or endorsement by them.