reorganize configuration syntax intro #849
Conversation
There was a problem hiding this comment.
High level LGTM, pending a review from @clayton-cornell for grammar/style/etc. I left a few questions but I'm fine with this being merged. Thanks!
| * Attributes appear within blocks and assign a value to a name. | ||
| * Expressions represent a value, either literally or by referencing and combining other values. | ||
| You use expressions to compute a value for an attribute. | ||
| ## Blocks |
There was a problem hiding this comment.
Are we concerned about any potential confusion now that blocks (which are composed of attributes) are explained before attributes?
There was a problem hiding this comment.
If this is a concern, but the ordering is still preferred, maybe we can add some kind of teaser to explain attributes, something like:
You use Blocks to configure components and groups of settings called attributes.
There was a problem hiding this comment.
I think this suggestion is more clear and a good replacement for line 68.
|
|
||
| You use _Blocks_ to configure components and groups of attributes. | ||
| Each block can contain any number of attributes or nested blocks. | ||
| ## Configuration syntax design goals | ||
|
|
||
| ```alloy | ||
| prometheus.remote_write "default" { | ||
| endpoint { | ||
| url = "http://localhost:9009/api/prom/push" | ||
| } | ||
| } | ||
| ``` | ||
| {{< param "PRODUCT_NAME" >}} is designed with the following requirements in mind: | ||
|
|
||
| The preceding example has two blocks: | ||
| * _Fast_: The configuration language must be fast so the component controller can quickly evaluate changes. | ||
| * _Simple_: The configuration language must be easy to read and write to minimize the learning curve. | ||
| * _Debuggable_: The configuration language must give detailed information when there's a mistake in the configuration file. | ||
|
|
||
| * `prometheus.remote_write "default"`: A labeled block which instantiates a `prometheus.remote_write` component. | ||
| The label is the string `"default"`. | ||
| * `endpoint`: An unlabeled block inside the component that configures an endpoint to send metrics to. | ||
| This block sets the `url` attribute to specify the endpoint. | ||
| The {{< param "PRODUCT_NAME" >}} configuration syntax is a distinct language with custom syntax and features, such as first-class functions. | ||
|
|
||
| * Blocks are a group of related settings and usually represent creating a component. | ||
| Blocks have a name that consists of zero or more identifiers separated by `.`, an optional user label, and a body containing attributes and nested blocks. | ||
| * Attributes appear within blocks and assign a value to a name. | ||
| * Expressions represent a value, either literally or by referencing and combining other values. | ||
| You use expressions to compute a value for an attribute. |
There was a problem hiding this comment.
Likely not in scope for this PR, but I wonder if this content adds anything new and if it makes more sense to merge it into other headers.
WDYT about the long-term value of this section @moxious?
There was a problem hiding this comment.
I was thinking the same. These points feel like a repetition or a rephrase of previous info... and it might be better to find a way to rephrase and fit it into the content around lines 59-65... somewhere in that area. Might help to commit some of the other changes and do a make docs so this can all be read in the rendered output.
There was a problem hiding this comment.
Noting the goals of the design for a configuration syntax is, in my view - of primary interest to the people who want to hack on the syntax or contribute to core alloy. So it's pretty advanced material. That's why I chose to locate it at the bottom. It wasn't in the scope of this PR to try to remove something, but being frank - if you're a beginning user you probably won't read this, because just knowing how to use the config syntax is enough.
If I were to move this content, I would move it into a section that's about "how to contribute to alloy" or "why we did what we did". Very useful information to gate what kind of contributions would be welcome.
| // Collection: mount a local directory with a certain path spec | ||
| local.file_match "applogs" { | ||
| path_targets = [{"__path__" = "/tmp/app-logs/app.log"}] | ||
| } |
There was a problem hiding this comment.
local.file_match is a weird one, as it fits into the same bucket as the discovery components. It's not collecting any data, but performs discovery to enrich other components.
Do you think this distinction is useful at the introduction level? If so, maybe it could be a fourth category of components so the categories become:
- Data enrichment (local.file_match, discovery.kubernetes, etc.)
- Collection
- Transformation
- Delivery
I'm ok with either; I'll defer to your judgment for what makes the most sense for high-level introductory content.
There was a problem hiding this comment.
I borrowed this from a worked example my team did, I don't have anything wrapped up in its specifics.
If we can keep the example technically correct while making it shorter & simpler, that's a win. We specifically don't need to teach anything advanced here, it's only there to demonstrate the "pipeline/flow" concept with a simple example anyone can follow (report logs)
| * Attributes appear within blocks and assign a value to a name. | ||
| * Expressions represent a value, either literally or by referencing and combining other values. | ||
| You use expressions to compute a value for an attribute. | ||
| ## Blocks |
There was a problem hiding this comment.
I think this suggestion is more clear and a good replacement for line 68.
|
|
||
| You use _Blocks_ to configure components and groups of attributes. | ||
| Each block can contain any number of attributes or nested blocks. | ||
| ## Configuration syntax design goals | ||
|
|
||
| ```alloy | ||
| prometheus.remote_write "default" { | ||
| endpoint { | ||
| url = "http://localhost:9009/api/prom/push" | ||
| } | ||
| } | ||
| ``` | ||
| {{< param "PRODUCT_NAME" >}} is designed with the following requirements in mind: | ||
|
|
||
| The preceding example has two blocks: | ||
| * _Fast_: The configuration language must be fast so the component controller can quickly evaluate changes. | ||
| * _Simple_: The configuration language must be easy to read and write to minimize the learning curve. | ||
| * _Debuggable_: The configuration language must give detailed information when there's a mistake in the configuration file. | ||
|
|
||
| * `prometheus.remote_write "default"`: A labeled block which instantiates a `prometheus.remote_write` component. | ||
| The label is the string `"default"`. | ||
| * `endpoint`: An unlabeled block inside the component that configures an endpoint to send metrics to. | ||
| This block sets the `url` attribute to specify the endpoint. | ||
| The {{< param "PRODUCT_NAME" >}} configuration syntax is a distinct language with custom syntax and features, such as first-class functions. | ||
|
|
||
| * Blocks are a group of related settings and usually represent creating a component. | ||
| Blocks have a name that consists of zero or more identifiers separated by `.`, an optional user label, and a body containing attributes and nested blocks. | ||
| * Attributes appear within blocks and assign a value to a name. | ||
| * Expressions represent a value, either literally or by referencing and combining other values. | ||
| You use expressions to compute a value for an attribute. |
There was a problem hiding this comment.
I was thinking the same. These points feel like a repetition or a rephrase of previous info... and it might be better to find a way to rephrase and fit it into the content around lines 59-65... somewhere in that area. Might help to commit some of the other changes and do a make docs so this can all be read in the rendered output.
accepted @clayton-cornell edits Co-authored-by: Clayton Cornell <[email protected]>
* reorganize configuration syntax intro * Apply suggestions from code review accepted @clayton-cornell edits Co-authored-by: Clayton Cornell <[email protected]> --------- Co-authored-by: Clayton Cornell <[email protected]> (cherry picked from commit 8afa972)
* reorganize configuration syntax intro * Apply suggestions from code review accepted @clayton-cornell edits Co-authored-by: Clayton Cornell <[email protected]> --------- Co-authored-by: Clayton Cornell <[email protected]> (cherry picked from commit 8afa972)
* reorganize configuration syntax intro * Apply suggestions from code review accepted @clayton-cornell edits Co-authored-by: Clayton Cornell <[email protected]> --------- Co-authored-by: Clayton Cornell <[email protected]> (cherry picked from commit 8afa972) Co-authored-by: David Allen <[email protected]>
* reorganize configuration syntax intro * Apply suggestions from code review accepted @clayton-cornell edits Co-authored-by: Clayton Cornell <[email protected]> --------- Co-authored-by: Clayton Cornell <[email protected]> (cherry picked from commit 8afa972) Co-authored-by: David Allen <[email protected]>
This PR attempts to do a couple of things:
@rfratto this is another trial balloon along the lines we discussed when we met. More than open to feedback here, but after that discussion hopefully it'll make sense where I'm coming from. The simplest possible worked example that would show off the "full conceptual scope" of config (by this I mean: collection, transformation, delivery) is a good thing to have up top.
Nobody's going to use the referenced example, so its particulars don't matter much beyond the KISS principle. (This example happens to be lifted from a video we did on reporting logs to loki). It's there to show the concepts in action before we get into a more technical discussion down the page about syntactically "what is a block".
There was an earlier example block that I removed because it was showing off "syntax only" before the concept of a block had been introduced.