github-mirrors/logstash
1
0
Fork 0
mirror of https://github.com/elastic/logstash.git synced 2025-04-25 07:07:54 -04:00
Code Issues Projects Releases Packages Wiki Activity

Add info on backward compatibility; add anchor for draining queue

Browse source 
Fixes #9796
This commit is contained in:
Karen Metts 2018-06-28 18:21:25 -04:00 • committed by karen.metts
parent dcf93f5a26
commit cb062c5699
2 changed files with 38 additions and 15 deletions
Download patch file Download diff file Expand all files Collapse all files

48
docs/static/breaking-changes.asciidoc vendored
View file

@ -1,11 +1,27 @@
[[breaking-changes]] [[breaking-changes]]
== Breaking Changes == Breaking Changes
This section discusses the changes that you need to be aware of when migrating to Logstash 6.0.0 from the previous major releases. We strive to maintain backward compatibility between minor versions (6.x to 6.y,
for example) so that you can upgrade without changing any configuration files.
Breaking changes are usually introduced only between major versions (such as 5.x
to 6.y). On occasion, we are forced to break compatibility within a given major release
to ensure correctness of operation.
This section covers the changes that you need to be aware of when migrating to
Logstash 6.0.0 and later.
NOTE: Migrating directly between non-consecutive major versions (1.x to
6.x) is not recommended.
See these topics for a description of breaking changes:
* <<breaking-pq>>
* <<breaking-6.0>>
See also <<releasenotes>>. See also <<releasenotes>>.
[float] [float]
[[breaking-pq]]
=== Breaking change across PQ versions prior to Logstash 6.3.0 === Breaking change across PQ versions prior to Logstash 6.3.0
If you are upgrading from Logstash 6.2.x or any earlier version (including 5.x) If you are upgrading from Logstash 6.2.x or any earlier version (including 5.x)
@ -13,38 +29,44 @@ and have the persistent queue enabled, we strongly recommend that you drain or
delete the persistent queue before you upgrade. See <<upgrading-logstash-pqs>> delete the persistent queue before you upgrade. See <<upgrading-logstash-pqs>>
for information and instructions. for information and instructions.
We are working to resolve issues with data incompatibilities in our 6.3.0 We are working to resolve issues with data incompatibilities so that additional
release so that additional steps won't be required for future upgrades. steps won't be required for future upgrades.
[float] [float]
=== Changes in Logstash Core [[breaking-6.0]]
=== Breaking changes in 6.0
Here are the breaking changes for 6.0.
[float]
==== Changes in Logstash Core
These changes can impact any instance of Logstash and are plugin agnostic, but only if you are using the features that are impacted. These changes can impact any instance of Logstash and are plugin agnostic, but only if you are using the features that are impacted.
[float] [float]
==== Application Settings ===== Application Settings
* The setting `config.reload.interval` has been changed to use time value strings such as `5m`, `10s` etc. * The setting `config.reload.interval` has been changed to use time value strings such as `5m`, `10s` etc.
Previously, users had to convert this to a millisecond time value themselves. Previously, users had to convert this to a millisecond time value themselves.
[float] [float]
==== RPM/Deb package changes ===== RPM/Deb package changes
* For `rpm` and `deb` release artifacts, config files that match the `*.conf` glob pattern must be in the conf.d folder, * For `rpm` and `deb` release artifacts, config files that match the `*.conf` glob pattern must be in the conf.d folder,
or the files will not be loaded. or the files will not be loaded.
[float] [float]
==== Command Line Interface behavior ===== Command Line Interface behavior
* The `-e` and `-f` CLI options are now mutually exclusive. This also applies to the corresponding long form options `config.string` and * The `-e` and `-f` CLI options are now mutually exclusive. This also applies to the corresponding long form options `config.string` and
`path.config`. This means any configurations provided via `-e` will no longer be appended to the configurations provided via `-f`. `path.config`. This means any configurations provided via `-e` will no longer be appended to the configurations provided via `-f`.
* Configurations provided with `-f` or `config.path` will not be appended with `stdin` input and `stdout` output automatically. * Configurations provided with `-f` or `config.path` will not be appended with `stdin` input and `stdout` output automatically.
[float] [float]
=== Plugin Changes ==== Plugin Changes
[float] [float]
==== Elasticsearch output changes ===== Elasticsearch output changes
* The default `document_type` has changed from `logs` to `doc` for consistency with Beats. * The default `document_type` has changed from `logs` to `doc` for consistency with Beats.
Furthermore, users are advised that Elasticsearch 6.0 deprecates doctypes, and 7.0 will remove them. Furthermore, users are advised that Elasticsearch 6.0 deprecates doctypes, and 7.0 will remove them.
@ -54,7 +76,7 @@ These changes can impact any instance of Logstash and are plugin agnostic, but o
The new mapping template has been updated to reflect that. If you are using a custom mapping template you may need to update it to reflect that. The new mapping template has been updated to reflect that. If you are using a custom mapping template you may need to update it to reflect that.
[float] [float]
==== Kafka input changes ===== Kafka input changes
* Upgraded Kafka client support to v0.11.0.0, which only supports Kafka brokers v0.10.x or later. * Upgraded Kafka client support to v0.11.0.0, which only supports Kafka brokers v0.10.x or later.
** Please refer to <<plugins-inputs-kafka,Kafka input plugin>> documentation for information about Kafka compatibility with Logstash. ** Please refer to <<plugins-inputs-kafka,Kafka input plugin>> documentation for information about Kafka compatibility with Logstash.
@ -63,21 +85,21 @@ These changes can impact any instance of Logstash and are plugin agnostic, but o
* The `ssl` option is now obsolete. * The `ssl` option is now obsolete.
[float] [float]
==== Kafka output changes ===== Kafka output changes
* Upgraded Kafka client support to v0.11.0.0, which only supports Kafka brokers v0.10.x or later. * Upgraded Kafka client support to v0.11.0.0, which only supports Kafka brokers v0.10.x or later.
** Please refer to <<plugins-outputs-kafka,Kafka output plugin>> documentation for information about Kafka compatibility with Logstash. ** Please refer to <<plugins-outputs-kafka,Kafka output plugin>> documentation for information about Kafka compatibility with Logstash.
* The options `block_on_buffer_full`, `ssl`, and `timeout_ms` are now obsolete. * The options `block_on_buffer_full`, `ssl`, and `timeout_ms` are now obsolete.
[float] [float]
==== Beats input changes ===== Beats input changes
* Logstash will no longer start when <<plugins-codecs-multiline,Multiline codec plugin>> is used with the Beats input plugin. * Logstash will no longer start when <<plugins-codecs-multiline,Multiline codec plugin>> is used with the Beats input plugin.
** It is recommended to use the multiline support in Filebeat as a replacement - see https://www.elastic.co/guide/en/beats/filebeat/current/multiline-examples.html[configuration options available in Filebeat] for details. ** It is recommended to use the multiline support in Filebeat as a replacement - see https://www.elastic.co/guide/en/beats/filebeat/current/multiline-examples.html[configuration options available in Filebeat] for details.
* The options `congestion_threshold` and `target_field_for_codec` are now obsolete. * The options `congestion_threshold` and `target_field_for_codec` are now obsolete.
[float] [float]
==== List of plugins bundled with Logstash ===== List of plugins bundled with Logstash
The following plugins were removed from the 6.0 default bundle based on usage data. You can still install these plugins manually: The following plugins were removed from the 6.0 default bundle based on usage data. You can still install these plugins manually:

5
docs/static/upgrading.asciidoc vendored
View file

@ -127,6 +127,7 @@ break that compatibility in version 6.3.0 to ensure correctness of operation.
For more technical details on this issue, please check our tracking github issue For more technical details on this issue, please check our tracking github issue
for this matter, https://github.com/elastic/logstash/issues/9494[#9494]. for this matter, https://github.com/elastic/logstash/issues/9494[#9494].
[[drain-pq]]
==== Drain the Persistent Queue ==== Drain the Persistent Queue
If you are upgrading from Logstash 6.2.x or an earlier version and use the persistent If you are upgrading from Logstash 6.2.x or an earlier version and use the persistent
@ -144,5 +145,5 @@ When the queue is empty:
. Complete the upgrade. . Complete the upgrade.
. Restart Logstash. . Restart Logstash.
We are working to resolve issues with data incompatibilities in our 6.3.0 We are working to resolve issues with data incompatibilities so that these steps
release so that these steps won’t be required for future upgrades. won’t be required for future upgrades.