
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.
À quoi sert Telegraf ?
Section intitulée « À quoi sert Telegraf ? »Le problème sans agent de collecte
Section intitulée « Le problème sans agent de collecte »Vous gérez un serveur qui fait tourner PostgreSQL, Redis et une application Docker. Pour monitorer tout ça, vous devez :
# Métriques système ? Pas de format standardcat /proc/meminfo | grep MemAvail # → Valeur brute en Ko
# PostgreSQL ? Il faut écrire des requêtes SQLpsql -c "SELECT * FROM pg_stat_database;" # → Résultat tabulaire
# Docker ? Encore une autre APIcurl --unix-socket /var/run/docker.sock http://localhost/containers/json # → JSONRésultat : vous vous retrouvez avec 3 scripts, 3 formats, 3 façons de parser… et une dette technique qui s’accumule.
La solution : Telegraf comme agent universel
Section intitulée « La solution : Telegraf comme agent universel »Avec Telegraf, une seule configuration collecte tout, normalise tout, et envoie tout :
Pourquoi c’est mieux :
| Sans Telegraf | Avec Telegraf |
|---|---|
| Un script par source | Une config déclarative |
| Formats hétérogènes | Format unifié (InfluxDB line protocol) |
| Push ou pull selon la source | Telegraf s’en occupe |
| Maintenance des scripts | Plugins maintenus par la communauté |
| Une destination à la fois | Multi-destination native |
Comprendre l’architecture
Section intitulée « Comprendre l’architecture »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).
Pourquoi cette architecture ?
Section intitulée « Pourquoi cette architecture ? »Imaginez que vous vouliez :
- Collecter le CPU, la mémoire ET les métriques PostgreSQL
- Renommer certains champs pour qu’ils correspondent à vos conventions
- Filtrer les conteneurs de test pour ne garder que la prod
- Envoyer le tout vers Prometheus ET InfluxDB simultanément
Avec Telegraf, vous configurez chaque étape indépendamment. Pas de code à écrire.
1. Inputs : collecter les données
Section intitulée « 1. Inputs : collecter les données »Les inputs interrogent les sources et récupèrent les métriques. C’est le point d’entrée de votre pipeline.
| Input | Ce qu’il collecte | Cas d’usage |
|---|---|---|
cpu | Utilisation CPU par cœur | Monitoring système |
mem | Mémoire utilisée/disponible | Monitoring système |
docker | Métriques conteneurs | Environnements conteneurisés |
postgresql | Stats BDD, locks, queries | Monitoring base de données |
prometheus | Scrape endpoints /metrics | Récupérer des métriques existantes |
http | Appel HTTP + parsing JSON | APIs custom |
2. Processors : transformer les données
Section intitulée « 2. Processors : transformer les données »Les processors modifient les métriques après collecte. C’est ici que vous normalisez, enrichissez ou filtrez.
| Processor | Ce qu’il fait | Exemple concret |
|---|---|---|
rename | Renomme champs/tags | cpu_usage_idle → cpu_idle |
regex | Extrait avec des regex | Extraire dc=paris du hostname srv-paris-01 |
filter | Supprime des métriques | Exclure les conteneurs dont le nom contient test |
converter | Change les types | String → Integer pour les calculs |
3. Aggregators : agréger dans le temps
Section intitulée « 3. Aggregators : agréger dans le temps »Les aggregators calculent des statistiques sur une fenêtre temporelle. Utile pour réduire le volume ou obtenir des vues synthétiques.
| Aggregator | Ce qu’il calcule | Quand l’utiliser |
|---|---|---|
basicstats | min, max, mean, stdev | Vue d’ensemble statistique |
histogram | Distribution en buckets | Analyser la distribution des latences |
merge | Fusionne plusieurs métriques | Consolider des sources similaires |
4. Outputs : envoyer les données
Section intitulée « 4. Outputs : envoyer les données »Les outputs transmettent les métriques aux backends. Vous pouvez en avoir plusieurs — les mêmes données partent vers tous les outputs.
| Output | Destination | Mode |
|---|---|---|
prometheus_client | Prometheus | Pull (exposition endpoint) |
influxdb_v2 | InfluxDB 2.x | Push |
kafka | Kafka | Push |
file | Fichier local | Debug |
Installer Telegraf
Section intitulée « Installer Telegraf »# 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 importgpg --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 signatureecho '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
# Installersudo apt-get update && sudo apt-get install telegraf
# Vérifier l'installationtelegraf versionRésultat attendu :
Telegraf 1.37.1# Ajouter le repocat <<'EOF' | sudo tee /etc/yum.repos.d/influxdb.repo[influxdb]name = InfluxDB Repositorybaseurl = https://repos.influxdata.com/rhel/$releasever/$basearch/stableenabled = 1gpgcheck = 1gpgkey = https://repos.influxdata.com/influxdata-archive.keyEOF
# Installersudo yum install telegraf -y
# Vérifiertelegraf --version# Créer un fichier de config minimalcat > telegraf.conf << 'EOF'[agent] interval = "10s" hostname = "demo"
[[inputs.cpu]] percpu = false totalcpu = true
[[outputs.file]] files = ["stdout"]EOF
# Lancer Telegraf (version pinnée, jamais :latest)docker run --rm \ -v $(pwd)/telegraf.conf:/etc/telegraf/telegraf.conf:ro \ telegraf:1.37.1Résultat : les métriques CPU s’affichent toutes les 10 secondes.
# Télécharger (version 1.37.1)wget https://dl.influxdata.com/telegraf/releases/telegraf-1.37.1_linux_amd64.tar.gztar xzf telegraf-1.37.1_linux_amd64.tar.gz
# Installersudo mv telegraf-1.37.1/usr/bin/telegraf /usr/local/bin/telegraf versionRésultat attendu :
Telegraf 1.37.1Votre premier pipeline
Section intitulée « Votre premier pipeline »Créons un pipeline qui collecte les métriques système et les affiche.
-
Générer une configuration de base
Fenêtre de terminal telegraf config \--input-filter cpu:mem:disk \--output-filter file \> telegraf.conf -
Simplifier la configuration
Éditez
telegraf.confpour ne garder que l’essentiel :telegraf.conf [agent]interval = "10s"round_interval = truehostname = "mon-serveur"# Collecter CPU[[inputs.cpu]]percpu = falsetotalcpu = true# Collecter mémoire[[inputs.mem]]# Collecter espace disque[[inputs.disk]]ignore_fs = ["tmpfs", "devtmpfs"]# Afficher dans le terminal[[outputs.file]]files = ["stdout"] -
Tester le pipeline
Fenêtre de terminal telegraf --config telegraf.conf --testRé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 -
Lancer en continu
Fenêtre de terminal # Mode debug pour voir ce qui se passetelegraf --config telegraf.conf --debugAppuyez sur
Ctrl+Cpour arrêter.
Exposer les métriques pour Prometheus
Section intitulée « Exposer les métriques pour Prometheus »Modifiez la configuration pour exposer un endpoint /metrics :
[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"-
Lancer Telegraf
Fenêtre de terminal telegraf --config telegraf.conf -
Vérifier l’endpoint
Fenêtre de terminal curl http://localhost:9273/metricsRésultat :
# HELP cpu_usage_idle Telegraf collected metric# TYPE cpu_usage_idle gaugecpu_usage_idle{cpu="cpu-total",host="mon-serveur"} 94.5# HELP mem_available Telegraf collected metric# TYPE mem_available gaugemem_available{host="mon-serveur"} 6.442450944e+09 -
Configurer Prometheus pour scraper Telegraf
Ajoutez dans
prometheus.yml:scrape_configs:- job_name: 'telegraf'static_configs:- targets: ['localhost:9273']
Collecter Docker et PostgreSQL
Section intitulée « Collecter Docker et PostgreSQL »Enrichissons le pipeline avec des métriques applicatives.
[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 = 2Métriques Docker disponibles
Section intitulée « Métriques Docker disponibles »| Métrique | Description |
|---|---|
docker_container_cpu_usage_percent | Utilisation CPU par conteneur |
docker_container_mem_usage | Mémoire utilisée par conteneur |
docker_container_net_rx_bytes | Trafic réseau reçu |
docker_container_blkio_io_service_bytes_read | I/O disque lecture |
Métriques PostgreSQL disponibles
Section intitulée « Métriques PostgreSQL disponibles »| Métrique | Description |
|---|---|
postgresql_numbackends | Connexions actives |
postgresql_xact_commit | Transactions commitées |
postgresql_blks_hit | Cache hits |
postgresql_deadlocks | Nombre de deadlocks |
Déploiement Kubernetes
Section intitulée « Déploiement Kubernetes »DaemonSet
Section intitulée « DaemonSet »apiVersion: apps/v1kind: DaemonSetmetadata: name: telegraf namespace: monitoringspec: 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: /sysConfigMap
Section intitulée « ConfigMap »apiVersion: v1kind: ConfigMapmetadata: name: telegraf-config namespace: monitoringdata: 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"Monitoring de Telegraf
Section intitulée « Monitoring de Telegraf »Métriques internes
Section intitulée « Métriques internes »[[inputs.internal]] collect_memstats = trueMétriques disponibles :
internal_agent: état de l’agentinternal_gather: temps de collecteinternal_write: temps d’écriture
Healthcheck
Section intitulée « Healthcheck »# Vérifier la config (dry-run)telegraf --config telegraf.conf --test
# Afficher la versiontelegraf versionAlertes recommandées sur l’agent
Section intitulée « Alertes recommandées sur l’agent »Avec inputs.internal, surveillez ces métriques :
| Métrique | Seuil d’alerte | Signification |
|---|---|---|
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 | > 0 | Buffer saturé, métriques perdues |
| Scrape absent | 2× interval | Agent down ou réseau coupé |
Bonnes pratiques
Section intitulée « Bonnes pratiques »-
Utilisez des variables d’environnement
token = "${INFLUXDB_TOKEN}" -
Filtrez au niveau de l’input
Évitez de collecter des métriques inutiles.
[[inputs.disk]]ignore_fs = ["tmpfs", "devtmpfs"] -
Limitez la cardinalité
Évitez les tags à haute cardinalité (IDs uniques).
-
Testez avant de déployer
Fenêtre de terminal telegraf --config telegraf.conf --test -
Monitorez Telegraf lui-même
Activez
inputs.internalpour surveiller les performances.
Dépannage
Section intitulée « Dépannage »| Symptôme | Cause probable | Solution |
|---|---|---|
| Plugin non trouvé | Version Telegraf trop ancienne | telegraf --version puis mettre à jour |
Error in plugin: permission denied | Accès socket/fichier refusé | sudo usermod -aG docker telegraf |
| Timeout input | Source lente ou inaccessible | Augmenter timeout dans la config input |
metric buffer limit reached | Trop de métriques en attente | Augmenter metric_buffer_limit ou réduire les inputs |
| Métriques dupliquées | Plusieurs instances scrapent la même source | Vérifier qu’un seul Telegraf collecte chaque source |
| Pas de métriques Docker | Socket inaccessible | Vérifier /var/run/docker.sock et permissions |
| Erreur PostgreSQL | Credentials invalides | Tester avec psql la chaîne de connexion |
Commandes de diagnostic
Section intitulée « Commandes de diagnostic »# Mode debug complettelegraf --config telegraf.conf --debug
# Tester uniquement l'input CPUtelegraf --config telegraf.conf --input-filter cpu --test
# Tester uniquement l'output Prometheustelegraf --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 disponiblestelegraf --input-listtelegraf --output-listVérifier que les métriques remontent
Section intitulée « Vérifier que les métriques remontent »# 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écifiquecurl -s http://localhost:9273/metrics | grep "docker_"Telegraf vs autres agents
Section intitulée « Telegraf vs autres agents »| Agent | Points forts | Quand l’utiliser |
|---|---|---|
| Telegraf | Des centaines de plugins, très bon pour métriques infra + services | Stack InfluxDB, ou besoin de collecter PostgreSQL/Redis/Docker |
| OTel Collector | Standard OTLP, normalisation, routing multi-backends | Pipeline unifié logs + metrics + traces, vendor-agnostic |
| Vector | Transformations puissantes, très performant | Pipelines logs complexes, enrichissement avancé |
| Fluent Bit | Ultra léger, CNCF | K8s/edge, logs principalement |
Envoyer vers OpenTelemetry Collector
Section intitulée « Envoyer vers OpenTelemetry Collector »Telegraf peut exporter ses métriques en OTLP vers un Collector :
[[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
Prometheus : pull vs push
Section intitulée « Prometheus : pull vs push »| Mode | Output | Usage |
|---|---|---|
| Pull | prometheus_client | Prometheus scrape /metrics sur le port exposé |
| Push | http vers remote_write | Envoyer vers Mimir, Cortex, Thanos |
[[outputs.prometheus_client]] listen = ":9273" path = "/metrics"[[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"Gestion des secrets en production
Section intitulée « Gestion des secrets en production »Ne stockez jamais les tokens en clair dans telegraf.conf.
Variables d’environnement
Section intitulée « Variables d’environnement »[[outputs.influxdb_v2]] urls = ["http://influxdb:8086"] token = "${INFLUXDB_TOKEN}" # Injecté par systemd/K8s organization = "myorg" bucket = "metrics"Secret stores (Telegraf 1.30+)
Section intitulée « Secret stores (Telegraf 1.30+) »Telegraf supporte des secret stores externes :
[[secretstores.os]] id = "system"
[[outputs.influxdb_v2]] token = "@{system:influxdb_token}"Checklist production
Section intitulée « Checklist production »- 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
Configuration complète
Section intitulée « Configuration complète »# === 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"Points clés de cette configuration
Section intitulée « Points clés de cette configuration »collection_jitter: évite que tous les serveurs interrogent en même tempsfieldpass: ne garde que les champs utiles (réduit le volume)global_tags: ajouteenvironmentetteamà toutes les métriques- Processors : extrait le datacenter du hostname automatiquement
- Secrets :
${PG_PASSWORD}injecté via variable d’environnement
Validation
Section intitulée « Validation »# 1. Tester la configurationtelegraf --config telegraf.conf --test
# 2. Vérifier que toutes les sources répondenttelegraf --config telegraf.conf --input-filter nginx --testtelegraf --config telegraf.conf --input-filter postgresql --test
# 3. Lancer en mode debugtelegraf --config telegraf.conf --debug
# 4. Vérifier l'endpoint Prometheuscurl -s http://localhost:9273/metrics | grep -E "cpu_usage|mem_available|nginx"À retenir
Section intitulée « À retenir »- 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