Grafana Alloy (alloy)
Collects the journal of the navin-* units and the files under /var/log/navin and ships them as OTLP logs to the OpenTelemetry Collector (then OpenSearch); optional metrics remote write.
Generated from catalog/services/alloy.yaml: do not edit by hand.
Summary
| Version | 1.10.0 |
| Use | install and configure |
| Layer | infrastructure (shown apart) |
| Category | Observability |
| Installation methods | binary |
| External connection | no |
| Sandbox only | no |
Licence
| SPDX identifier | Apache-2.0 |
| Licence policy | core licence (MIT or Apache-2.0) |
| Licence exception | - |
| Platform component | alloy |
Packages and artifacts
A package the project of the service publishes (its image, its binary archive, its Python or OS package) carries the licence of the service; a third-party package carries the licence written on its row, read from the official upstream metadata.
| Kind | Package | Version | Licence | Details |
|---|---|---|---|---|
| binary archive | alloy-linux-amd64.zip | 1.10.0 | Apache-2.0 | https://github.com/grafana/alloy/releases/download/v1.10.0/alloy-linux-amd64.zip, x86_64, checksum sha256 |
Supported systems and architectures
| Method | Operating systems | Architectures |
|---|---|---|
binary | RHEL family (dnf), Debian family (apt), Arch Linux (pacman) | x86_64 (architecture of the artifacts of the descriptor) |
Certified host systems: RHEL 8/9/10, Rocky Linux 8/9/10, AlmaLinux 8/9/10, Oracle Linux 8/9, CentOS Stream 9/10, Ubuntu 22.04/24.04, Debian 12, Arch Linux (rolling). The host preflight accepts these systems (other releases of a known family give a warning, end of life releases are refused) and the x86_64 and aarch64 architectures.
Prerequisites
Host
The descriptor declares no host preflight check.
Network and ports
| Component | Port name | Port | Opened in the host firewall |
|---|---|---|---|
alloy | http | 12345/tcp | no |
Services and connections needed
otel:otel-collector.prometheus:prometheus(optional).tetragon:tetragon(optional).
Details and resolution: see Dependencies.
Installation methods and modes
| Method | Default | What the method uses |
|---|---|---|
binary | yes | the binary archives of the descriptor, unpacked under the service directory |
Components
| Component | Kind | Installation methods | Ports |
|---|---|---|---|
Alloy agent (alloy) | worker | binary | 12345/tcp |
Every host (every-host) (default)
One agent per managed host.
What the mode deploys:
| Component | Placement |
|---|---|
alloy | min 0, recommended 3 |
Install this service
The install wizard of the Navin Manager plans, validates and runs the installation; you need the services:install permission on the cluster.
-
Open the wizard. In Clusters, choose the row action Install services of the target cluster. The wizard opens on its first step, Service.
-
Choose the service. On the Service step, select Grafana Alloy. The card shows the licence
Apache-2.0and the dependencies the installation needs. -
Choose the hosts and the mode. On the Hosts step, tick the hosts, then choose the Mode:
every-host(default). Each mode deploys the components listed in Installation methods and modes. -
Bind the dependencies. On the Bindings step, choose for each dependency (
otel,prometheus,tetragon) Install with the platform or Use an existing connection; an optional dependency can stay on No binding. -
Configure. On the Configure step, review the parameters (see Configuration parameters). Passwords left empty with a generated default are generated and sealed by the Manager.
-
Review and install. On the Install step the Manager validates the plan and shows the installation order; when it says "The plan is valid. Ready to install.", choose Install. A highly available mode is installed only when its HA checks pass.
-
Verify. The operation ends when the health checks of every instance pass (see Health checks); the service then shows as running in Services.
High availability
| Cluster | per host (per-host) |
| High availability | per host (per-host) |
| Failover | none (none) |
| Replication | none (none) |
| Quorum | none (none) |
| Discovery | static (static) |
| Entry point | per host (per-host) |
| Official documentation | https://github.com/grafana/alloy/blob/main/docs/sources/configure/clustering/configure-alloy.md |
Prerequisites
| Prerequisite | Must be highly available | Modes | Description |
|---|---|---|---|
otel | no | modes of level ha or cluster | OpenTelemetry Collector receiving the data of the agents; replicate it (gateway mode) so that an agent always has a destination. |
Topology per mode
| Modes | Highest catalog level | Distribution | Quorum component | Fault domains | Description |
|---|---|---|---|---|---|
every-host | ha (ha) | per host (per-host) | - | - | One agent on every host: each host covers itself, the loss of a host only loses its own coverage. |
Notes
- Alloy clustering is enabled component by component (only the compatible components share their work); the catalog mode runs one independent agent per host and does not enable it.
Configuration parameters
General
| Parameter | Type | Default | Allowed values | Required | Secret | Restart | Description |
|---|---|---|---|---|---|---|---|
HTTP port (port) | port | 12345 | - | no | no | no | Port of the Alloy interface and metrics, bound to the host address. |
TLS (tls_enabled) | bool | false | - | no | no | no | Serve the interface and the metrics over HTTPS (http block, tls) with a certificate issued by the manager CA; Prometheus then scrapes it in https and verifies it with that CA. |
Log directory (log_root) | path | /var/log/navin | - | no | no | no | Directory whose *.log files are shipped. |
Send host metrics (remote_write_metrics) | bool | false | - | no | no | no | Remote write the Unix exporter metrics to the Prometheus binding. |
Dependencies
For each active dependency the Manager takes the first of: the binding chosen in the wizard; a service of the same installation that provides it; a service already installed in the cluster; the only connection of the expected type. Otherwise an optional dependency stays unbound, and a required one is added to the installation in its default mode (the column below names the catalog service added).
| Binding | Provided by | Connection type | Endpoint | Optional | When nothing is bound | Description |
|---|---|---|---|---|---|---|
otel | otel-collector | - | otlp_http | no | otel-collector is added to the installation | OpenTelemetry Collector receiving the logs (OTLP over HTTP). |
prometheus | prometheus | - | http | yes | stays unbound (optional) | Prometheus receiving the host metrics by remote write. |
tetragon | tetragon | - | metrics | yes | stays unbound (optional) | Tetragon whose metrics stay on the loopback of its hosts (metrics_local): Alloy scrapes them on its own host and sends them to Prometheus by remote write. |
Endpoints
| Endpoint | Scheme | Component | Port | Path | TLS parameter | Binding parameters | Binding secrets | Provisioning command |
|---|---|---|---|---|---|---|---|---|
http | http | alloy | 12345 (port) | - | tls_enabled | - | - | - |
Health checks
Liveness (per instance)
| Component | Check | Details |
|---|---|---|
alloy | HTTP {{ 'https' if config.tls_enabled else 'http' }}://{{ host.fqdn if config.tls_enabled else (host.ip or '127.0.0.1') }}:{{ config.port }}/-/ready | Expected 200; 30 retries; interval 1 s; timeout 3 s |
Uninstall
Paths removed when the data is purged: {{ paths.data }}.
Quick links
- Alloy interface:
{{ 'https' if config.tls_enabled else 'http' }}://{{ host.fqdn }}:{{ config.port }}/