Why Graylog plugin and API client upgrades break at known release boundaries
When an in-house plugin or automation script that worked on an older Graylog fails after an upgrade, the cause is usually a documented breaking change, not a fault in the platform. The 6.0 release made Message constructors package-private, so plugins must create messages through MessageFactory. The 6.3 release requires plugin code that uses the database layer to switch to org.graylog2.database.MongoCollection. The 7.0 release changes entity creation to a CreateEntityRequest structure and rejects unknown JSON properties. Each of these is a known boundary that can be scheduled, tested and fixed before production cutover.
The supported route runs through the 6.x minor releases to reach 7.0, and the step order matters. Your code is affected at each boundary you cross, so confirm the exact sequence for your starting version in the upgrade documentation for Graylog 6.0, Graylog 6.3 and Graylog 7.0. Inventory every custom plugin, script, integration and API caller against those notes before you change any version number, because a plugin rebuilt for one boundary may still fail at the next.
This work covers your custom code and the integrations that call Graylog, not the Graylog server, its MongoDB or its search backend, which are planned separately. Decide early who owns each plugin and script, whether a rebuild or a rewrite is the better path, and where test coverage will come from. Ask any partner for a written scope that lists each plugin, each API call pattern and the versions you will test against, so that the effort is visible before work starts.
Which Graylog release changes affect custom code, and what each one requires
This table lists the documented Graylog 6.0, 6.3 and 7.0 changes that affect in-house plugins and API clients, with the impact on code and the action each one requires. Read each row against the code you own, starting with the release you are upgrading to. The main takeaway is that compile-time breaks surface during plugin builds, while the 7.0 API changes can fail silently in scripts that never see a build step.
| Change | Impact on custom code | Action needed |
|---|---|---|
| 6.0: Message constructors | Message constructors are package-private, so plugin code calling them no longer compiles. | Create messages through MessageFactory and rebuild the plugin against 6.0. |
| 6.0: jakarta namespace | Plugins written against the older namespace must use the jakarta namespace to load and build. | Update imports and dependencies, then rebuild the plugin for the jakarta namespace. |
| 6.3: database layer | Plugin code using the database layer must switch to org.graylog2.database.MongoCollection. | Replace direct database layer usage with MongoCollection and retest data access paths. |
| 7.0: CreateEntityRequest | Requests that create streams, dashboards and similar entities must use the CreateEntityRequest structure. | Rewrite entity creation calls and payloads, then test each creation path in a non-production cluster. |
| 7.0: unknown JSON properties | The API rejects requests containing unknown JSON properties, so payloads with stray or outdated fields fail. | Remove unrecognized fields from client payloads and validate requests against the 7.0 API before go-live. |
Plugin code or external API scripts: which fixes belong to which team
Teams that compile code against Graylog's server libraries own the most invasive fixes. A plugin can fail at build time, at class loading or at runtime, so the work starts with a rebuild against the target version and ends with a load test on a non-production node. Usually the team that wrote the plugin owns the change, and the team running Graylog schedules the upgrade around it.
- Message creation: Since Graylog 6.0, Message constructors are package-private, so code that calls them must create messages through
MessageFactoryinstead. - Database access: From Graylog 6.3, plugin code that uses the database layer must switch to
org.graylog2.database.MongoCollection, so collection wrappers need rewriting along with the build. - Entity and resource code: Plugins that create streams, dashboards or other entities should be reviewed against the Graylog 7.0 entity-creation changes, which the Graylog 7.0 upgrade notes describe.
- Rebuild and retest: Rebuild each plugin against the target version, then exercise inputs, searches, persistence and any scheduled work before it reaches production.
Confirm which Graylog version each plugin was compiled against and whether any plugin calls the database layer directly before you set the rebuild schedule.
Scripts, CI jobs and integrations that call the REST API are usually quicker to fix but easier to lose track of. They often sit in repositories owned by security operations, automation or application teams, and they may only surface when a scheduled job fails. The main 7.0 change affects how entity creation requests are shaped and validated.
- Entity creation payloads: Requests that create streams, dashboards and similar entities must follow the CreateEntityRequest structure introduced in Graylog 7.0. Scripts that post the older body shape will fail.
- Strict JSON validation: The 7.0 API rejects unknown JSON properties, so keys that were previously ignored, such as leftovers from copied examples, now cause errors. Remove them or test each payload against the new structure.
- Credentials in pipelines: List which CI jobs and scripts hold API tokens and run them against a test instance before production.
- Failure handling: Make scripts read response bodies and status codes so a rejected request stops the job instead of passing silently.
Confirm the full list of scripts, scheduled jobs and integrations that call the API, including those owned by other teams, and capture the request bodies each one sends.
The platform or security team coordinates both groups. Its work is to keep one accurate inventory, decide when code can move, and keep a way back if a change fails. This view matters most when plugins and scripts belong to several owners, because a fix that is correct for one team can still break a job another team depends on.
- Single inventory: Keep one register of plugins, scripts and integrations with the owner, the Graylog version each one targets, and the endpoints or database calls it makes.
- Release gating: Move plugin builds and script changes to production only after the matching Graylog version and the same builds run in staging with representative traffic.
- Rollback path: Keep the previous plugin artifacts and script versions available, and tie rollback to the backup taken before the upgrade starts.
- Evidence: Record test results, change approvals and owner sign-offs. These records support change reviews, but they do not replace an independent audit.
Confirm who approves production changes to Graylog and whether your staging environment can run the same plugin builds and integration traffic as production.
What to inventory and back up before changing any custom code
Custom plugins and API clients fail on upgrade for reasons that are easy to miss until a change is under way. The cards below cover the artifacts to list, the state to capture and the environment to test in before any code moves to a new Graylog version.
Plugin and script inventory
List every custom plugin, script, scheduled job and integration that talks to Graylog, and record the Graylog version each one was built and tested against. For plugins, note the Java and build dependencies, since the 6.0 move to the jakarta namespace changes what compiles. The inventory should name each artifact's owner, because a plugin nobody remembers building is the one most likely to break unnoticed. Developers and the team that deployed the integrations usually hold this knowledge.
Source control and reproducible builds
Confirm that every plugin and client is in version control and can be rebuilt from a tagged commit with pinned dependencies. A plugin that exists only as a compiled jar on one server cannot be rebuilt against the 6.0 or 7.0 changes if its source is lost. Check that the build still resolves the Graylog libraries it was written against, and record the commit each deployed artifact came from. Source owners and the platform or DevOps team usually control this.
Graylog configuration and MongoDB backup
Back up the Graylog server configuration and the MongoDB database that stores custom entities such as streams, dashboards, pipelines and other objects your code creates or reads. Restore tests matter more than the backup job itself, because the entity structures your scripts depend on are defined by the stored data. Confirm the backup covers the MongoDB version that Graylog requires for the target release. Platform operators and the MongoDB administrators usually hold these backups.
Non-production Graylog on the target version
Stand up a non-production Graylog on the exact target version, restored from a recent backup, with the same plugins loaded. Run each plugin, script and API client against it before any production change, including the entity creation calls that moved to the CreateEntityRequest structure in 7.0. This environment is the only place to see strict JSON validation rejections without affecting live ingestion. The platform team usually owns it, with the integration owners running the tests.
API consumer register
Record every system that calls the Graylog API, including its credentials, the endpoints it uses, the payload shapes it sends and the person accountable for it. Automation that creates streams or dashboards is the usual breakage point in 7.0, so flag those first. Include internal tools, monitoring jobs and third-party products that may have been configured years ago. Ask the security or identity team to confirm how each consumer's access tokens are issued and stored, and ask application owners to name a contact for each consumer.
How to move plugin code to MessageFactory and MongoCollection
Start by searching the plugin source for the two patterns that Graylog changed. The first is direct construction of Message objects. Since Graylog 6.0 the Message constructors are package-private, so any new Message(...) call in your code will stop compiling against 6.0 and later. Replace each call with a message created through MessageFactory, passing the same field values. The second pattern is database access that bypasses Graylog's own layer, such as direct use of the MongoDB Java driver or imports from older packages. From Graylog 6.3, plugin code that uses the database layer must switch to org.graylog2.database.MongoCollection. Search for MongoCollection, MongoDatabase, com.mongodb and jakarta imports together, because a single plugin often mixes old and new namespaces. Use the Graylog 6.0 upgrade notes and the Graylog 6.3 upgrade notes for the exact class names, method signatures and any removed helpers before you edit each call site, rather than guessing from the old code.
Build the plugin against the exact Graylog version you will run in production, not against the version it was written for. A clean compile confirms that every referenced class and method exists in that version and that the new imports resolve. Treat compile errors as a complete list of API breaks that the build can see, and fix them all before testing. Keep the old and new builds side by side in version control so the diff for each upgrade step is reviewable. Ask your team to confirm which Graylog version the build targets and whether the plugin's dependency versions match the platform it will load into.
Compile success does not prove the plugin behaves correctly. Code can compile when a message is created with the wrong defaults, when a query returns the same documents but in a different order, or when a database write succeeds against a collection that the new wrapper handles differently. Plan runtime checks that exercise each replaced path: create a message through the plugin, confirm it reaches the expected stream and index, read and write one entity through the database layer, and confirm that the results match the pre-upgrade behavior. Run these checks in a non-production environment restored from a current backup, and record the outputs so you can compare them after each Graylog upgrade step.
Upgrade sequence for plugins and API clients, with rollback points
This sequence moves each in-house plugin and script from its current Graylog build to the target version, with a tested version of each artifact and a restorable configuration backup kept at every stage. Each step ends with a check that tells you whether it can be closed or rolled back.
Inventory and classify every customization
Your team lists each in-house plugin, custom input or extractor, and every script or service that calls the Graylog API, including the Graylog version it was built against and the owner who maintains it. Classify each item by whether it uses Message constructors, the database layer, or entity creation calls, since those are the areas with breaking changes in the 6.0, 6.3 and 7.0 upgrades. Store the current plugin binaries, script versions and a configuration backup in a location the rollback process can reach. Done when every item has a row in the inventory with its owner, its build or version identifier, its change category, and a confirmed restorable copy of its previous artifact.
Rebuild plugins and fix the 6.0 and 6.3 code changes
Engineers rebuild each plugin against the target Graylog version and make two sets of code changes. Message objects can no longer be created with constructors, because those became package-private in Graylog 6.0, so code must create them through MessageFactory. Plugin code that uses the database layer must switch to org.graylog2.database.MongoCollection from Graylog 6.3. Engineers also confirm the jakarta namespace is used throughout, since plugins were rebuilt for it in the 6.0 line. Done when the plugin compiles against the target version, the build artifact is stored under a new version identifier, and the previous artifact remains available for rollback.
Move entity creation calls to CreateEntityRequest
Engineers update every call that creates streams, dashboards or similar entities so the request body follows the CreateEntityRequest structure introduced in Graylog 7.0. Each script is changed in a branch, with the previous version kept in version control so it can be restored by reverting to the prior commit. Done when a request built from the new structure returns the expected entity identifier in a test environment and the previous script version is still tagged and retrievable.
Remove unknown properties from JSON payloads
The Graylog 7.0 API rejects unknown JSON properties, so any payload that carries fields the API no longer accepts will fail. Engineers compare each request body against the API schema for the target version, remove extra fields, and add a validation step in the calling code so new unknown fields are caught before they are sent. Done when every payload in the test suite is accepted by the target API without errors and the validation step reports zero unexpected fields on a sample of real requests captured from the previous version.
Test in a non-production environment
Your team deploys the rebuilt plugins and updated scripts to a non-production Graylog that runs the target version and has been upgraded using the same platform steps planned for production. Testers exercise each plugin function, each input or extractor, and each automation path, and they check that data still flows through streams and pipelines as expected. Keep the production configuration backup and the previous plugin and script builds available during testing. Done when every item in the inventory has a passed test record, any failures have a recorded fix or a documented decision to defer, and a rollback has been rehearsed once in the non-production environment.
Roll out to production after the platform upgrade
Deploy the tested plugin builds and script versions to production only after the Graylog platform upgrade has completed and the cluster is healthy. Deploy in a planned order, starting with the lowest-risk integrations, and keep the previous artifacts in place until each integration has run successfully. If a plugin fails to load or an integration rejects requests, restore the previous plugin build or script version and use the configuration backup taken in the first step to return the system to its prior state. Done when each deployed item reports successful operation in its first full working cycle and the rollback path for each item has been confirmed as available.
Monitor and retire the rollback artifacts
Watch the Graylog server logs, the journal, and the error responses from each integration for an agreed observation period that your team sets based on its own change policy. Check that entity creation requests succeed, that no payloads are rejected for unknown properties, and that plugin-related errors do not appear in the logs. Once the observation period closes without incidents, archive the previous plugin builds and script versions under your retention rules rather than deleting them immediately. Done when the monitoring checks are clean for the full period, the change record lists every item as complete, and the archived artifacts are recorded with their location.
How to test plugins and API clients before and after the cutover
Testing for this cutover has to prove five things on the target version: the plugin loads and the server starts cleanly with it, messages are created through MessageFactory on every code path that used to call a Message constructor, database reads and writes through the org.graylog2.database.MongoCollection wrapper return the data your code expects, entity creation calls send the CreateEntityRequest structure, and payloads carrying unknown JSON properties are rejected rather than silently accepted. Build a test list for each of these from your own code, not from a generic checklist. Search your plugin and script repositories for direct Message construction, old database imports and hand-built JSON bodies for streams, dashboards and similar entities. Each hit is a test case. Run the plugin against a staging Graylog on the target version with a copy of your configuration, and confirm that the API calls your scripts make return the status codes and response bodies they parse. The upgrade notes for Graylog 7.0 are the reference for the request structure.
Plan the rollback before the cutover, because a plugin built for one major version usually cannot run on the previous one. Keep the previous plugin build, its source revision and the matching Graylog package or image in your artifact store, and keep the old scripts in version control with a tag that marks the last known-good release. Treat the platform and the custom code as one release unit: if you roll back Graylog, you roll back the plugin and scripts to the matching build at the same time. A platform rollback may also require restoring the configuration backup taken before the upgrade, since settings and database state changed during the upgrade may not be readable by the older server. Confirm the exact rollback steps for your deployment method, whether packages, Docker Compose or another orchestrator, with a rehearsal in staging, and confirm with Graylog which database changes are reversible before you rely on them.
What makes custom code upgrades take longer
The table compares the factors that change how much work it takes to port in-house plugins and API scripts across the 6.0 and 7.0 changes. Read each row as a question to answer about your own code before estimating effort, since the heaviest drivers are usually the number of internal API touchpoints and whether the source and build are still maintained.
| Driver | Why it adds work | How to reduce it |
|---|---|---|
| Plugins and internal API dependence | Plugins that call internal server classes must follow the 6.0 move to MessageFactory and the 6.3 switch to MongoCollection, so each internal call is a porting point. | Inventory every import from Graylog server packages and replace direct use with the documented entry points before the first upgrade. |
| Scripts calling entity creation | Automation that creates streams, dashboards or similar entities must match the 7.0 CreateEntityRequest structure, and unknown JSON properties are now rejected. | List every script and integration that posts to creation endpoints, then validate payloads against the 7.0 request shape in a test environment. |
| Source code and build pipeline availability | Without current source, a working build and pinned dependencies, a plugin cannot be rebuilt against the new Graylog version at all. | Confirm each plugin has version control, a reproducible build and a documented Graylog target version before scheduling the upgrade. |
| Test coverage and test data | Without automated tests or representative messages and entities, regressions appear only after go-live, when inputs and dashboards are already affected. | Write tests for message creation, database access and API calls, and keep anonymized sample data from production for replay. |
| Number of Graylog versions crossed | Moving from 5.2 through 6.x to 7.x means several sets of breaking changes apply to the same code, and each step can invalidate earlier fixes. | Map the breaking changes for each release in order and port the code once against the final target where the steps allow it. |
| In-house Java and plugin experience | Graylog plugins depend on Java build tooling and the server's internal conventions, so teams new to them spend more time locating the right change. | Pair plugin owners with engineers who have shipped Graylog plugins, or plan vendor-side review of the port before it goes live. |
| Environment access for testing | Plugins and scripts need a non-production Graylog cluster on the target version with comparable inputs, streams and permissions to prove the fix. | Provision a staging cluster that matches production topology and confirm the team can deploy test builds to it on demand. |
Questions teams ask before fixing Graylog plugins and API clients
What drives the cost of fixing Graylog plugins and API clients after an upgrade?
The main cost driver is how much code touches the changed areas: plugin classes that create messages, code that uses the database layer, and scripts that create streams, dashboards or other entities through the API. Each changed area needs reading the upgrade notes, locating affected code, rewriting it, and testing it against a running Graylog of the target version. Ask a provider for a fixed-scope quote that lists each plugin and script, the target version, the test environment, and who performs acceptance testing. Quotes are based on the written scope, so an inventory of your code is the first input to request.
How long does this work take, and what makes it longer?
Duration depends on the number of affected components, how much custom code was written against internal Graylog classes, and whether tests exist. Plugins that rely on several changed areas take longer than a single API script, and a missing test suite adds time because behavior has to be checked by hand. Ask the provider to state the timeline in the written scope, along with the assumptions behind it, such as how many release candidates or test cycles are included. No duration is given here because none has been published for this work.
What does your team need to provide before work starts?
Plan to supply the following before a provider can scope the work:
- Source code for every in-house plugin and script, with the build files that compile them
- Build access to your repository and artifact store, plus the Java and build tool versions in use
- A non-production Graylog environment on the target version, with representative test data such as sample streams and messages
- A list of every API consumer, including owners, schedules and the endpoints each one calls
The API consumer list matters most because it shows which scripts will fail when strict JSON validation is enforced.
Can our internal team fix these plugins without outside help?
Yes, if the team has Java developers who can work with the Graylog plugin build, and someone who can read the upgrade notes for each release and test against a non-production cluster. The changes are well documented, so the work is about locating affected code and verifying behavior. Outside help is most useful when plugins are numerous, when the original author has left, or when the team needs a fixed delivery date. Ask any provider to name who will perform the work and what knowledge transfer is included, since that affects your long-term ownership.
What happens to scripts that send unknown JSON properties after the 7.0 upgrade?
In Graylog 7.0 the API rejects unknown JSON properties, so a script that sends an extra or misspelled field in an entity-creation request will fail instead of silently ignoring it. Entity creation requests also use a CreateEntityRequest structure, so payloads built for earlier versions need to be reshaped. Scripts usually fail with an error response rather than corrupting data, but failures can go unnoticed if the script does not check responses. Ask the provider to test every consumer against the 7.0 API, log the error responses, and confirm that failed calls raise alerts in your automation.
Does this work include the Graylog platform upgrade itself?
No. This work covers changing in-house plugins and API clients so they run on the target Graylog version. The platform upgrade covers Graylog server nodes, MongoDB, the search backend, the journal and related prerequisites, and it is planned separately. The two are linked, because you usually need a test cluster on the target version before plugin fixes can be verified. Confirm the boundary in the written scope, and ask whether the provider will coordinate with your upgrade schedule.
Will the Graylog Open license affect plugins we build?
Graylog Open is licensed under SSPL-1.0, which is not an OSI-approved open source license, so any plugin you build should be reviewed by your legal or licensing team before distribution or redistribution. Plugins that run only inside your own organization raise different questions from plugins shared with partners or customers. Ask your counsel to review how the SSPL terms apply to your use, and include that review in your project plan. This page does not provide legal advice.
How DeployOpen scopes, fixes and supports Graylog plugin and API upgrades
DeployOpen works on custom Graylog plugins and API clients as a fixed-scope engagement: we inventory what breaks against the 6.0, 6.3 and 7.0 changes, fix it in your code, and hand over tested, documented components. Ongoing support for later Graylog releases is available as a retainer.
How we scope
- We inventory every in-house plugin, script and API client that touches Graylog, noting which ones create messages, use the database layer or call entity creation endpoints.
- We map each item to the documented 6.0, 6.3 or 7.0 change it depends on, so the written scope names the exact code paths to fix.
- The written scope lists deliverables, target Graylog version, environments covered and acceptance tests, and is agreed before work starts.
How we build
- We move message creation onto MessageFactory and switch database access to org.graylog2.database.MongoCollection where your plugin code requires it.
- We rework entity creation calls to send the CreateEntityRequest structure and remove any unknown JSON properties that strict validation would reject.
- We test each fix against a non-production Graylog node on the target version, covering plugin loading, API calls and failure responses.
How we hand over
- You receive the changed source, build files and a record of every API payload and class replacement, with the reason each change was made.
- We document how to rebuild and deploy each plugin, including the Graylog version it was tested against and any known gaps.
- We walk your engineers through the test cases so they can rerun them during your next upgrade without us.
How we support
- Support covers the agreed components only, and changes after handover follow the written scope or a new one.
- A retainer can cover reviews of new Graylog releases against your plugins and API clients before you upgrade.
- Retainer terms, response expectations and the release versions covered are set in writing, so confirm them in your quote.
