Skip to content

Commit

Permalink
syntax: add README.md
Browse files Browse the repository at this point in the history
Add a basic README.md to explain what the syntax submodule is.
  • Loading branch information
rfratto committed Mar 27, 2024
1 parent 0c85fd3 commit aeaaf99
Showing 1 changed file with 60 additions and 0 deletions.
60 changes: 60 additions & 0 deletions syntax/README.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,60 @@
# Alloy configuration syntax

<p>
<a href="https://pkg.go.dev/github.com/grafana/alloy/syntax"><img src="https://pkg.go.dev/badge/github.com/grafana/alloy.svg" alt="API"></a>
<a href="https://grafana.com/docs/alloy/latest/concepts/config-syntax"><img src="https://img.shields.io/badge/Documentation-link-blue?logo=gitbook" alt="User documentation"></a>
</p>

The Alloy configuration syntax is a domain-specific language used by Grafana
Alloy to define pipelines.

The syntax was designed with the following goals:

* _Fast_: The syntax must be fast so the component controller can quickly evaluate changes.
* _Simple_: The syntax must be easy to read and write to minimize the learning curve.
* _Debuggable_: The syntax must give detailed information when there's a mistake in the configuration file.

The syntax package is importable as a Go module so other projects can use
it.

> **NOTE**: The `syntax` submodule is versioned separately from the main
> module, and does not have a stable API.
## Example

```alloy
// Discover Kubernetes pods to collect metrics from.
discovery.kubernetes "pods" {
role = "pod"
}
// Collect metrics from Kubernetes pods.
prometheus.scrape "default" {
targets = discovery.kubernetes.pods.targets
forward_to = [prometheus.remote_write.default.receiver]
}
// Get an API key from disk.
local.file "apikey" {
filename = "/var/data/my-api-key.txt"
is_secret = true
}
// Send metrics to a Prometheus remote_write endpoint.
prometheus.remote_write "default" {
endpoint {
url = "http://localhost:9009/api/prom/push"
basic_auth {
username = "MY_USERNAME"
password = local.file.apikey.content
}
}
}
```

## Limitations

The `syntax` submodule only contains lower level concepts (attributes, blocks,
expressions). It does not contain any higher level concepts like components or
services.

0 comments on commit aeaaf99

Please sign in to comment.