Undocumented "error" field appears in JSON logs

[baterja]

Bug Description

It's only a documentation "bug".

JSON logs structure reported there in the docs:
https://docs.flipt.io/configuration/observability#json
doesn't contain all possible fields because practice shows that "error" field may appear in the log:

{ 
  "L":"ERROR",
  "T":"2025-01-13T16:54:57Z",
  "M":"error getting file system from directory",
  "server":"grpc",
  "error":"flag <anonymised> rule 1 references unknown segment \"<anonymised>\""
}

We were relying on only putting "M" field into our centralized logging system so we missed important error details.

Version Info

v1.50.0

Search

• I searched for other open and closed issues before opening this

Steps to Reproduce

1. Use S3 as a flag definitions source.
2. Add a flag definition with a rule that uses a nonexisting "segment"

Expected Behavior

No response

Additional Context

No response

[dosubot]

Hey @baterja! I'm here to help you with any bugs, questions, or contributions. Let's tackle this together!

The "error" field in the JSON logs appears when there is an issue related to flag definitions, such as referencing a nonexisting segment. This is part of the error handling mechanism in the system, where specific errors are logged to provide more context about the issue. The logic for handling such errors is implemented in the internal/storage/fs/snapshot_test.go file, where errors related to unknown segments are captured and logged ^[1].

To address the documentation bug, it would be beneficial to update the documentation to include the "error" field as a possible entry in the JSON logs. This ensures that users are aware of all potential fields that might appear in the logs, allowing them to capture and process important error details effectively.

To continue talking to Dosu, mention @dosu.

---

^{Help Dosu learn! Give it feedback: Great Response | Irrelevant Answer | Incorrect Sources | Too Verbose | Hallucination | Other}

[markphelps]

Hey @baterja thanks for the issue!

In the above linked documentation (https://docs.flipt.io/configuration/observability#json) you can see a similar L key which stands for LEVEL, or log level. In the docs we just have 'INFO' as the value, but of course if there is an error it will log at 'ERROR' level.

"L": "INFO",

We could do a better job of describing those keys though I agree.

Some of those keys are also configurable, (L being one): https://docs.flipt.io/configuration/overview#logging

[baterja]

Thanks for transferring it to the documentation repo, I wasn't aware of its existence :)

[baterja]

Hello! It's great how fast you react to any issue reported there, but are you sure it should be completed? That report mainly addressed the lack of a description of an "error" field in the JSON log (particularly the error log). I see you added descriptions of the "main" fields of the JSON but the "error" field existence is still not mentioned.

[markphelps]

@baterja ah I see. I misunderstood the original issue. you're right that we should document the addition of the error field if its an error log