diff --git a/README.md b/README.md index 4143f776ce121..afba2d826c97f 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 0000000000000..b51871110180b Binary files /dev/null and b/assets/TelegrafTigerSmall.png differ