Aller au contenu
Outils medium

Telegraf : l'agent de collecte qui supporte tout

26 min de lecture

logo telegraf

Telegraf est un agent de collecte de métriques qui s’installe sur vos serveurs pour récupérer CPU, mémoire, Docker, PostgreSQL, Redis — et des centaines d’autres sources — puis envoyer le tout vers Prometheus, InfluxDB, OpenTelemetry Collector ou n’importe quel autre backend.

Ce guide vous montre comment démarrer : installation, premier pipeline fonctionnel, et connexion à vos backends.

Vous gérez un serveur qui fait tourner PostgreSQL, Redis et une application Docker. Pour monitorer tout ça, vous devez :

Fenêtre de terminal
# Métriques système ? Pas de format standard
cat /proc/meminfo | grep MemAvail # → Valeur brute en Ko
# PostgreSQL ? Il faut écrire des requêtes SQL
psql -c "SELECT * FROM pg_stat_database;" # → Résultat tabulaire
# Docker ? Encore une autre API
curl --unix-socket /var/run/docker.sock http://localhost/containers/json # → JSON

Résultat : vous vous retrouvez avec 3 scripts, 3 formats, 3 façons de parser… et une dette technique qui s’accumule.

Avec Telegraf, une seule configuration collecte tout, normalise tout, et envoie tout :

Architecture Telegraf : Inputs → Processors → Aggregators → Outputs

Pourquoi c’est mieux :

Sans TelegrafAvec Telegraf
Un script par sourceUne config déclarative
Formats hétérogènesFormat unifié (InfluxDB line protocol)
Push ou pull selon la sourceTelegraf s’en occupe
Maintenance des scriptsPlugins maintenus par la communauté
Une destination à la foisMulti-destination native

Telegraf fonctionne comme une chaîne de montage : les données entrent d’un côté (inputs), passent par des postes de transformation (processors), peuvent être agrégées (aggregators), puis sortent vers vos backends (outputs).

Pipeline Telegraf : Inputs → Processors → Aggregators → Outputs

Imaginez que vous vouliez :

  1. Collecter le CPU, la mémoire ET les métriques PostgreSQL
  2. Renommer certains champs pour qu’ils correspondent à vos conventions
  3. Filtrer les conteneurs de test pour ne garder que la prod
  4. Envoyer le tout vers Prometheus ET InfluxDB simultanément

Avec Telegraf, vous configurez chaque étape indépendamment. Pas de code à écrire.

Les inputs interrogent les sources et récupèrent les métriques. C’est le point d’entrée de votre pipeline.

InputCe qu’il collecteCas d’usage
cpuUtilisation CPU par cœurMonitoring système
memMémoire utilisée/disponibleMonitoring système
dockerMétriques conteneursEnvironnements conteneurisés
postgresqlStats BDD, locks, queriesMonitoring base de données
prometheusScrape endpoints /metricsRécupérer des métriques existantes
httpAppel HTTP + parsing JSONAPIs custom

Les processors modifient les métriques après collecte. C’est ici que vous normalisez, enrichissez ou filtrez.

ProcessorCe qu’il faitExemple concret
renameRenomme champs/tagscpu_usage_idlecpu_idle
regexExtrait avec des regexExtraire dc=paris du hostname srv-paris-01
filterSupprime des métriquesExclure les conteneurs dont le nom contient test
converterChange les typesString → Integer pour les calculs

Les aggregators calculent des statistiques sur une fenêtre temporelle. Utile pour réduire le volume ou obtenir des vues synthétiques.

AggregatorCe qu’il calculeQuand l’utiliser
basicstatsmin, max, mean, stdevVue d’ensemble statistique
histogramDistribution en bucketsAnalyser la distribution des latences
mergeFusionne plusieurs métriquesConsolider des sources similaires

Les outputs transmettent les métriques aux backends. Vous pouvez en avoir plusieurs — les mêmes données partent vers tous les outputs.

