
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