From a78e02c3ae139eed05d9520f4e1653a9acb416bb Mon Sep 17 00:00:00 2001 From: Joshua Powers Date: Mon, 6 May 2024 12:13:53 -0600 Subject: [PATCH] docs: Revamp readme (#15290) Co-authored-by: Dane Strandboge <136023093+DStrand1@users.noreply.github.com> --- README.md | 206 +++++++++++----------------------- assets/TelegrafTigerSmall.png | Bin 0 -> 3448 bytes 2 files changed, 67 insertions(+), 139 deletions(-) create mode 100644 assets/TelegrafTigerSmall.png diff --git a/README.md b/README.md index 4143f776c..afba2d826 100644 --- a/README.md +++ b/README.md @@ -1,164 +1,92 @@ +# ![tiger](assets/TelegrafTigerSmall.png "tiger") Telegraf -# Telegraf +[![GoDoc](https://img.shields.io/badge/doc-reference-00ADD8.svg?logo=go)](https://godoc.org/github.com/influxdata/telegraf) [![Docker pulls](https://img.shields.io/docker/pulls/library/telegraf.svg)](https://hub.docker.com/_/telegraf/) [![Go Report Card](https://goreportcard.com/badge/github.com/influxdata/telegraf)](https://goreportcard.com/report/github.com/influxdata/telegraf) [![Circle CI](https://circleci.com/gh/influxdata/telegraf.svg?style=svg)](https://circleci.com/gh/influxdata/telegraf) -![tiger](assets/TelegrafTiger.png "tiger") +Telegraf is an agent for collecting, processing, aggregating, and writing +metrics, logs, and other arbitrary data. -[![Contribute](https://img.shields.io/badge/Contribute%20To%20Telegraf-orange.svg?logo=influx&style=for-the-badge)](https://github.com/influxdata/telegraf/blob/master/CONTRIBUTING.md) [![Slack Status](https://img.shields.io/badge/slack-join_chat-white.svg?logo=slack&style=for-the-badge)](https://www.influxdata.com/slack) [![Circle CI](https://circleci.com/gh/influxdata/telegraf.svg?style=svg)](https://circleci.com/gh/influxdata/telegraf) [![GoDoc](https://godoc.org/github.com/influxdata/telegraf?status.svg)](https://godoc.org/github.com/influxdata/telegraf) [![Docker pulls](https://img.shields.io/docker/pulls/library/telegraf.svg)](https://hub.docker.com/_/telegraf/) [![Go Report Card](https://goreportcard.com/badge/github.com/influxdata/telegraf)](https://goreportcard.com/report/github.com/influxdata/telegraf) +* Offers a comprehensive suite of over 300 plugins, covering a wide range of + functionalities including system monitoring, cloud services, and message + passing +* Enables the integration of user-defined code to collect, transform, and + transmit data efficiently +* Compiles into a standalone static binary without any external dependencies, + ensuring a streamlined deployment process +* Utilizes TOML for configuration, providing a user-friendly and unambiguous + setup experience +* Developed with contributions from a diverse community of over 1,200 + contributors -Telegraf is an agent for collecting, processing, aggregating, and writing metrics. Based on a -plugin system to enable developers in the community to easily add support for additional -metric collection. There are four distinct types of plugins: +Users can choose plugins from a wide range of topics, including but not limited +to: -1. [Input Plugins](/docs/INPUTS.md) collect metrics from the system, services, or 3rd party APIs -2. [Processor Plugins](/docs/PROCESSORS.md) transform, decorate, and/or filter metrics -3. [Aggregator Plugins](/docs/AGGREGATORS.md) create aggregate metrics (e.g. mean, min, max, quantiles, etc.) -4. [Output Plugins](/docs/OUTPUTS.md) write metrics to various destinations +* Devices: OPC UA, Modbus +* Logs: File, Tail, Directory Monitor +* Messaging: AMQP, Kafka, MQTT +* Monitoring: OpenTelemetry, Prometheus +* Networking: Cisco TelemetryMDT, gNMI +* System monitoring: CPU, Memory, Disk, Network, SMART, Docker, Nvidia SMI, etc. +* Universal: Exec, HTTP, HTTP Listener, SNMP, SQL +* Windows: Event Log, Management Instrumentation, Performance Counters -New plugins are designed to be easy to contribute, pull requests are welcomed, and we work to -incorporate as many pull requests as possible. Consider looking at the -[list of external plugins](EXTERNAL_PLUGINS.md) as well. +## 🔨 Installation -## Minimum Requirements +For binary builds, Docker images, RPM & DEB packages, and other builds of +Telegraf, please see the [install guide](/docs/INSTALL_GUIDE.md). -Telegraf shares the same [minimum requirements][] as Go: +See the [releases documentation](/docs/RELEASES.md) for details on versioning +and when releases are made. -- Linux kernel version 2.6.32 or later -- Windows 10 or later -- FreeBSD 12 or later -- macOS 10.15 Catalina or later +## 💻 Usage -[minimum requirements]: https://go.dev/wiki/MinimumRequirements +Users define a TOML configuration with the plugins and settings they wish to +use, then pass that configuration to Telegraf. The Telegraf agent then +collects data from inputs at each interval and sends data to outputs at each +flush interval. -## Obtaining Telegraf +For a basic walkthrough see [quick start](/docs/QUICK_START.md). -View the [changelog](/CHANGELOG.md) for the latest updates and changes by version. +## 📖 Documentation -### Binary Downloads +For a full list of documentation including tutorials, reference and other +material, start with the [Docs directory](/docs/README.md). -Binary downloads are available from the [InfluxData downloads](https://www.influxdata.com/downloads) -page or from each [GitHub Releases](https://github.com/influxdata/telegraf/releases) page. +Additionally, each plugin has its own README that includes details about how to +configure, use, and sometimes debug or troubleshoot. Look under the +[/plugins directory](/plugins/) for specific plugins. -### Package Repository +Here are some commonly used documents: -InfluxData also provides a package repo that contains both DEB and RPM downloads. +* [Changelog](/CHANGELOG.md) +* [Configuration](/docs/CONFIGURATION.md) +* [FAQ](/docs/FAQ.md) +* [Releases](https://github.com/influxdata/telegraf/releases) +* [Security](/SECURITY.md) -For deb-based platforms (e.g. Ubuntu and Debian) run the following to add the -repo key and setup a new sources.list entry: +## ❤️ Contribute -```shell -# influxdata-archive_compat.key GPG fingerprint: -# 9D53 9D90 D332 8DC7 D6C8 D3B9 D8FF 8E1F 7DF8 B07E -wget -q https://repos.influxdata.com/influxdata-archive_compat.key -echo '393e8779c89ac8d958f81f942f9ad7fb82a25e133faddaf92e15b16e6ac9ce4c influxdata-archive_compat.key' | sha256sum -c && cat influxdata-archive_compat.key | gpg --dearmor | sudo tee /etc/apt/trusted.gpg.d/influxdata-archive_compat.gpg > /dev/null -echo 'deb [signed-by=/etc/apt/trusted.gpg.d/influxdata-archive_compat.gpg] https://repos.influxdata.com/debian stable main' | sudo tee /etc/apt/sources.list.d/influxdata.list -sudo apt-get update && sudo apt-get install telegraf -``` +[![Contribute](https://img.shields.io/badge/contribute-to_telegraf-blue.svg?logo=influxdb)](https://github.com/influxdata/telegraf/blob/master/CONTRIBUTING.md) -For RPM-based platforms (e.g. RHEL, CentOS) use the following to create a repo -file and install telegraf: +We love our community of over 1,200 contributors! Many of the plugins included +in Telegraf were originally contributed by community members. Check out +our [contributing guide](CONTRIBUTING.md) if you are interested in helping out. +Also, join us on our [Community Slack](https://influxdata.com/slack) or +[Community Forums](https://community.influxdata.com/) if you have questions or +comments for our engineering teams. -```shell -# influxdata-archive_compat.key GPG fingerprint: -# 9D53 9D90 D332 8DC7 D6C8 D3B9 D8FF 8E1F 7DF8 B07E -cat < telegraf.conf -``` - -### Generate config with only cpu input & influxdb output plugins defined - -```shell -telegraf config --section-filter agent:inputs:outputs --input-filter cpu --output-filter influxdb -``` - -### Run a single telegraf collection, outputting metrics to stdout - -```shell -telegraf --config telegraf.conf --test -``` - -### Run telegraf with all plugins defined in config file - -```shell -telegraf --config telegraf.conf -``` - -### Run telegraf, enabling the cpu & memory input, and influxdb output plugins - -```shell -telegraf --config telegraf.conf --input-filter cpu:mem --output-filter influxdb -``` - -## Contribute to the Project - -Telegraf is an MIT licensed open source project and we love our community. The fastest way to get something fixed is to open a PR. Check out our [contributing guide](CONTRIBUTING.md) if you're interested in helping out. Also, join us on our [Community Slack](https://influxdata.com/slack) or [Community Page](https://community.influxdata.com/) if you have questions or comments for our engineering teams. - -If your completely new to Telegraf and InfluxDB, you can also enroll for free at [InfluxDB university](https://www.influxdata.com/university/) to take courses to learn more. - -## Documentation - -[Latest Release Documentation](https://docs.influxdata.com/telegraf/latest/) - -For documentation on the latest development code see the [documentation index](/docs). - -- [Input Plugins](/docs/INPUTS.md) -- [Output Plugins](/docs/OUTPUTS.md) -- [Processor Plugins](/docs/PROCESSORS.md) -- [Aggregator Plugins](/docs/AGGREGATORS.md) +[![MIT](https://img.shields.io/badge/license-MIT-blue)](https://github.com/influxdata/telegraf/blob/master/LICENSE) diff --git a/assets/TelegrafTigerSmall.png b/assets/TelegrafTigerSmall.png new file mode 100644 index 0000000000000000000000000000000000000000..b51871110180b2095497eeccf75cb1d779a16a15 GIT binary patch literal 3448 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 bLhB4dQ{!(2yTKX4VgOT=rAe)kYwW)O)t!_5 literal 0 HcmV?d00001