OutputDestinationMode
prometheus_clientPrometheusPull (exposition endpoint)
influxdb_v2InfluxDB 2.xPush
kafkaKafkaPush
fileFichier localDebug
Fenêtre de terminal
# Télécharger et vérifier la clé GPG (fingerprint officiel)
curl --silent --location -O https://repos.influxdata.com/influxdata-archive.key
# Vérifier l'empreinte avant import
gpg --show-keys --with-fingerprint --with-colons ./influxdata-archive.key 2>&1 \
| grep -q '^fpr:\+24C975CBA61A024EE1B631787C3D57159FC2F927:$' \
&& echo "Fingerprint OK" || echo "ERREUR: fingerprint invalide"
# Installer la clé dans le keyring dédié
cat influxdata-archive.key \
| gpg --dearmor \
| sudo tee /etc/apt/keyrings/influxdata-archive.gpg > /dev/null
# Ajouter le repo avec signature
echo 'deb [signed-by=/etc/apt/keyrings/influxdata-archive.gpg] https://repos.influxdata.com/debian stable main' \
| sudo tee /etc/apt/sources.list.d/influxdata.list
# Installer
sudo apt-get update && sudo apt-get install telegraf
# Vérifier l'installation
telegraf version

Résultat attendu :

Telegraf 1.37.1

Créons un pipeline qui collecte les métriques système et les affiche.

  1. Générer une configuration de base

    Fenêtre de terminal
    telegraf config \
    --input-filter cpu:mem:disk \
    --output-filter file \
    > telegraf.conf
  2. Simplifier la configuration

    Éditez telegraf.conf pour ne garder que l’essentiel :

    telegraf.conf
    [agent]
    interval = "10s"
    round_interval = true
    hostname = "mon-serveur"
    # Collecter CPU
    [[inputs.cpu]]
    percpu = false
    totalcpu = true
    # Collecter mémoire
    [[inputs.mem]]
    # Collecter espace disque
    [[inputs.disk]]
    ignore_fs = ["tmpfs", "devtmpfs"]
    # Afficher dans le terminal
    [[outputs.file]]
    files = ["stdout"]
  3. Tester le pipeline

    Fenêtre de terminal
    telegraf --config telegraf.conf --test

    Résultat attendu :

    > cpu,cpu=cpu-total,host=mon-serveur usage_idle=95.2,usage_system=2.1,usage_user=2.7 1707465600000000000
    > mem,host=mon-serveur available=6442450944i,total=8589934592i,used=2147483648i 1707465600000000000
    > disk,device=sda1,host=mon-serveur,path=/ free=42949672960i,total=107374182400i,used=64424509440i 1707465600000000000
  4. Lancer en continu

    Fenêtre de terminal
    # Mode debug pour voir ce qui se passe
    telegraf --config telegraf.conf --debug

    Appuyez sur Ctrl+C pour arrêter.

Modifiez la configuration pour exposer un endpoint /metrics :

telegraf.conf
[agent]
interval = "10s"
hostname = "mon-serveur"
[[inputs.cpu]]
percpu = false
totalcpu = true
[[inputs.mem]]
[[inputs.disk]]
ignore_fs = ["tmpfs", "devtmpfs"]
# Exposer pour Prometheus sur le port 9273
[[outputs.prometheus_client]]
listen = ":9273"
metric_version = 2
path = "/metrics"
  1. Lancer Telegraf

    Fenêtre de terminal
    telegraf --config telegraf.conf
  2. Vérifier l’endpoint

    Fenêtre de terminal
    curl http://localhost:9273/metrics

    Résultat :

    # HELP cpu_usage_idle Telegraf collected metric
    # TYPE cpu_usage_idle gauge
    cpu_usage_idle{cpu="cpu-total",host="mon-serveur"} 94.5
    # HELP mem_available Telegraf collected metric
    # TYPE mem_available gauge
    mem_available{host="mon-serveur"} 6.442450944e+09
  3. Configurer Prometheus pour scraper Telegraf

    Ajoutez dans prometheus.yml :

    scrape_configs:
    - job_name: 'telegraf'
    static_configs:
    - targets: ['localhost:9273']

Enrichissons le pipeline avec des métriques applicatives.

