[WIP] Update README.md

awslabs · Mar 2, 2024 · dc02b37 · dc02b37
1 parent a2c81b2
commit dc02b37
Showing 1 changed file with 32 additions and 60 deletions.
diff --git a/README.md b/README.md
@@ -4,76 +4,53 @@
 [![Gem Version](https://badge.fury.io/rb/fluent-plugin-kinesis.svg)](https://rubygems.org/gems/fluent-plugin-kinesis)
 [![Gem Downloads](https://img.shields.io/gem/dt/fluent-plugin-kinesis.svg)](https://rubygems.org/gems/fluent-plugin-kinesis)
 
-[Fluentd][fluentd] output plugin
-that sends events to [Amazon Kinesis Data Streams][streams] and [Amazon Kinesis Data Firehose][firehose]. Also it supports [KPL Aggregated Record Format][kpl]. This gem includes three output plugins respectively:
+
+A fluentd output plugin to send events to [Amazon Kinesis Data Streams][streams] and [Amazon Data Firehose][firehose]. The plugin also supports [KPL Aggregated Record Format][kpl].
+
+This gem includes following three output plugins:
 
 - `kinesis_streams`
 - `kinesis_firehose`
 - `kinesis_streams_aggregated`
 
-Also, there is a [documentation on Fluentd official site][fluentd-doc-kinesis].
-
-**Note**: This README is for v3. Plugin v3 is almost compatible with v2. If you use v1, see the [old README][v1-readme].
-
-## Installation
-This Fluentd plugin is available as the `fluent-plugin-kinesis` gem from RubyGems.
+The plugin is also described in [official Fluentd document][fluentd-doc-kinesis].
 
-    gem install fluent-plugin-kinesis
+**Note**: This README is for the latest v3. Plugin v3 is almost compatible with v2. If you use v1, see [v1 README][v1-readme].
 
-Or you can install this plugin for [td-agent][td-agent] as:
 
-    td-agent-gem install fluent-plugin-kinesis
-
-If you would like to build by yourself and install, see the section below. Your need [bundler][bundler] for this.
-
-In case of using with Fluentd: Fluentd will be also installed via the process below.
-
-    git clone https://github.com/awslabs/aws-fluent-plugin-kinesis.git
-    cd aws-fluent-plugin-kinesis
-    bundle install
-    bundle exec rake build
-    bundle exec rake install
-
-Also, you can use this plugin with td-agent: You have to install td-agent before installing this plugin.
+## Installation
 
-    git clone https://github.com/awslabs/aws-fluent-plugin-kinesis.git
-    cd aws-fluent-plugin-kinesis
-    bundle install
-    bundle exec rake build
-    fluent-gem install pkg/fluent-plugin-kinesis
+Simply use RubyGems:
 
-Or just download specify your Ruby library path. Below is the sample for specifying your library path via RUBYLIB.
+    $ gem install fluent-plugin-kinesis --no-document
 
-    git clone https://github.com/awslabs/aws-fluent-plugin-kinesis.git
-    cd aws-fluent-plugin-kinesis
-    bundle install
-    export RUBYLIB=$RUBYLIB:/path/to/aws-fluent-plugin-kinesis/lib
+If you would like to build by yourself and install, you can build and install as follows:
 
-## Dependencies
- * Ruby 2.4.2+
- * Fluentd 0.14.22+ (td-agent v3.1.0+)
+    $ git clone https://github.com/awslabs/aws-fluent-plugin-kinesis.git
+    $ cd aws-fluent-plugin-kinesis
+    $ bundle install
+    $ bundle exec rake build
+    $ bundle exec rake install
 
-## Basic Usage
-Here are general procedures for using this plugin:
+    # If using fluent-package (td-agent), use td-agent-gem
+    $ td-agent-gem install pkg/fluent-plugin-kinesis
 
- 1. Install.
- 1. Edit configuration
- 1. Run Fluentd or td-agent
 
-You can run this plugin with Fluentd as follows:
+## Requirements
 
- 1. Install.
- 1. Edit configuration file and save it as 'fluentd.conf'.
- 1. Then, run `fluentd -c /path/to/fluentd.conf`
+| fluent-plugin-kinesis | fluentd    | ruby     |
+|:---------------------:|:-----------:|:--------:|
+| >= 3.5.0              | >= 0.14.22 | >= 2.4.2 |
+| >= 3.2.0 && < 3.5.0   | >= 0.14.22 | >= 2.3   |
+| >= 3.0.0 && < 3.2.0   | >= 0.14.10 | >= 2.1   |
+| >= 2.0.0 && < 3.0.0   | >= 0.12.35 | >= 2.1   |
+| < 2.0.0               | >= 0.10.58 | >= 2.0   |
 
-To run with td-agent, it would be as follows:
 
- 1. Install.
- 1. Edit configuration file provided by td-agent.
- 1. Then, run or restart td-agent.
+## Getting Started
+When you run this plugin on Amazon EC2 instances or container services, use [instance profiles](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_use_switch-role-ec2_instance-profiles.html) to assume role. If you want to use specific credentials, see [Credentials](#configuration-credentials).
 
-## Getting started
-Assume you use Amazon EC2 instances with Instance profile. If you want to use specific credentials, see [Credentials](#configuration-credentials).
+In your Fluentd configuration, use @type kinesis_streams, kinesis_firehose, or kinesis_streams_aggregated. The configuration would look like this:
 
 ### kinesis_streams
     <match your_tag>
@@ -102,21 +79,19 @@ For more details, see [Configuration: kinesis_firehose](#configuration-kinesis_f
     </match>
 For more details, see [Configuration: kinesis_streams_aggregated](#configuration-kinesis_streams_aggregated).
 
-### For better throughput
-Add configurations like below:
+### Configurations to increase throughput
+Add configurations like this:
 
       flush_interval 1
       chunk_limit_size 1m
       flush_thread_interval 0.1
       flush_thread_burst_interval 0.01
       flush_thread_count 15
 
-When you use Fluent v1.0 (td-agent3), write these configurations in buffer section. For more details, see [Config: Buffer Section][fluentd-buffer-section].
-
-Note: Each value should be adjusted to your system by yourself.
+When you use Fluent v1.0+ (td-agent v3+), write these configurations in buffer section. For more details, see [Config: Buffer Section][fluentd-buffer-section]. Note that each parameter should be adjusted to your system.
 
 ## Configuration: Credentials
-To put records into Amazon Kinesis Data Streams or Firehose, you need to provide AWS security credentials somehow. Without specifying credentials in config file, this plugin automatically fetch credential just following AWS SDK for Ruby does (environment variable, shared profile, and instance profile).
+To put records into Amazon Kinesis Data Streams or Amazon Firehose, you need to provide AWS security credentials somehow. Without specifying credentials in config file, this plugin automatically fetch credential just following AWS SDK for Ruby does (environment variable, shared profile, and instance profile).
 
 This plugin uses the same configuration in [fluent-plugin-s3][fluent-plugin-s3], but also supports aws session tokens for temporary credentials. 
 
@@ -542,12 +517,9 @@ Bug reports and pull requests are welcome on [GitHub][github].
 * [Amazon Kinesis Data Streams Developer Guide](http://docs.aws.amazon.com/kinesis/latest/dev/introduction.html)
 * [Amazon Kinesis Data Firehose Developer Guide](http://docs.aws.amazon.com/firehose/latest/dev/what-is-this-service.html)
 
-[fluentd]: https://www.fluentd.org/
 [streams]: https://aws.amazon.com/kinesis/streams/
 [firehose]: https://aws.amazon.com/kinesis/firehose/
 [kpl]: https://github.com/awslabs/amazon-kinesis-producer/blob/master/aggregation-format.md
-[td-agent]: https://github.com/treasure-data/omnibus-td-agent
-[bundler]: https://bundler.io/
 [region]: https://docs.aws.amazon.com/general/latest/gr/rande.html#ak_region
 [fluentd-buffer-section]: https://docs.fluentd.org/configuration/buffer-section
 [fluentd-formatter-json]: https://docs.fluentd.org/formatter/json