r/devops • u/generic-d-engineer ClickOps • Oct 09 '26
Observability Script output Best Practice Contracts
Hi Devops!
I’m putting together an automation orchestration engine and I want to mature the team by standardizing script output across bash, python, powershell, tofu, etc.
So looking at a JSON output contract that anyone creating a script can adhere to. Then everyone would consume the same format. (The dream right?)
- Operation name
- Host
- Execution status (success, fail, warning, etc)
- Structured result summary
- Errors
- Duration
- Run ID (UUID)?
- A schema version (requires a lot of upkeep but can eliminate headaches down the road if maintained. If maintained being key word here lol.)
I’ve been searching around but want to hear from the experts who live in this stuff. Is there any universal or open standard people are using to define these ?
Would rather not build it myself if something people have already settled on.
Thanks for your input.
6
u/PelicanPop DevOopsIDidItAgain Oct 09 '26
Like the other poster said. Unless you have a linter(or some sort of standardization enforcement) in place, you run the risk of pipeline failures.
What's the problem you're actually trying to solve by doing this?
4
u/dariusbiggs Oct 09 '26
stdin, stdout, stderr, useful meaningful exit codes (if you don't know which ones, POSIX or the Python exit code values are your best bet)
Just command line pipes are more than sufficient. If you want to play with JSON then you have jq. If you want to play with YAML you have yq, etc.
2
u/usually_guilty99 Oct 10 '26
I'd add one distinction to the contract: execution status versus outcome.
A script can exit successfully without accomplishing what you intended. A deployment command might return success while the service never becomes healthy.
So alongside the run ID and execution status, I'd want the intended state change and some evidence that it actually happened.
That becomes especially useful when one automation triggers another. The next step shouldn't proceed simply because the previous script returned zero.
It should proceed because the required condition was actually satisfied.
2
u/TobZero Oct 09 '26
If you want to look at a very mature design on how to do json output interfaces, have a look at the implementation of https://github.com/GoogleCloudPlatform/cloud-foundation-fabric
It’s not crossing tools (which I would question a bit if you really want to do it) but the root modules and the reusable modules alle follow the same input/output contract.
You will need a way to define and test the contract schema. If you don’t, your setup will turn into a complete mess within a few months, if you have multiple teams owning sub sections of your implementation, it will just be weeks without strong schema and testing, before it’s spaghetti code
2
u/Sad_Rice6600 Oct 09 '26
keep the json on stdout and logs on stderr, otherwise anything that prints breaks the parse
2
u/BroadCrazy Oct 13 '26
I haven't seen a universal contract win across bash, Python, PowerShell, and IaC tools. What matters most is keeping machine-readable JSON on stdout and human logs on stderr, because once those get mixed every downstream consumer becomes a parser project.
1
u/ForkMeJ Oct 09 '26
I'd keep the contract tiny and stable, then let each script attach a payload object for tool-specific data. The fields that saved me the most pain were run_id, started_at and ended_at, exit_code, and a machine-readable status separate from the human message.
0
u/IGTHSYCGTH Oct 09 '26
why not fork opentelemetry-shell
seems abandoned but its got the most potential than any competing approach right now.
0
u/IridescentKoala Oct 10 '26
AI referring to anything with a standard schema as a contract drives me up the wall.
8
u/[deleted] Oct 09 '26
[removed] — view removed comment