telegraf.conf
[agent]
interval = "10s"
hostname = "mon-serveur"
[global_tags]
environment = "production"
# === SYSTÈME ===
[[inputs.cpu]]
percpu = false
totalcpu = true
[[inputs.mem]]
[[inputs.disk]]
ignore_fs = ["tmpfs", "devtmpfs"]
# === DOCKER ===
[[inputs.docker]]
endpoint = "unix:///var/run/docker.sock"
gather_services = false
container_name_exclude = ["telegraf*"]
timeout = "5s"
perdevice = true
# === POSTGRESQL ===
[[inputs.postgresql]]
address = "postgres://telegraf:password@localhost/postgres?sslmode=disable"
# === OUTPUT ===
[[outputs.prometheus_client]]
listen = ":9273"
metric_version = 2
MétriqueDescription
docker_container_cpu_usage_percentUtilisation CPU par conteneur
docker_container_mem_usageMémoire utilisée par conteneur
docker_container_net_rx_bytesTrafic réseau reçu
docker_container_blkio_io_service_bytes_readI/O disque lecture
MétriqueDescription
postgresql_numbackendsConnexions actives
postgresql_xact_commitTransactions commitées
postgresql_blks_hitCache hits
postgresql_deadlocksNombre de deadlocks
telegraf-daemonset.yaml
apiVersion: apps/v1
kind: DaemonSet
metadata:
name: telegraf
namespace: monitoring
spec:
selector:
matchLabels:
app: telegraf
template:
metadata:
labels:
app: telegraf
spec:
serviceAccountName: telegraf
containers:
- name: telegraf
image: telegraf:1.37.1 # Toujours pinner la version
env:
- name: HOSTNAME
valueFrom:
fieldRef:
fieldPath: spec.nodeName
- name: INFLUXDB_TOKEN
valueFrom:
secretKeyRef:
name: telegraf-secrets
key: token
volumeMounts:
- name: config
mountPath: /etc/telegraf
- name: docker-socket
mountPath: /var/run/docker.sock
readOnly: true
- name: proc
mountPath: /host/proc
readOnly: true
- name: sys
mountPath: /host/sys
readOnly: true
resources:
limits:
memory: 256Mi
cpu: 200m
requests:
memory: 128Mi
cpu: 100m
volumes:
- name: config
configMap:
name: telegraf-config
- name: docker-socket
hostPath:
path: /var/run/docker.sock
- name: proc
hostPath:
path: /proc
- name: sys
hostPath:
path: /sys
telegraf-configmap.yaml
apiVersion: v1
kind: ConfigMap
metadata:
name: telegraf-config
namespace: monitoring
data:
telegraf.conf: |
[global_tags]
cluster = "production"
[agent]
interval = "10s"
round_interval = true
hostname = "$HOSTNAME"
[[inputs.cpu]]
percpu = true
totalcpu = true
[[inputs.mem]]
[[inputs.kubernetes]]
url = "https://kubernetes.default.svc"
bearer_token = "/var/run/secrets/kubernetes.io/serviceaccount/token"
insecure_skip_verify = true
[[outputs.prometheus_client]]
listen = ":9273"
[[inputs.internal]]
collect_memstats = true

Métriques disponibles :

  • internal_agent : état de l’agent
  • internal_gather : temps de collecte
  • internal_write : temps d’écriture
Fenêtre de terminal
# Vérifier la config (dry-run)
telegraf --config telegraf.conf --test
# Afficher la version
telegraf version

Avec inputs.internal, surveillez ces métriques :

MétriqueSeuil d’alerteSignification
internal_write.errors> 0 sur 5 minÉchecs d’écriture vers le backend
internal_gather.errors> 0 sur 5 minÉchecs de collecte (input down)
internal_agent.metrics_dropped> 0Buffer saturé, métriques perdues
Scrape absent2× intervalAgent down ou réseau coupé
  1. Utilisez des variables d’environnement

    token = "${INFLUXDB_TOKEN}"
  2. Filtrez au niveau de l’input

    Évitez de collecter des métriques inutiles.

    [[inputs.disk]]
    ignore_fs = ["tmpfs", "devtmpfs"]
  3. Limitez la cardinalité

    Évitez les tags à haute cardinalité (IDs uniques).

  4. Testez avant de déployer

    Fenêtre de terminal
    telegraf --config telegraf.conf --test
  5. Monitorez Telegraf lui-même

    Activez inputs.internal pour surveiller les performances.

