Why a Graylog 5.2 to 6.0 upgrade needs its own plan
A Graylog 5.2 to 6.0 upgrade is manageable when every change the upgrade notes document is inventoried before the change window opens. The changes are specific: data_dir no longer has a default and must be set in the configuration file, the jvm_classes_loaded metric is renamed to jvm_classes_currently_loaded, plugins must be adjusted for the jakarta namespace, and the processor buffer defaults now depend on CPU cores. Each one can break a running node or a dashboard if it is discovered during the cutover rather than before it.
The reason to plan this as its own project is that most of these changes fail quietly or at startup. Graylog 6.0 stops the server from starting when an incompatible plugin is present, so in-house plugins and any third-party plugins need a compatibility check before the server image or package changes. The JMTE update also rejects unquoted string comparisons in if statements, which means pipeline rules and processing logic that worked on 5.2 may need review. Your team should list every plugin, pipeline and monitoring query, then confirm which ones depend on the changed behavior.
This page follows the path that the Graylog 6.0 upgrade notes describe, starting from 5.2. It does not assume any other version path, and it does not cover the later 6.x minor releases or the move to 7.x, which have their own sibling pages. Before you schedule anything, confirm your current version in your own environment and read the Graylog 6.0 upgrade notes in full, since they are the reference for any detail this page summarizes.
What changes in Graylog 6.0 and what each change requires
This table lists each Graylog 6.0 change from the upgrade notes, its effect on a running 5.2 deployment, and the action to take before or during the upgrade. Read it as a pre-upgrade checklist: the first two rows affect configuration files and monitoring, while the plugin and JMTE rows can stop the server from starting or change how existing rules evaluate.
| Change | Impact | Action needed |
|---|---|---|
| Default value of data_dir removed | Graylog 6.0 no longer falls back to a default, so a node without the setting may not start as it did on 5.2 | Set data_dir explicitly in the server configuration file on every node before upgrading |
| jvm_classes_loaded renamed to jvm_classes_currently_loaded | Dashboards, alerts or scrapers that read the old JVM metric name will show no data or stop matching | Search for the old metric name in dashboards and monitoring rules, then update it to the new name |
| All plugins must be adjusted for 6.0 | Plugins built for 5.2 may not load on 6.0 | Inventory every installed plugin, confirm a 6.0-compatible build with its vendor or author, and test in staging first |
| Incompatible plugins stop the server from starting | A single unsupported plugin can block the whole node from starting after the upgrade | Remove or replace incompatible plugins before the production upgrade and keep a rollback copy of the 5.2 configuration |
| Several javax packages moved to jakarta | Custom plugins or code compiled against javax imports will fail to build or load | Rebuild in-house plugins against the 6.0 libraries and update package imports from javax to jakarta |
| processbuffer_processors and outputbuffer_processors defaults depend on CPU cores | Nodes with different core counts can run different thread counts, which changes throughput and load | Set both values explicitly where you need predictable behavior, and check journal and buffer metrics after the upgrade |
| JMTE rejects unquoted string comparisons in if statements | Processing pipeline or other JMTE rules that compare strings without quotes will fail or behave differently | Review every if statement in templates and rules, add quotes around string literals, and test with sample messages |
How the 6.0 breaking changes hit a running cluster
The 6.0 changes matter most because some of them stop a node from starting at all, and others change behavior without any error. The most visible failure is plugin incompatibility: the Graylog 6.0 upgrade notes state that all plugins must be adjusted for 6.0, that incompatible plugins prevent the server from starting, and that several javax packages moved to jakarta. A team running in-house or third-party plugins should inventory each one, confirm a 6.0-compatible build exists, and test it on a staging node before the production cluster is touched. Because the failure happens at startup, a rolling restart can leave a node down with inputs shifting to the remaining nodes, so plan that capacity before you begin.
Two changes fail quietly. The renamed JVM metric, jvm_classes_loaded becoming jvm_classes_currently_loaded, means dashboards, alert conditions and external monitoring that read the old name will show no data or stale values after the upgrade rather than raising an error. Search the monitoring stack for the old name and update it as part of the change. The JMTE update is similar: it rejects unquoted string comparisons in if statements, so pipeline rules and index set or template logic that worked before may stop matching. Review every rule that uses such comparisons and confirm the results against sample messages.
The processor defaults deserve the most deliberate review. In 6.0, the defaults for processbuffer_processors and outputbuffer_processors depend on available CPU cores, so a node that you have not set explicitly may run with different thread counts after the upgrade. Record the current values from each node's configuration, decide whether to pin them, and check throughput and journal behavior after the change. Also confirm that the data_dir setting is present in each configuration file, since 6.0 no longer supplies a default for it. Because your own plugin set, pipeline rules and node hardware determine which of these changes apply, confirm each item against your environment and the Graylog 6.0 upgrade notes before you schedule the change.
What to prepare before touching Graylog 5.2
Most failed Graylog 6.0 upgrades trace back to work that was skipped before the first package was installed. The six items below cover configuration, plugins, pipeline logic, monitoring, a rehearsal environment and processor sizing, and each one should have an owner and a written result before the change window is booked.
Back up MongoDB and configuration
Take a full MongoDB backup of the Graylog configuration database, and copy the server.conf file and any service overrides from every Graylog node. Test that the backup restores on a separate host, not just that the files exist. Record the current data_dir value if one is set, because Graylog 6.0 no longer supplies a default and the server needs it set explicitly in the configuration file. Confirm with your backup owner how long a restore takes and who can authorize it.
Inventory plugins and jakarta status
List every in-house and third-party plugin, its source, its build and the owner who can rebuild it. Graylog 6.0 requires all plugins to be adjusted, and an incompatible plugin stops the server from starting, so this list determines whether the upgrade is possible on the planned date. Several javax packages moved to jakarta, so ask each vendor or internal team whether a 6.0 build exists and whether it has been tested against your Graylog version.
Review JMTE if-statements and pipeline rules
Export every pipeline rule and extract each if condition that compares strings. The 6.0 update of the JMTE template engine rejects unquoted string comparisons, so a rule that worked for years can fail after the upgrade. Test each affected rule against sample messages in staging and record the fixed version. Check dashboards and event definitions that use the same expressions, since they are easy to miss.
Record current JVM metric names
Export the list of JVM metric names that your monitoring system, dashboards and alert rules query today. Graylog 6.0 renames the jvm_classes_loaded metric to jvm_classes_currently_loaded, so any panel or threshold that uses the old name will go blank or stop alerting. Ask your monitoring team to confirm which dashboards and alerts reference the old name and to prepare the replacement before the cutover.
Build staging from production configuration
Create a staging environment from a recent copy of production configuration, including the MongoDB data, inputs, streams, pipelines and index set settings, with production secrets replaced. Confirm with your platform team that staging uses the same OpenSearch or Data Node version and similar sizing, since results from an undersized test cluster can hide problems. Use staging to run the full upgrade, the plugin startup checks and a sample of searches before production is scheduled.
Document the processor settings decision
Graylog 6.0 derives the defaults for processbuffer_processors and outputbuffer_processors from available CPU cores, so a host that previously ran on explicit values may behave differently after the upgrade. Record the current values from each node, decide whether to keep them or accept the new defaults, and write down the reason. Confirm the CPU count on every node with your infrastructure team, because nodes with different hardware may need different settings.
Upgrade sequence from 5.2 to 6.0 with checks and rollback points
This sequence moves a running Graylog 5.2 deployment to 6.0 in an order that keeps a known-good state available at every stage. Each step ends with a check you can confirm before moving on, and a rollback point you can return to if it fails.
Back up and record the current state
The platform or operations owner records the exact Graylog 5.2 server version on every node, then backs up the MongoDB configuration database, the server configuration file, plugin binaries, and the OpenSearch or Data Node index data or snapshot repository. Export or copy the current input, stream, pipeline, event definition and index set configuration so you can compare it after the upgrade. Check that a test restore of the MongoDB backup completes on a separate host. The output is a dated backup set and an inventory file, and the rollback point is the restored 5.2 stack on the same hosts.
Set data_dir explicitly in the configuration
The Graylog administrator adds an explicit data_dir value to the server configuration file on every Graylog node, because Graylog 6.0 no longer applies a default. Choose a directory that the Graylog service user can write to, and confirm that it exists with the right ownership before the service starts. Check the value on each node against the others so that nodes do not diverge. The output is a configuration file that sets data_dir on every node, and the rollback point is the unmodified 5.2 configuration file kept from step one.
Rebuild or replace plugins for jakarta
The plugin owner lists every installed plugin and confirms, with each vendor or maintainer, that a build exists for Graylog 6.0. Graylog 6.0 moved several javax packages to jakarta, and an incompatible plugin stops the server from starting, so treat any plugin without a 6.0 build as a blocker. For in-house plugins, rebuild against the 6.0 libraries, run them in a test node, and confirm the server starts with each one loaded. The output is a signed-off plugin list with a version for each entry, and the rollback point is the 5.2 plugin directory kept intact.
Update monitoring for the renamed JVM metric
The monitoring owner changes any dashboard, alert or scrape rule that reads jvm_classes_loaded to use jvm_classes_currently_loaded, which is the name Graylog 6.0 exposes. Search your monitoring system for the old name across dashboards, recording rules and alert definitions, and confirm that no alert still points to it. Check that the new metric returns values on a staging node after its first start. The output is a monitoring configuration with no references to the old metric name, and the rollback point is the saved copy of the 5.2 monitoring configuration.
Review string comparisons in templates and rules
The Graylog content owner searches message templates, pipeline rules and any other JMTE expressions for if statements that compare against unquoted strings, because the JMTE update in 6.0 rejects them. Quote each string literal, then test the changed templates and rules against sample messages in a staging environment and compare the output with the 5.2 output. Confirm that the pipeline simulator reports no errors for the rules you changed. The output is a reviewed list of templates and rules with the fixes applied, and the rollback point is the exported 5.2 content from step one.
Set processor defaults deliberately
The operations owner decides the values for processbuffer_processors and outputbuffer_processors on each node, rather than relying on the 6.0 defaults, which depend on the available CPU cores. Compare the CPU count on each node, since nodes with different hardware may need different values, and record the chosen numbers in the configuration. Confirm that the message journal and buffers behave as expected on staging under representative load. The output is a documented processor setting per node, and the rollback point is the 5.2 settings recorded in step one.
Upgrade and verify a staging node
The platform team upgrades one staging Graylog node to 6.0, starting from the backups and configuration changes made in the earlier steps, and checks the server log for plugin load errors and startup failures. Confirm the node reaches a running state, that its inputs accept messages, that searches return results from existing indices, and that event definitions evaluate. Compare the results with the 5.2 baseline you recorded. The output is a signed-off staging node with the test results attached, and the rollback point is reinstalling the 5.2 package and restoring the backed-up configuration on that node.
Upgrade production nodes in sequence
The platform team upgrades production Graylog nodes one at a time, confirms each node is healthy before starting the next, and keeps inputs flowing through the remaining nodes and the message journal. Each node gets the same configuration and plugin set that passed staging. Confirm the cluster shows all nodes on 6.0 before finishing. The output is a fully upgraded cluster, and the rollback point for each node is the 5.2 package with its backed-up configuration, applied one node at a time.
Verify inputs, journal and searches
The operations owner checks that every input is in the running state, that the message journal drains without growing, and that searches, dashboards and event definitions return the results you expect over a known time range. Compare message counts for a sample period with the 5.2 records and confirm alerts still fire against test events. Record the results and keep the 5.2 backup until this check has passed for a period your team agrees in advance. The output is a signed verification record, and the rollback point is the 5.2 backup set until verification is signed off.
How to test the upgrade and roll back if it fails
A test pass for the Graylog 5.2 to 6.0 upgrade should prove that the server works end to end, not only that it starts. Confirm first that the Graylog server starts with every plugin loaded, since Graylog 6.0 stops the server from starting when a plugin is incompatible. Then check input ingestion: each input should report messages arriving, and the message journal should drain after the restart rather than keep growing. Compare search results for a fixed query and time range before and after the upgrade so you can show that the same data is still searchable. Finally, fire a test event definition, confirm its notification reaches the intended channel, and check that dashboard widgets read the right metrics. Renamed JVM metrics such as jvm_classes_currently_loaded are a common reason a widget goes blank, so review every panel that uses JVM data.
Rollback means restoring the configuration and data you backed up to the prior version, not patching the new version in place. Keep the backup of graylog.conf, the MongoDB data and the search backend, and confirm you can restore each of them on a separate host before the window opens. Because the 6.0 upgrade removes the default for data_dir, a restored configuration must still set that key explicitly, or the older version will be started with settings that no longer match your environment. Confirm the exact restore steps with the Graylog upgrade notes for Upgrading to Graylog 6.0 and with your own backend version records before you rely on them.
Before the window starts, name one owner who can call the rollback and write down the decision point: the specific checks that must pass, and the point after which rolling back costs more than fixing forward. Agree who approves the decision, who communicates with the teams that depend on alerts and dashboards, and how inputs are paused or held while the restore runs. Record the results of each check in the change ticket so the decision can be reviewed later. Ask your team or partner to state in writing how long the restore is expected to take in your environment, since no general figure applies to every deployment.
What makes a Graylog 6.0 upgrade take longer
This table lists the factors that lengthen a Graylog 5.2 to 6.0 upgrade, the direction each one pushes the work, and how to measure it in your environment before you ask for a quote. Read it as a checklist: the more a row applies to your deployment, the more planning and validation the upgrade will need. Count each driver during scoping, since the inventory is what separates a short plan from a long one.
| Driver | Effect on the work | How to scope it |
|---|---|---|
| Custom plugins | Each in-house plugin must be checked against the jakarta namespace change and rebuilt, and an incompatible plugin stops the server from starting. More plugins, or plugins that depend on internal APIs, extend build and test time. | List every plugin, its source owner, and whether it has tests. Confirm which ones need code changes versus a rebuild. |
| Pipeline rules and JMTE templates | The JMTE update rejects unquoted string comparisons in if statements, so each template and rule that uses them needs review. Larger libraries mean more manual edits and more test messages to replay. | Export pipeline rules and templates, search for unquoted comparisons, and count the rules that affect dashboards or alerts. |
| Node count and cluster layout | A single node has one configuration to change. A cluster needs consistent settings across nodes, a controlled order of restarts, and checks that inputs keep flowing through the journal during each step. | Record how many Graylog nodes run, which node is the leader, and whether a load balancer sits in front of them. |
| MongoDB and index data volume | Backups and restore tests take longer as configuration and index data grow. Large index sets also lengthen the time needed to confirm that search and retention still behave as before. | Measure the MongoDB database size and the stored index volume, and confirm the backup method and restore test window with your team. |
| Dashboards and monitoring tied to JVM metric names | The jvm_classes_loaded metric is renamed to jvm_classes_currently_loaded in 6.0. Every dashboard, alert or scrape rule that reads the old name needs an update and a check that data still arrives. | Search monitoring tools and Graylog dashboards for the old metric name and list each owner who must approve the change. |
| Staging validation scope | Staging needs a copy of the production configuration, real plugins and representative traffic. The more inputs, streams and alerts you must prove, the longer the test cycle and the more sign-offs are needed. | Define the list of inputs, streams, event definitions and reports to test, and agree the pass criteria before the staging run starts. |
| Explicit data_dir and processor settings | The data_dir setting has no default in 6.0 and must be written into the configuration file, and processor defaults now follow CPU core count. Hosts with different hardware may need different values reviewed. | Compare configuration files across nodes, confirm the data directory path on each host, and note the core count used for processor sizing. |
Questions teams ask before a Graylog 5.2 to 6.0 upgrade
What does a Graylog 5.2 to 6.0 upgrade cost, and what drives the price?
The cost depends on how many Graylog server nodes, MongoDB and OpenSearch or Data Node components sit in scope, how many custom plugins need rework, and how many parsing pipelines, dashboards and API clients must be checked after the move. A fixed-scope quote is built from those inputs, so the largest drivers are plugin count and whether the environment is a single node or a multi-node cluster. Ask for the quote to separate one-time work (assessment, plugin changes, the upgrade itself, test evidence) from anything recurring, such as ongoing support or a retainer. DeployOpen does not publish a price list, so ask for a written scope before comparing numbers.
How long does the upgrade take in a typical environment?
Duration follows the environment more than the version pair. A single development node with no custom plugins moves much faster than a production cluster with in-house plugins, several inputs, a load balancer and strict change control. The longest items are usually plugin rebuilds for the jakarta namespace, testing parsing and alerting after the processor defaults change, and waiting for change windows. Confirm the duration in the written scope, and ask which steps depend on your own approvals, test environments or backup restores.
What must our team provide before the upgrade starts?
The team must provide administrative access to the Graylog servers, MongoDB and the search backend, plus current backups of configuration and data before any change is made. Source code and build files for every custom plugin are essential, because Graylog 6.0 requires all plugins to be adjusted and an incompatible plugin stops the server from starting. You also need named owners for inputs and dashboards, a test environment that matches production closely enough to prove parsing and alerts, and agreed change windows with a rollback decision point.
Can our in-house team perform the 5.2 to 6.0 upgrade without a partner?
Yes, if the team has Linux and MongoDB operations experience, can read the Graylog 6.0 upgrade notes closely, and has the time to test. The work is well defined: set the data_dir value explicitly, rebuild or verify plugins, review metric names used in monitoring, review templates that use string comparisons, and check processor settings against available CPU cores. The main risk is the untested edge: a plugin nobody maintains or a dashboard that quietly stops working. A partner adds value mainly when the team lacks capacity or plugin development skills, or when it needs a documented, repeatable test record.
Does Graylog Open licensing affect the upgrade work?
Graylog Open is licensed under SSPL-1.0, which is not an OSI-approved open source license, so the license terms apply to how you run and redistribute the software, not to the upgrade steps themselves. Confirm with your legal and procurement teams whether that license is acceptable for your use. Some features you may rely on, such as certain inputs, archive restore, or Security content, depend on an Enterprise or Security edition. Check which features your current deployment uses, because a plugin or feature that needs a paid edition must be confirmed before the upgrade is scoped.
What should we ask for in a fixed-scope quote?
Ask for a written scope that lists each Graylog node, MongoDB member, search backend component and input in scope, plus the named plugins and their source status. The quote should state the deliverables: an updated configuration, rebuilt or verified plugins, a validation checklist covering inputs, pipelines, dashboards, event definitions and API clients, a rollback plan and a closing report. It should also state exclusions, the assumptions about your environment, the change windows you must provide, and the dependencies on your own approvals. Ask how any change request after signing is priced.
What does the engineer need to check before and after the upgrade?
Before the upgrade, confirm that the configuration file sets data_dir explicitly, since version 6.0 removes its default, and that every plugin is confirmed compatible with the 6.0 build. Review any monitoring that reads the jvm_classes_loaded metric, because it is renamed to jvm_classes_currently_loaded. Review JMTE if statements that compare unquoted strings, and confirm that processbuffer_processors and outputbuffer_processors suit the CPU cores on each node. After the upgrade, check that the journal drains, inputs receive messages, and searches and event definitions return expected results.
How DeployOpen scopes and delivers a Graylog upgrade
DeployOpen is a Chainscore Labs company that plans, implements, customizes, hardens, backs up, upgrades, documents and supports self-hosted open-source platforms inside your own infrastructure. For a Graylog 5.2 to 6.0 upgrade, we start from your inventory of plugins, configuration files and automation, then plan and test the changes in a non-production environment before anything touches production.
How we scope
- Inventory every Graylog server node, its server.conf settings and whether data_dir is explicitly set.
- List every installed plugin and confirm with its vendor or maintainer that a Graylog 6.0 build exists.
- Record API clients, scripts and processing rules that use metrics names, if statements or buffer tuning.
How we build
- Rehearse the upgrade on a copy of production, including the MongoDB and OpenSearch or Data Node versions your stack requires.
- Adjust or replace plugins and custom code for the jakarta namespace changes, then test that the server starts cleanly.
- Review processing rules for unquoted string comparisons, which the updated JMTE rejects, and confirm processor buffer defaults against your CPU count.
How we hand over
- Deliver a written runbook with the pre-upgrade backup steps, the rollback point and the post-upgrade checks in order.
- Document the configuration changes, renamed metric names for dashboards and alerts, and the plugin versions in use.
- Walk your operations team through the verification steps so they can repeat them on later upgrades.
How we support
- Engagements are fixed-scope, with scope, deliverables and timelines agreed in writing before work starts.
- Ongoing support, upgrades and continuous testing are available as a retainer after the upgrade is complete.
- Ask any partner to confirm in writing which Graylog versions, plugins and environments their quote covers.
