Inline shapers vs. pointers to files that contain shaper code

[philrz]

While acting as a new user of the brimcap analyze -config YAML, I made the mistake of thinking the shaper parameter was the name of a file containing my Zed shaper code, as opposed to it being the shaper code itself. I felt like this was an innocent mistake since there's other contexts where shapers are treated as files, such as the -I option to zed query, or the way that when we mention reference shaper configs in our docs we point at files in our repos.

If my would-be "shaper" had been somehow invalid and had caused a Zed parse error, I might have found my mistake sooner. Unfortunately, it ended up being valid Zed, effectively doing a text search for the string that's the pathname I provided. It matched nothing, effectively sending my logs to /dev/null. This gave me the mistaken impression that maybe the contents of my shaper script file were fundamentally broken and/or that there was a bug in Brimcap, so I burned a fair amount of time before figuring out my mistake.

A few thoughts for consideration:

1. If we do nothing else, I can just make sure we emphasize this strongly in the user docs.
2. The fact that degenerate Zed forms a quiet, no-op shaper could be seen as a general hazard of Zed itself. If there's a way we can identify what it means to be a "shaper" as opposed to any ol' Zed that might legitimately contain just a search, perhaps we could parse it and return errors in contexts like this that only expect a shaper.
3. Perhaps Brimcap itself could be enhanced such that the shaper parameter supports both in-line Zed as well as files, and the way each approach is specified in the YAML could be self-documenting in a way that would make it very difficult to repeat my mistake.