SymptômeCause probableSolution
Plugin non trouvéVersion Telegraf trop anciennetelegraf --version puis mettre à jour
Error in plugin: permission deniedAccès socket/fichier refusésudo usermod -aG docker telegraf
Timeout inputSource lente ou inaccessibleAugmenter timeout dans la config input
metric buffer limit reachedTrop de métriques en attenteAugmenter metric_buffer_limit ou réduire les inputs
Métriques dupliquéesPlusieurs instances scrapent la même sourceVérifier qu’un seul Telegraf collecte chaque source
Pas de métriques DockerSocket inaccessibleVérifier /var/run/docker.sock et permissions
Erreur PostgreSQLCredentials invalidesTester avec psql la chaîne de connexion
Fenêtre de terminal
# Mode debug complet
telegraf --config telegraf.conf --debug
# Tester uniquement l'input CPU
telegraf --config telegraf.conf --input-filter cpu --test
# Tester uniquement l'output Prometheus
telegraf --config telegraf.conf --output-filter prometheus_client --test
# Générer une config complète (utile pour explorer les options)
telegraf config > telegraf.full.conf
# Lister les plugins disponibles
telegraf --input-list
telegraf --output-list
Fenêtre de terminal
# Endpoint Prometheus exposé ?
curl -s http://localhost:9273/metrics | head -20
# Combien de métriques ?
curl -s http://localhost:9273/metrics | grep -v "^#" | wc -l
# Métriques d'un input spécifique
curl -s http://localhost:9273/metrics | grep "docker_"
AgentPoints fortsQuand l’utiliser
TelegrafDes centaines de plugins, très bon pour métriques infra + servicesStack InfluxDB, ou besoin de collecter PostgreSQL/Redis/Docker
OTel CollectorStandard OTLP, normalisation, routing multi-backendsPipeline unifié logs + metrics + traces, vendor-agnostic
VectorTransformations puissantes, très performantPipelines logs complexes, enrichissement avancé
Fluent BitUltra léger, CNCFK8s/edge, logs principalement

Telegraf peut exporter ses métriques en OTLP vers un Collector :

telegraf.conf
[[outputs.opentelemetry]]
## Endpoint OTLP gRPC du Collector
service_address = "otel-collector:4317"
## Attributs OpenTelemetry ajoutés à toutes les métriques
[outputs.opentelemetry.attributes]
"service.name" = "telegraf"
"deployment.environment" = "production"

Cela vous permet de :

  • Centraliser toutes les métriques dans un pipeline OTLP
  • Changer de backend (Prometheus → Mimir → Datadog) sans toucher à Telegraf
  • Ajouter du sampling, filtering, enrichissement côté Collector
ModeOutputUsage
Pullprometheus_clientPrometheus scrape /metrics sur le port exposé
Pushhttp vers remote_writeEnvoyer vers Mimir, Cortex, Thanos
Pull (défaut)
[[outputs.prometheus_client]]
listen = ":9273"
path = "/metrics"
Push vers Mimir
[[outputs.http]]
url = "http://mimir:9009/api/v1/push"
data_format = "prometheusremotewrite"
[outputs.http.headers]
Content-Type = "application/x-protobuf"
X-Prometheus-Remote-Write-Version = "0.1.0"

Ne stockez jamais les tokens en clair dans telegraf.conf.

[[outputs.influxdb_v2]]
urls = ["http://influxdb:8086"]
token = "${INFLUXDB_TOKEN}" # Injecté par systemd/K8s
organization = "myorg"
bucket = "metrics"

Telegraf supporte des secret stores externes :

[[secretstores.os]]
id = "system"
[[outputs.influxdb_v2]]
token = "@{system:influxdb_token}"
  • Pinner la version : telegraf:1.37.1 (jamais :latest)
  • Secrets externalisés : env vars ou secret store
  • Config read-only : -v telegraf.conf:/etc/telegraf/telegraf.conf:ro
  • Jitter configuré : éviter le thundering herd
  • Monitoring de l’agent : inputs.internal + alertes
  • Limiter la cardinalité : filtrer les tags à haute cardinalité
  • RBAC K8s : ServiceAccount avec permissions minimales

