From f9e4b0e6150e6f1856f07fe34b457eab764ec904 Mon Sep 17 00:00:00 2001 From: "Eric D. Schabell" Date: Fri, 25 Sep 2026 20:31:04 +0200 Subject: [PATCH] docs: pipeline: outputs: output-formats: document JSON nesting depth limit Add a Nesting depth limit section under JSON formats covering the 512 level cap applied when converting records to JSON (upstream commit 78b8e42bb not present in v5.1.2 or earlier): - Containers at the limit are replaced with null, not dropped, and the rest of the record is preserved. - An empty map or array at the limit still renders as {} or []. - The truncation warning is logged at most once per conversion. - State that maps/arrays through level 512 are preserved - Clarify non-empty containers at level 513 become null and their contents are omitted - Clarify empty containers at level 513 still serialize as {} or [] - Clarify depth warning is logged at most once per serialization pass - Explain pass scope: full queued-record array for json, one record for json_lines/json_stream - Note buffer-growth retries start a new pass and may log the warning again Signed-off-by: Eric D. Schabell --- pipeline/outputs/output_formats.md | 12 ++++++++++++ 1 file changed, 12 insertions(+) diff --git a/pipeline/outputs/output_formats.md b/pipeline/outputs/output_formats.md index 976a5ad8d..6edb2cbbf 100644 --- a/pipeline/outputs/output_formats.md +++ b/pipeline/outputs/output_formats.md @@ -23,6 +23,18 @@ The following example payloads are modified for readability. Records shown in example payloads are the three first commits of the Fluent Bit repository. +### Nesting depth limit + +In Fluent Bit version 5.1.3 and greater, converting a record to any of these JSON formats serializes at most 512 levels of nested maps and arrays. Maps and arrays through level 512 are preserved. When a record nests deeper than this limit, Fluent Bit writes each non-empty map or array at level 513 as `null`, omits its contents, and keeps the rest of the record intact. An empty map or array at level 513 is still written as `{}` or `[]`. + +Fluent Bit logs the following warning at most once for each serialization pass, no matter how many branches are affected: + +```text +[warn] [pack] msgpack to JSON conversion exceeded the maximum nesting depth (512), truncating remaining structure +``` + +With `json`, a pass covers the full array of queued records. With `json_lines` and `json_stream`, a pass covers one record. If the output buffer is too small, Fluent Bit grows it and retries in a new pass, which can log the warning again. + ### `json` Queued records encoded as a single JSON array of JSON encoded Fluent Bit records.