Documentation Grafana Cloud Observe and act Monitor infrastructure Kubernetes Monitoring Configure Kubernetes Monitoring Configure with Helm chart Helm chart Collector reference

Grafana Alloy collector reference

Use this reference if you want to configure Grafana Alloy instances without using the Kubernetes Monitoring configuration GUI or if you want to modify Alloy instances you have deployed.

Collectors are Grafana Alloy instances deployed by the Alloy Operator as Kubernetes workloads. This information covers collector options specific to the Kubernetes Monitoring Helm chart.

When you define a collector, Alloy Operator creates a Kubernetes workload as either a DaemonSet, StatefulSet, or Deployment, with its own set of Pods running Alloy containers. The workload is normally named <RELEASE_NAME>-<COLLECTOR_NAME>, though the chart doesn’t repeat the collector name when your release name already contains it.

The presets you assign determine the collector’s deployment shape: which of those workload types it runs as, and what host access its Pods get. A collector that reads log files from the Nodes needs a different shape from one that scrapes metrics, so you pick the presets that match the work the collector does.

General configuration

Collectors are defined as a map in the values file of the Kubernetes Monitoring Helm chart. You choose the name for each collector and apply one or more presets that describe the deployment shape:

YAML Copy

collectors:
  metrics-collector: # You choose the name
    presets: [clustered, statefulset] # Deployment shape
    alloy: {} # Alloy container settings (resources, security context, …)
    controller: {} # Workload settings (replicas, node selectors, …)
    configReloader: {} # Config-reloader sidecar settings
  logs-collector:
    presets: [filesystem-log-reader, daemonset]
  events-collector:
    presets: [singleton]

Features are assigned to a collector using the collector field. If you define only a single collector, all features use it automatically. The following example shows the complete pattern. It defines three collectors: a metrics collector clustered and deployed as a StatefulSet, a logs collector deployed as a DaemonSet that reads log files from each node, and a receiver deployed as a DaemonSet for incoming application telemetry. Each feature references its collector by name.

YAML Copy

collectors:
  metrics-collector:
    presets: [clustered, statefulset] # Deploys as a StatefulSet
  logs-collector:
    presets: [filesystem-log-reader, daemonset] # Deploys as a DaemonSet, one per node
  receiver:
    presets: [daemonset] # Deploys as a DaemonSet, one per node

clusterMetrics:
  enabled: true
  collector: metrics-collector # References the collector defined above

podLogsViaLoki:
  enabled: true
  collector: logs-collector # References the collector defined above

applicationObservability:
  enabled: true
  collector: receiver # References the collector defined above

If you want to apply the same Alloy settings to every collector (for example, resource limits or environment variables), use the collectorCommon section instead of repeating them in each collector definition:

YAML Copy

collectorCommon:
  alloy: {}

Presets

Presets define the deployment shape and capabilities of a collector. You can apply multiple presets to a single collector, and their settings combine.

Resource presets

The following presets don’t change a collector’s shape. They set CPU and memory requests and limits, so you combine them with one of the presets in the preceding table.

For the values each resource preset sets, and for the current list of all presets, refer to Collector presets in the Helm chart repository. To tune resources yourself instead, set alloy.resources on the collector and refer to Estimate Grafana Alloy resource usage.

Typical collector configurations

The following examples show how to configure collectors for common use cases.

Metrics collector

Use a metrics collector for scraping cluster metrics, host metrics, cost metrics, targets discovered through Pod annotations, and targets defined by Prometheus Operator ServiceMonitors and PodMonitors.

YAML Copy

collectors:
  metrics-collector:
    presets: [clustered, statefulset]

Logs collector

Use a logs collector for gathering Pod logs and Node logs from the filesystem.

YAML Copy

collectors:
  logs-collector:
    presets: [filesystem-log-reader, daemonset]

Events collector

Use an events collector for gathering Cluster events and other data that must run as a single instance.

YAML Copy

collectors:
  events-collector:
    presets: [singleton]

Application receiver

A receiver is a listening port. Alloy opens the port and waits for your instrumented applications to push telemetry to it, instead of scraping or tailing a source itself. Configuring one takes two blocks, because the word covers two different things:

• The collector that hosts the ports. This is an ordinary collector that you happen to name receiver. The daemonset preset puts one Pod on every Node, so applications can push to an endpoint on their own Node.
• The protocols listening on it, set under applicationObservability.receivers. These decide which ports open and which data formats they accept.

You need both because the collector and the feature are separate things: the collector is the workload, and the feature is the telemetry pipeline assigned to it. Neither one opens a port on its own.

The first block defines the collector:

YAML Copy

collectors:
  receiver:
    presets: [daemonset]

The second block is a separate top-level key that configures the Application Observability feature and assigns it to that collector. Enabling a receiver protocol here opens the matching port on the collector’s Pods and starts a listener for that protocol, so instrumented applications can send traces, metrics, and logs. Both blocks go in the same values file.

YAML Copy

applicationObservability:
  enabled: true
  collector: receiver # References the receiver collector defined above
  receivers:
    otlp:
      grpc:
        enabled: true
        port: 4317 # OTLP gRPC endpoint
      http:
        enabled: true
        port: 4318 # OTLP HTTP endpoint

Profiles collector

Use a profiles collector for gathering profiles using eBPF, Java, or pprof profilers. The privileged preset runs the container as root with host PID access, which eBPF and Java profilers require to inspect processes on the node.

YAML Copy

collectors:
  profiles-collector:
    presets: [privileged, daemonset]

Client endpoint configuration

You can configure endpoints inside or outside the Cluster.