Scénario complet : monitoring d’une application web

Section intitulée « Scénario complet : monitoring d’une application web »

Mettons tout ensemble avec un cas réaliste. Vous avez :

  • Un serveur Ubuntu avec Nginx en reverse proxy
  • Une application Node.js qui expose des métriques Prometheus
  • Une base PostgreSQL
  • Le tout monitoré dans Grafana via Prometheus
telegraf.conf
# === AGENT ===
[agent]
interval = "15s"
round_interval = true
collection_jitter = "3s"
flush_interval = "15s"
flush_jitter = "3s"
hostname = "${HOSTNAME}"
[global_tags]
environment = "production"
team = "backend"
# === SYSTÈME ===
[[inputs.cpu]]
percpu = false
totalcpu = true
fieldpass = ["usage_idle", "usage_system", "usage_user"]
[[inputs.mem]]
fieldpass = ["available_percent", "used_percent"]
[[inputs.disk]]
ignore_fs = ["tmpfs", "devtmpfs", "overlay"]
fieldpass = ["used_percent", "free"]
[[inputs.net]]
interfaces = ["eth0"]
fieldpass = ["bytes_recv", "bytes_sent", "err_in", "err_out"]
# === NGINX ===
[[inputs.nginx]]
urls = ["http://localhost:8080/nginx_status"]
response_timeout = "5s"
# === APPLICATION NODE.JS ===
# L'app expose /metrics au format Prometheus
[[inputs.prometheus]]
urls = ["http://localhost:3000/metrics"]
metric_version = 2
# === POSTGRESQL ===
[[inputs.postgresql]]
address = "postgres://telegraf:${PG_PASSWORD}@localhost:5432/myapp?sslmode=disable"
# === PROCESSORS ===
# Ajouter le datacenter comme tag
[[processors.regex]]
[[processors.regex.tags]]
key = "host"
pattern = "^srv-(?P<datacenter>[a-z]+)-.*$"
replacement = "${datacenter}"
result_key = "dc"
# === OUTPUT ===
# Exposer pour Prometheus (Grafana le scrape)
[[outputs.prometheus_client]]
listen = ":9273"
metric_version = 2
path = "/metrics"
expiration_interval = "60s"
  1. collection_jitter : évite que tous les serveurs interrogent en même temps
  2. fieldpass : ne garde que les champs utiles (réduit le volume)
  3. global_tags : ajoute environment et team à toutes les métriques
  4. Processors : extrait le datacenter du hostname automatiquement
  5. Secrets : ${PG_PASSWORD} injecté via variable d’environnement
Fenêtre de terminal
# 1. Tester la configuration
telegraf --config telegraf.conf --test
# 2. Vérifier que toutes les sources répondent
telegraf --config telegraf.conf --input-filter nginx --test
telegraf --config telegraf.conf --input-filter postgresql --test
# 3. Lancer en mode debug
telegraf --config telegraf.conf --debug
# 4. Vérifier l'endpoint Prometheus
curl -s http://localhost:9273/metrics | grep -E "cpu_usage|mem_available|nginx"
  • Un seul agent pour tout collecter : système, Docker, BDD, applications
  • Pipeline : Input → Processor → Aggregator → Output
  • Des centaines de plugins prêts à l’emploi, sans code à écrire
  • Multi-destination : Prometheus, InfluxDB, OTel Collector simultanément
  • Test avant déploiement : telegraf --config telegraf.conf --test
  • Empreinte variable : dépend des plugins, de la cardinalité et des outputs
  • Pin de version : toujours en production

Ce site vous est utile ?

Sachez que moins de 1% des lecteurs soutiennent ce site.

Je maintiens +700 guides gratuits, sans pub ni tracing. Aujourd'hui, ce site ne couvre même pas mes frais d'hébergement, d'électricité, de matériel, de logiciels, mais surtout de cafés.

Un soutien régulier, même symbolique, m'aide à garder ces ressources gratuites et à continuer de produire des guides de qualité. Merci pour votre appui.