Improve documentation on V20180924111644_AddDefaultGrokPatterns migration

[edmundoa]

Expected Behavior

Inform users that the V20180924111644_AddDefaultGrokPatterns migration may fail during an upgrade from 2.5.1 to 3.0.0, if the user modified one of the "default" Grok Patterns.

Current Behavior

After taking care of all things mentioned in the upgrade guide and starting Graylog using 3.0.0, I could see one of the migrations fail in the server logs.

Looking a bit into it, I realised I had previously modified the Grok Pattern mentioned in the stack trace (SYSLOGPROG) while using 2.5.1 and that seems to be the cause of the error.

Server error log

2019-01-31 13:16:24,755 ERROR: org.graylog2.periodical.ConfigurationManagementPeriodical - Error while running migration <V20180924111644_AddDefaultGrokPatterns{2018-09-24T11:16:44Z}>
org.graylog2.contentpacks.exceptions.ContentPackException: Failed to install content pack <a3ce55ad-bdf3-7a50-305c-1e5bf3de6eca/1>
        at org.graylog2.contentpacks.ContentPackService.installContentPack(ContentPackService.java:158) ~[graylog.jar:?]
        at org.graylog2.contentpacks.ContentPackService.installContentPack(ContentPackService.java:99) ~[graylog.jar:?]
        at org.graylog2.migrations.V20180924111644_AddDefaultGrokPatterns.upgrade(V20180924111644_AddDefaultGrokPatterns.java:76) ~[graylog.jar:?]
        at org.graylog2.periodical.ConfigurationManagementPeriodical.doRun(ConfigurationManagementPeriodical.java:43) [graylog.jar:?]
        at org.graylog2.plugin.periodical.Periodical.run(Periodical.java:77) [graylog.jar:?]
        at java.lang.Thread.run(Thread.java:748) [?:1.8.0_191]
Caused by: org.graylog2.contentpacks.exceptions.DivergingEntityConfigurationException: Expected Grok pattern for name "SYSLOGPROG": <%{PROG:program}(?:\[%{POSINT:pid}\])?>; actual Grok pattern: <%{PROG:progra
m}(?:\[%{INT:pid}\])?>
        at org.graylog2.contentpacks.facades.GrokPatternFacade.compareGrokPatterns(GrokPatternFacade.java:138) ~[graylog.jar:?]
        at org.graylog2.contentpacks.facades.GrokPatternFacade.lambda$findExisting$0(GrokPatternFacade.java:131) ~[graylog.jar:?]
        at java.util.Optional.ifPresent(Optional.java:159) ~[?:1.8.0_191]
        at org.graylog2.contentpacks.facades.GrokPatternFacade.findExisting(GrokPatternFacade.java:131) ~[graylog.jar:?]
        at org.graylog2.contentpacks.facades.GrokPatternFacade.findExisting(GrokPatternFacade.java:119) ~[graylog.jar:?]
        at org.graylog2.contentpacks.ContentPackService.installContentPack(ContentPackService.java:131) ~[graylog.jar:?]
        ... 5 more

Possible Solution

I am not sure how often users would modify one of the provided Grok Patterns, but I guess somebody will face this situation.

In my opinion, the minimum solution would be to warn people in the documentation about this and let them know what to do if that happens. Showing a more friendly message during the migration on what happened and what to do next should also be considered.

The documentation and error message should also indicate if the old Grok Patterns were modified by this migration or not, as this is unclear at the moment.

Steps to Reproduce (for bugs)

1. Modify one of the "default" Grok Patterns in 2.5.1
2. Upgrade to 3.0.0
3. Migration cannot run and (I guess) Grok Patterns were left as they were

Your Environment

• Graylog Version: Graylog 3.0.0-rc.2-SNAPSHOT (28d3724)