Inside the Cluster

Applications inside the Kubernetes Cluster use the kubedns name to reference a particular receiver endpoint. For example:

YAML Copy

endpoint: http://grafana-k8s-monitoring-alloy[.mynamespace.cluster.local]:4318

Outside the Cluster

To expose the receiver to applications outside the Cluster (for example, Frontend Observability), you can use different approaches depending on your setup. Load balancers are created by whatever controllers are installed on your Cluster. For the full list of options, refer to the Alloy chart values.

For example, to create a Network Load Balancer on Amazon Elastic Kubernetes Service (Amazon EKS) when using the AWS Load Balancer Controller, use this example:

YAML Copy

collectors:
  receiver:
    presets: [daemonset]
    alloy:
      service:
        type: LoadBalancer

To create an Application Load Balancer, use this example:

YAML Copy

collectors:
  receiver:
    presets: [daemonset]
    alloy:
      ingress:
        enabled: true
        path: /
        faroPort: 12347

You can also create additional services and ingress objects as needed if the Alloy Helm chart options don’t fit your needs. Consult your Kubernetes vendor documentation for details.

Istio/Service Mesh

Depending on your mesh configuration, you might need to do either of these:

• Explicitly include the Grafana monitoring namespace as a member.
• Declare the receiver as a backend of your application for traffic within the Cluster.

For traffic from outside the Cluster, it’s likely you need to set up an ingress gateway into your mesh. In any case, consult your mesh vendor for details.

Troubleshooting

Here are some troubleshooting tips related to configuring collectors.

Startup issues

Make sure your collector Pods are up and running. Use this command to show you a list of Pods and associated states, replacing <namespace> with the Kubernetes namespace where you installed the Helm chart:

kubectl get pods -n <namespace>

You may also have meta-monitoring turned on, which means using Kubernetes Monitoring to watch the monitoring components themselves: you point the chart’s service integrations at your own collectors, and at components such as Grafana, Loki, and Mimir, to collect their health and performance telemetry. It’s on only if your values file defines those integrations. For an example, refer to Meta-monitoring in the Helm chart repository.

Meta-monitoring exposes the Alloy Pod logs in Loki, but that isn’t helpful when the logs collector itself is faulty.

To troubleshoot collector startup problems, inspect the Pod logs using the method you would for any Kubernetes workload. Use the Pod name from the NAME column of kubectl get pods output (replace <pod-name> below). For example, to watch a logs collector:

kubectl logs -f --tail 100 <pod-name> -n <namespace>

Alloy debugger

You can apply standard Alloy troubleshooting strategies to each collector Pod specifically for Kubernetes.

1. To access the Alloy UI on a collector Pod, forward the UI port to your local machine:

   Bash Copy

   kubectl port-forward <pod-name> 12345:12345

2. Open your browser to http://localhost:12345

Scaling

Follow these instructions for appropriate scaling.

DaemonSets and Singleton instances

For collectors deployed as DaemonSets (using the daemonset preset), one Pod is deployed per Node. You cannot deploy more replicas with this type of controller.

For collectors with the singleton preset, only one Pod is deployed in the Cluster, and it must remain a single instance to avoid duplicate data.

To scale the individual Pods, increase the resource requests and limits. Refer to Estimate Grafana Alloy resource usage to learn how to tune those parameters.

For example, to increase the CPU and memory available to each Pod in a DaemonSet logs collector, set requests and limits under alloy.resources:

YAML Copy

collectors:
  logs-collector:
    presets: [filesystem-log-reader, daemonset]
    alloy:
      resources:
        requests:
          cpu: 100m
          memory: 128Mi
        limits:
          cpu: 500m
          memory: 512Mi

StatefulSets

For StatefulSet collectors (using the statefulset preset), set the number of replicas. When combined with the clustered preset, Alloy automatically distributes scrape targets across all replicas.

YAML Copy

collectors:
  metrics-collector:
    presets: [clustered, statefulset]
    controller:
      replicas: 3

Autoscaling

Alloy does not enable autoscaling by default, but allows for the configuration of either a Horizontal Pod Autoscaler (HPA) or a Vertical Pod Autoscaler (VPA).

To enable autoscaling for a collector, add the appropriate configuration to the controller section of the collector. You can use an HPA for horizontal scaling or a VPA for vertical scaling, and different collectors can use different strategies. For an HPA, minReplicas and maxReplicas set the floor and ceiling for the replica count, and targetCPUUtilizationPercentage sets the threshold that triggers a scale-up. For a VPA, the autoscaler adjusts CPU and memory requests automatically based on observed usage, and resourcePolicy constrains the ranges the VPA can set.

YAML Copy

collectors:
  metrics-collector:
    presets: [clustered, statefulset]
    controller:
      autoscaling:
        horizontal:
          enabled: true
          minReplicas: 2
          maxReplicas: 10
          targetCPUUtilizationPercentage: 80

  logs-collector:
    presets: [filesystem-log-reader, daemonset]
    controller:
      autoscaling:
        vertical:
          enabled: true
          resourcePolicy:
            containerPolicies:
              - containerName: alloy
                minAllowed:
                  cpu: 50m
                  memory: 64Mi
                maxAllowed:
                  cpu: '2'
                  memory: 2Gi

Values reference

Collectors are user-defined, so all keys are relative to collectors.<name>. The same schema applies to every collector. For additional keys not listed here (such as alloy and controller sub-keys), refer to the generated collector values documentation.

General

Logging

Remote configuration

Remote configuration: authentication

Remote configuration: TLS

Additional configuration sources

Each collector has the ability to specify additional configuration sources within its definition: