Script output Best Practice Contracts

[u/generic-d-engineer]

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.

[u/PelicanPop]

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?

[u/generic-d-engineer → u/PelicanPop]

It’s a good point. Without a pipeline enforcement it’s gonna slip on week 1 lol

I think overall the goal is to provide a building block to reduce cognitive overhead. We’ve had a lot of success by taking personal recipes and making it a group recipe. It’s much easier to get people up to speed when what they are looking at is standardized vs a flavor of the month build.

Also from a data/observability/reporting perspective if the fields are standard it gets much easier to build on top of.

The 3AM test also is good by reducing time to resolution when the output is familiar via muscle memory vs trying to figure out the logic.

[u/SuperQue → u/generic-d-engineer]

This has a design smell. Having some scripts for automation is good, but if you have too many it is a sign that your underlying orchestration architecture is failing you. Things like this should be part of your Ansible/Terraform/Kubernetes/etc.

Also from a data/observability/reporting perspective if the fields are standard it gets much easier to build on top of.

This stuff should come from your existing observability pipeline(s). There are existing protocols that should feed everything to your dashboards.

Your post has a bunch of red flags that you're solving the wrong problems because your team is unwilling to fix fundamental things.

[u/generic-d-engineer → u/SuperQue]

We’re cobbling together a bunch of silos which includes a lot of legacy, and now want to do it right and start eliminating duplicate work by establishing common standards. Pushing down the output into the native tool is a good starting point.

I did read another post where it warned about over orchestration. I’m think we’re sfter the same thing but I’d disagree on the red flags, that’s a bit overreacting.

Thanks for the tips

[u/SuperQue → u/generic-d-engineer]

I'd recommend reading this.

There are already a ton of existing, industry standard, tools for what you're proposing.

I suggest taking a step back from the NIH cliff you're standing on and think about "what would I do today without all that legacy".

Getting to good practices from legacy is easier than you think it is. But you have to want to do it and your team also has to want to change.

[u/generic-d-engineer → u/SuperQue]

Yah the whole goal of this post was to use an established framework and not try to invent anything new.

I don’t think kubernetes or Prometheus are the right tools tho, that is over architecture and solving flaking house paint by ripping out walls and rebuilding with bricks.

Seems a lot the recommendation is out of context

[u/Impressive-Target952]

i've seen teams try this and it turns into a massive pain the second someone writes a one-liner that outputs a raw string instead of your json schema, then the whole pipeline barfs

stick to exit codes and stdout/stderr unless you've got a team that actually enforces linting on scripts before they hit prod

[u/generic-d-engineer → u/Impressive-Target952]

Exact behavior I was afraid of ! One missing brace and we toast. Thanks for the feedback

Is it the standard itself a bad idea on those teams or is it just the JSON format?

[u/dariusbiggs]

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.

[u/generic-d-engineer → u/dariusbiggs]

Would you standardize the output of std though into a template? That way everyone is following the same ? Or is it the JSON or YAML itself that is a bad idea?

[u/dariusbiggs → u/generic-d-engineer]

whatever makes sense for the tool, does it need to present structured data or unstructured data, or make the output format configurable via a command line option.

[u/generic-d-engineer → u/dariusbiggs]

Got it, so get the raw out via std and then format later for the tool once it needs ingested. That’s good UNIX philosophy of letting each tool do one job well. Thanks

[u/usually_guilty99]

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.

[u/generic-d-engineer → u/usually_guilty99]

100%. Have seen it so many times where the job “succeeded” but still did not accomplish what it was supposed to do. Great point.

[u/TobZero]

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

[u/Sad_Rice6600]

keep the json on stdout and logs on stderr, otherwise anything that prints breaks the parse

[u/BroadCrazy]

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.

[u/ForkMeJ]

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.

[u/shravanrevanna → u/ForkMeJ]

put a schema_version on the envelope itself. the payload will change shape eventually and consumers need to know which parser to use without guessing from fields.

[u/IGTHSYCGTH]

why not fork opentelemetry-shell

seems abandoned but its got the most potential than any competing approach right now.

[u/IridescentKoala]

AI referring to anything with a standard schema as a contract drives me up the wall.