diff --git a/docs/index.asciidoc b/docs/index.asciidoc index 6cc5ee3fa..f77648a51 100644 --- a/docs/index.asciidoc +++ b/docs/index.asciidoc @@ -154,3 +154,7 @@ include::static/submitting-a-plugin.asciidoc[] include::static/glossary.asciidoc[] + +// Release Notes + +include::static/releasenotes.asciidoc[] diff --git a/docs/static/breaking-changes.asciidoc b/docs/static/breaking-changes.asciidoc index ebef1ac92..56f405a00 100644 --- a/docs/static/breaking-changes.asciidoc +++ b/docs/static/breaking-changes.asciidoc @@ -1,10 +1,63 @@ [[breaking-changes]] == Breaking changes +This section summarizes the breaking changes in the following releases: + +* <> +* <> +* <> +* <> + +[[logstash-breaking-changes-5-3]] +=== Logstash 5.3.0 Breaking Changes + +This section discusses the changes that you need to be aware of when migrating your application +from Logstash 5.2 to 5.3. + +[float] +==== Changes in Logstash Core + +==== Persistent queue + +The default location on disk where the queue data is stored has been changed from `/queue` to +`/queue/main`. The directory hierarchy now includes the pipeline ID which defaults to `main`. +This change was made to accommodate an upcoming feature where multiple, isolated pipelines can be run on +the same Logstash instance. In this future situation, each pipeline will have its own queue; hence the new directory +structure. + +**Upgrading to 5.3** + +If you are using the persistent queue feature and intend to upgrade to 5.3: + +* Ensure you completely drain the queue data in 5.2 by stopping the incoming data and processing all of the + in-flight events. +* Stop Logstash and manually move the files under `/queue/` to `/queue/main` before upgrading to 5.3. +* If you do not intend to process the data currently buffered in the queue in 5.2, you can manually delete + the `path.data/queue` directory before upgrading to 5.3. + +[float] +==== Breaking Changes in Plugins + +*`KV filter`*: `trim` and `trimkey` options are renamed to `trim_value` and `trim_key` respectively. Their behavior has been +changed as well to _trim_ the characters at the beginning or end of the values. + +[[logstash-breaking-changes-5-2]] +=== Logstash 5.2.0 Breaking Changes + +There are no breaking changes in this particular release. + +[[logstash-breaking-changes-5-1]] +=== Logstash 5.1.0 Breaking Changes + +There are no breaking changes in this particular release. + +[[logstash-breaking-changes-5-0]] +=== Logstash 5.0.0 Breaking Changes + This section discusses the changes that you need to be aware of when migrating your application to Logstash 5.0 from the previous major release of Logstash (2.x). [float] -=== Changes in Logstash Core +==== 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. @@ -153,7 +206,7 @@ were familiar with the RSpec framework, which is a Ruby testing framework. [float] -=== Breaking Changes in Plugins +==== Breaking Changes in Plugins [float] ==== Elasticsearch Output `workers` Setting Removed diff --git a/docs/static/releasenotes.asciidoc b/docs/static/releasenotes.asciidoc new file mode 100644 index 000000000..c9783f64a --- /dev/null +++ b/docs/static/releasenotes.asciidoc @@ -0,0 +1,66 @@ +[[releasenotes]] +== Release Notes + +This section summarizes the changes in the following releases: + +* <> + +[[logstash-5-3-0]] +=== Logstash 5.3.0 Release Notes + + +* Persistent queues: + ** Changed the default queue location on disk to include the pipeline's ID in the path hierarchy. + By default, the queue is now created under `/queue/main`. This breaking change was made to + accommodate an upcoming feature where multiple, isolated pipelines could be run on the same Logstash + instance. + ** Added a recovery process that runs during Logstash startup to recover data that has been written to the + persistent queue, but not yet checkpointed. This is useful in situations where the input has written data to + the queue, but Logstash crashed before writing to the checkpoint file. + ** Added exclusive access to the persistent queue on disk, as defined by the `path.queue` setting. Using a file + lock guards against corruption by ensuring that only a single Logstash instance has access to write to the + queue on the same path. ({lsissue}6604[Issue 6604]). + ** You can now safely reload the pipeline config when using persistent queues. Previously, reloading the + config could result in data corruption. In 5.3, the reload sequence has been changed to reliably shut down the + first pipeline before a new one is started with the same settings. + ** Fixed an issue where Logstash would stop accepting new events when queue capacity is reached even though events + were successfully acknowledged ({lsissue}6626[Issue 6626]). + +* Fixed a warning message when --config.debug is used with --log.level=debug ({lsissue}6256[Issue 6256]). + + +[float] +==== Input Plugins + +*`S3`*: + +* We now include the S3 key information in the metadata (https://github.com/logstash-plugins/logstash-input-s3/issues/105[Issue 105]). + +*`Unix`*: + +* The `host` and `path` fields are no longer overwritten if they are already provided by `add_field` config. + +==== Filter Plugins + +*`KV`*: + +* Breaking: The `trim` and `trimkey` options are renamed to `trim_value` and `trim_key` respectively (https://github.com/logstash-plugins/logstash-filter-kv/issues/10[Issue 10]). +* `trim_value` only removes the specified leading and trailing characters from the value. Similarly, `trim_key` + only removes the specified leading and trailing characters from the key (https://github.com/logstash-plugins/logstash-filter-kv/issues/10[Issue 10]). +* Added new options `remove_char_value` and `remove_char_key` to remove the specified characters from keys + (or values) regardless of where these characters are found (https://github.com/logstash-plugins/logstash-filter-kv/issues/10[Issue 10]). + +*`Grok`*: + +* Added an option to define custom patterns using `pattern_definitions` configuration. + +==== Output Plugins + +*`S3`*: + +* Fixed to use the correct `signature_version` for the SDK v2 library (https://github.com/logstash-plugins/logstash-output-csv/issues/129[Issue 129]). +* Fixed an issue which resulted in uploading empty files to S3 when using gzip compression (https://github.com/logstash-plugins/logstash-output-s3/issues/95[Issue 95]). + +*`CSV`*: + +* Updated to work with the 5.0 event API and threading contracts (https://github.com/logstash-plugins/logstash-output-csv/issues/10[Issue 10]).