github-mirrors/logstash
1
0
Fork 0
mirror of https://github.com/elastic/logstash.git synced 2025-04-24 06:37:19 -04:00
Code Issues Projects Releases Packages Wiki Activity

Remove 2.x info from upgrade docs

Browse source 
Fixes #6129
This commit is contained in:
DeDe Morton 2016-10-26 15:48:44 -07:00
parent 4b3b1ab29e
commit c20e5f557b
1 changed files with 14 additions and 33 deletions
Download patch file Download diff file Expand all files Collapse all files

47
docs/static/upgrading.asciidoc vendored
View file

@ -9,18 +9,29 @@ Before upgrading Logstash:
* Test upgrades in a development environment before upgrading your production cluster.
===========================================
If you are installing Logstash with other components in the Elastic Stack, also see the
{stack}index.html[Elastic Stack installation and upgrade documentation].
See the following topics for information about upgrading Logstash:
* <<upgrading-using-package-managers>>
* <<upgrading-using-direct-download>>
* <<upgrading-logstash-5.0>>
[[upgrading-using-package-managers]]
=== Upgrading Using Package Managers
This procedure uses <<package-repositories,package managers>> to upgrade Logstash.
1. Shut down your Logstash pipeline, including any inputs that send events to Logstash.
2. Using the directions in the _Package Repositories_ section, update your repository links to point to the 2.0 repositories
2. Using the directions in the _Package Repositories_ section, update your repository links to point to the 5.x repositories
instead of the previous version.
3. Run the `apt-get upgrade logstash` or `yum update logstash` command as appropriate for your operating system.
4. Test your configuration file with the `logstash --config.test_and_exit -f <configuration-file>` command. Configuration options for
some Logstash plugins have changed in the 2.0 release.
some Logstash plugins have changed in the 5.x release.
5. Restart your Logstash pipeline after updating your configuration file.
[[upgrading-using-direct-download]]
=== Upgrading Using a Direct Download
This procedure downloads the relevant Logstash binaries directly from Elastic.
@ -29,39 +40,9 @@ This procedure downloads the relevant Logstash binaries directly from Elastic.
2. Download the https://www.elastic.co/downloads/logstash[Logstash installation file] that matches your host environment.
3. Unpack the installation file into your Logstash directory.
4. Test your configuration file with the `logstash --config.test_and_exit -f <configuration-file>` command. Configuration options for
some Logstash plugins have changed in the 2.0 release.
some Logstash plugins have changed in the 5.x release.
5. Restart your Logstash pipeline after updating your configuration file.
[[upgrading-logstash-2.2]]
=== Upgrading Logstash to 2.2
Logstash 2.2 re-architected the pipeline stages to provide more performance and help future enhancements in resiliency.
The new pipeline introduced micro-batches, processing groups of events at a time. The default batch size is
125 per worker. Also, the filter and output stages are executed in the same thread, but still, as different stages.
The CLI flag `--pipeline-workers` or `-w` control the number of execution threads, which is set by default to number of cores.
**Considerations for Elasticsearch Output**
The default batch size of the pipeline is 125 events per worker. This will by default also be the bulk size
used for the elasticsearch output. The Elasticsearch output's `flush_size` now acts only as a maximum bulk
size (still defaulting to 500). For example, if your pipeline batch size is 3000 events, Elasticsearch
Output will send 500 events at a time, in 6 separate bulk requests. In other words, for Elasticsearch output,
bulk request size is chunked based on `flush_size` and `--pipeline.batch.size`. If `flush_size` is set greater
than `--pipeline.batch.size`, it is ignored and `--pipeline.batch.size` will be used.
The default number of output workers in Logstash 2.2 is now equal to the number of pipeline workers (`-w`)
unless overridden in the Logstash config file. This can be problematic for some users as the
extra workers may consume extra resources like file handles, especially in the case of the Elasticsearch
output. Users with more than one Elasticsearch host may want to override the `workers` setting
for the Elasticsearch output in their Logstash config to constrain that number to a low value, between 1 to 4.
**Performance Tuning in 2.2**
Since both filters and output workers are on the same thread, this could lead to threads being idle in I/O wait state.
Thus, in 2.2, you can safely set `-w` to a number which is a multiple of the number of cores on your machine.
A common way to tune performance is keep increasing the `-w` beyond the # of cores until performance no longer
improves. A note of caution - make sure you also keep heapsize in mind, because the number of in-flight events
are `#workers * batch_size * average_event size`. More in-flight events could add to memory pressure, eventually
leading to Out of Memory errors. You can change the heapsize in Logstash by setting `LS_HEAP_SIZE`.
[[upgrading-logstash-5.0]]
=== Upgrading Logstash to 5.0