# Telegraf

> Plugin-driven server agent for collecting and reporting metrics.

- Category: Monitoring & Observability
- Difficulty: intermediate
- Components: telegraf, influxdb
- Tags: telegraf, metrics, influxdb, agent, plugins
- Source: https://docker.recipes/monitoring/telegraf

## Overview

Telegraf is InfluxData's plugin-driven server agent designed to collect, process, aggregate, and write metrics from diverse sources including system statistics, application metrics, IoT sensors, and third-party APIs. Originally developed as part of the TICK stack (Telegraf, InfluxDB, Chronograf, Kapacitor), Telegraf has become the de facto standard for metrics collection with over 300 input plugins and numerous output destinations, making it one of the most versatile monitoring agents available.

This monitoring stack combines Telegraf's comprehensive data collection capabilities with InfluxDB's purpose-built time-series database engine to create a powerful metrics pipeline. Telegraf continuously gathers metrics from configured sources and pushes them directly to InfluxDB using its native line protocol, while InfluxDB stores and indexes the time-stamped data for fast retrieval and analysis. The push-based architecture ensures reliable data delivery even during network interruptions through Telegraf's built-in buffering and retry mechanisms.

This combination is ideal for infrastructure teams, DevOps engineers, and system administrators who need comprehensive monitoring without the complexity of agent-server architectures like Prometheus. Organizations running hybrid environments, IoT deployments, or custom applications benefit from Telegraf's extensive plugin ecosystem and InfluxDB's flexible querying capabilities through both InfluxQL and Flux languages, making it particularly valuable for teams requiring both operational monitoring and business analytics from the same data store.

## Features

- 300+ input plugins including Docker containers, system metrics, SNMP devices, databases, message queues, and cloud services
- Native InfluxDB line protocol integration with automatic schema creation and tag/field optimization
- Built-in data processing with aggregation, transformation, and filtering processors before storage
- Automatic service discovery for dynamic environments including Docker, Kubernetes, and cloud platforms
- Multiple output destinations supporting simultaneous writes to InfluxDB, Prometheus, Kafka, and other systems
- InfluxDB 2.0 organization and bucket-based data isolation with token-based authentication
- Flux query language support for advanced analytics, predictions, and cross-measurement joins
- Configurable data retention policies and downsampling for long-term storage optimization

## Use cases

- Infrastructure monitoring for servers, containers, and network devices with centralized metrics storage
- IoT sensor data collection and analysis for manufacturing, environmental monitoring, or smart building systems
- Application performance monitoring with custom metrics, database query times, and business KPIs
- DevOps pipeline monitoring including build times, deployment frequencies, and error rates
- Network monitoring through SNMP polling of switches, routers, and other network infrastructure
- Database performance tracking for MySQL, PostgreSQL, MongoDB, and other database systems
- Cloud resource monitoring across AWS, Azure, and GCP with cost and utilization metrics

## Prerequisites

- Minimum 1GB RAM for InfluxDB with additional memory scaling based on cardinality and retention periods
- Port 8086 available for InfluxDB HTTP API and web interface access
- Docker socket access (/var/run/docker.sock) mounted for container monitoring capabilities
- Understanding of time-series concepts including tags, fields, and measurement schemas for optimal data modeling
- Telegraf configuration knowledge for input/output plugin setup and metric collection intervals
- Network connectivity from monitored systems to Telegraf agent for remote monitoring scenarios

## docker-compose.yml

```yaml
services:
  influxdb:
    image: influxdb:2
    container_name: influxdb
    restart: unless-stopped
    environment:
      DOCKER_INFLUXDB_INIT_MODE: setup
      DOCKER_INFLUXDB_INIT_USERNAME: admin
      DOCKER_INFLUXDB_INIT_PASSWORD: ${INFLUXDB_PASSWORD}
      DOCKER_INFLUXDB_INIT_ORG: myorg
      DOCKER_INFLUXDB_INIT_BUCKET: telegraf
    volumes:
      - influxdb_data:/var/lib/influxdb2
    ports:
      - "8086:8086"
    networks:
      - telegraf-network

  telegraf:
    image: telegraf:latest
    container_name: telegraf
    restart: unless-stopped
    volumes:
      - ./telegraf/telegraf.conf:/etc/telegraf/telegraf.conf:ro
      - /var/run/docker.sock:/var/run/docker.sock:ro
    depends_on:
      - influxdb
    networks:
      - telegraf-network

volumes:
  influxdb_data:

networks:
  telegraf-network:
    driver: bridge
```

## .env

```bash
INFLUXDB_PASSWORD=changeme123
```

## Usage notes

- Docs: https://docs.influxdata.com/telegraf/
- InfluxDB UI at http://localhost:8086 - admin/INFLUXDB_PASSWORD
- Create ./telegraf/telegraf.conf or generate: telegraf config > telegraf.conf
- 300+ input plugins: system stats, Docker, SNMP, databases, etc.
- Output to InfluxDB, Prometheus, Kafka, and many more
- TICK stack component - pairs with InfluxDB, Chronograf, Kapacitor

## Troubleshooting

- Error 'database not found' or 401 authentication: Verify InfluxDB initialization completed and bucket 'telegraf' exists with correct token permissions
- High memory usage in InfluxDB: Check metric cardinality using SHOW CARDINALITY and avoid high-cardinality tags like timestamps or UUIDs
- Telegraf metrics not appearing: Verify telegraf.conf output configuration matches InfluxDB organization/bucket and check Telegraf logs for connection errors
- Permission denied accessing Docker socket: Ensure telegraf container user has docker group membership or run with appropriate privileges
- Clock synchronization errors: Verify system clocks are synchronized between Telegraf agents and InfluxDB as time skew affects data ingestion
- Plugin-specific errors in logs: Check plugin documentation for required permissions, credentials, or network access to monitored services

