Integrations next (Experimental) on Grafana Labs

app_agent_receiver_config next

Wed, 15 Apr 2026 03:22:24 +0000

app_agent_receiver_config next

The app_agent_receiver_config block configures the app_agent_receiver integration. This integration exposes a http endpoint that can receive telemetry from the Grafana Faro Web SDK and forward it to logs, traces or metrics backends.

These are the options you have for configuring the app_agent_receiver integration.

  autoscrape:
    # Enables autoscrape of integrations.
    [enable: <boolean> | default = true]

    # Specifies the metrics instance name to send metrics to. Instance
    # names are located at metrics.configs[].name from the top-level config.
    # The instance must exist.
    #
    # As it is common to use the name "default" for your primary instance,
    # we assume the same here.
    [metrics_instance: <string> | default = "default"]

    # Autoscrape interval and timeout. Defaults are inherited from the global
    # section of the top-level metrics config.
    [scrape_interval: <duration> | default = <metrics.global.scrape_interval>]
    [scrape_timeout: <duration> | default = <metrics.global.scrape_timeout>]

  # Integration instance name
  [instance: <string>]

  # Traces instance to send traces to. This assumes that you have a traces config with such instance defined
  [traces_instance: <string> | default = ""]

  # Logs instance to send logs and exceptions to. This assumes that you have a logs
  # config with the instance defined
  [logs_instance: <string> | default = ""]

  # Server config refers to the HTTP endpoint that the integration will be exposing
  # to receive data from.
  server:
    [host: <string> | default = "127.0.0.1"]
    [port: <number> | default = 12347]

    # Domains in which the agent is sending data from. For example "https://myapp.com"
    cors_allowed_origins:
      [- <string>]

    # Configure rate limiting. The HTTP server of the App observability implements
    # a token bucket rate limitng algorithm in which we can configure the maximum RPS
    # as well as the burstiness (peaks of RPS)
    rate_limiting:
      [enabled: <boolean> | default = false]
      [rps: <number> | default = 100]
      [burstiness: <number> | default = 50]

    # If configured, incoming requests will be required to specify this key in "x-api-key" header
    [api_key: <string>]

    # Max allowed payload size in bytes for the JSON payload. Interanlly the
    # Content-Length header is used to make this check
    [max_allowed_payload_size: <number> | default = 0]

  # Labels to set for the log entry.
  # If value is specified, it will be used.
  # If value is empty and key exists in data, it's value will be used from data
  logs_labels:
    [- <key>: <string>]

  # Timeout duration when sending an entry to Loki, milliseconds
  [logs_send_timeout: <duration> | default = 2s]

  # Sourcemap configuration for enabling stack trace transformation to original source locations
  [sourcemaps: <sourcemap_config>]

sourcemap_config

# Whether agent should attempt to download compiled sources and source maps
[download: <boolean> | default = false]

# List of HTTP origins to download sourcemaps for
[download_origins: []<string> | default = ["*"]]

# Timeout for downloading compiled sources and sourcemaps
[download_timeout: <duration> | default = "1s"]

# Sourcemap locations on filesystem. Takes precedence over downloading if both methods are enabled
filesystem:
  [- <sourcemap_file_location>]

sourcemap_file_location

# Grafana Faro Web SDK will send filename in stacktrace, when any exception is being captured.
# That filename will be the source url. e.g. https://my-app.dev/static/foo.js
#
# Source URL prefix. If a minified source URL matches this prefix,
# a filepath is constructed by removing the prefix, prepending path below and appending ".map".
#
# Example:
#
# minified_path_prefix = "https://my-app.dev/static/"
# path = "/var/app/static/"
#
# Then given source url "https://my-app.dev/static/foo.js"
# it will look for sourcemap at "/var/app/static/foo.js.map"

minified_path_prefix: <string>

# Directory on file system that contains source maps.
# See above for more detailed explanation.
# It is parsed as a Go template. You can use "{{.Release }}" which will be replaced with
# app.release meta property.
path: <string>

blackbox_config next

Wed, 15 Apr 2026 03:22:24 +0000

blackbox_config next

The blackbox_config block configures the blackbox_exporter integration, which is an embedded version of blackbox_exporter. This allows for the collection of blackbox metrics (probes) and exposing them as Prometheus metrics.

Quick configuration example

To get started, define Blackbox targets in Grafana Agent’s integration block:

metrics:
  wal_directory: /tmp/wal
  configs:
    - name: default
integrations:
  blackbox:
    blackbox_targets:
      - name: example
        address: http://example.com
        module: http_2xx
    blackbox_config:
      modules:
        http_2xx:
          prober: http
          timeout: 5s
          http:
            method: POST
            headers:
              Content-Type: application/json
            body: '{}'
            preferred_ip_protocol: "ip4"

Full reference of options:

  # Provide an explicit value to uniquely identify this instance of the
  # integration. If not provided, a reasonable default will be inferred based
  # on the integration.
  #
  # The value here must be unique across all instances of the same integration.
  [instance: <string>]

  # Override autoscrape defaults for this integration.
  autoscrape:
    # Enables autoscrape of integrations.
    [enable: <boolean> | default = <integrations.metrics.autoscrape.enable>]

    # Specifies the metrics instance name to send metrics to.
    [metrics_instance: <string> | default = <integrations.metrics.autoscrape.metrics_instance>]

    # Autoscrape interval and timeout.
    [scrape_interval: <duration> | default = <integrations.metrics.autoscrape.scrape_interval>]
    [scrape_timeout: <duration> | default = <integrations.metrics.autoscrape.scrape_timeout>]

  # An optional extra set of labels to add to metrics from the integration target. These
  # labels are only exposed via the integration service discovery HTTP API and
  # added when autoscrape is used. They will not be found directly on the metrics
  # page for an integration.
  extra_labels:
    [ <labelname>: <labelvalue> ... ]

  #
  # Exporter-specific configuration options
  #

  # blackbox configuration file with custom modules.
  # This field has precedence to the config defined in the blackbox_config block.
  # See https://github.com/prometheus/blackbox_exporter/blob/master/example.yml for more details how to generate custom blackbox.yml file.
  [config_file: <string> | default = ""]

  # Embedded blackbox configuration. You can specify your modules here instead of an external config file.
  # See https://github.com/prometheus/blackbox_exporter/blob/master/CONFIGURATION.md for more details how to specify your blackbox modules.
  blackbox_config:
    [- <modules> ... ]

  # List of targets to probe
  blackbox_targets:
    [- <blackbox_target> ... ]

  # Option to configure blackbox_exporter.
  # Represents the offset to subtract from timeout in seconds when probing targets.
  [probe_timeout_offset: <float> | default = 0.5]

blackbox_target config

  # Name of a blackbox_target
  [name: <string>]

  # The address of the target to probe
  [address: <string>]

  # Blackbox module to use to probe
  [module: <string> | default = ""]

eventhandler_config next

Wed, 15 Apr 2026 03:22:24 +0000

eventhandler_config next

eventhandler_config configures the Kubernetes eventhandler integration. This integration watches Event resources in a Kubernetes cluster and forwards them as log entries to a Loki sink. This integration depends on the experimental integrations-next feature being enabled.

On restart, the integration will look for a cache file (configured using cache_path) that stores the last shipped event. This file is optional, and if present, will be used to avoid double-shipping events if Agent or the integration restarts. Kubernetes expires events after 60 minutes, so events older than 60 minutes ago will never be shipped.

To use the cache feature and maintain state in a Kubernetes environment, a StatefulSet must be used. Sample manifests are provided at the bottom of this doc. Please adjust these according to your deployment preferences. You can also use a Deployment, however the presence of the cache file will not be guaranteed and the integration may ship duplicate entries in the event of a restart. Loki does not yet support entry deduplication for the A->B->A case, so further deduplication can only take place at the Grafana / front-end layer (Grafana Explore does provide some deduplication features for Loki datasources).

This integration uses Grafana Agent’s embedded Loki-compatible logs subsystem to ship entries, and a logs client and sink must be configured to use the integration. Please see the sample Agent config below for an example configuration. Pipelines and relabel configuration are not yet supported, but these features will be added soon. You should use the job=eventhandler cluster=... labels to query your events (you can then use LogQL on top of the result set).

If not running the integration in-cluster, the integration will use kubeconfig_path to search for a valid Kubeconfig file, defaulting to a kubeconfig in the user’s home directory. If running in-cluster, the appropriate ServiceAccount and Roles must be defined. Sample manifests are provided below.

Configuration reference:

  # Provide an explicit value to uniquely identify this instance of the
  # integration. If not provided, a reasonable default will be inferred based
  # on the integration.
  #
  # The value here must be unique across all instances of the same integration.
  [instance: <string>]

  ## Eventhandler hands watched events off to promtail using a promtail
  ## client channel. This parameter configures how long to wait (in seconds) on the channel
  ## before abandoning and moving on.
  [send_timeout: <int> | default = 60]

  ## Configures the path to a kubeconfig file. If not set, will fall back to using
  ## an in-cluster config. If this fails, will fall back to checking the user's home
  ## directory for a kubeconfig.
  [kubeconfig_path: <string>]

  ## Path to a cache file that will store the last timestamp for a shipped event and events
  ## shipped for that timestamp. Used to prevent double-shipping on integration restart.
  [cache_path: <string> | default = "./.eventcache/eventhandler.cache"]

  ## Name of logs subsystem instance to hand log entries off to.
  [logs_instance: <string> | default = "default"]

  ## K8s informer resync interval (seconds). You should use defaults here unless you are
  ## familiar with K8s informers.
  [informer_resync: <int> | default = 120]

  ## The integration will flush the last event shipped out to disk every flush_interval seconds.
  [flush_interval: <int> | default = 10]

  ## If you would like to limit events to a given namespace, use this parameter.
  [namespace: <string>]

  ## Configure extra labels to add to log lines
  extra_labels:
    { <string>: <string> }

  ## Format of the log line. The possible values are "logfmt" and "json".
  ## The values are also LogQL parsers, which can be used for processing the logs
  [log_format: <string> | default = "logfmt"]

Sample agent config:

server:
  log_level: info

integrations:
  eventhandler:
    cache_path: "/etc/eventhandler/eventhandler.cache"

logs:
  configs:
  - name: default
    clients:
    - url: https://logs-prod-us-central1.grafana.net/api/prom/push
      basic_auth:
        username: YOUR_LOKI_USER
        password: YOUR_LOKI_API_KEY
      external_labels:
        cluster: "cloud"
    positions:
      filename: /tmp/positions0.yaml

Be sure to replace the Loki credentials with the appropriate values.

Sample StatefulSet manifests. Please adjust these according to your needs:

apiVersion: v1
kind: ServiceAccount
metadata:
  name: grafana-agent-eventhandler
  namespace: default
---
apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRole
metadata:
  name: grafana-agent-eventhandler
rules:
- apiGroups:
  - ""
  resources:
  - events
  verbs:
  - get
  - list
  - watch
---
apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRoleBinding
metadata:
  name: grafana-agent-eventhandler
roleRef:
  apiGroup: rbac.authorization.k8s.io
  kind: ClusterRole
  name: grafana-agent-eventhandler
subjects:
- kind: ServiceAccount
  name: grafana-agent-eventhandler
  namespace: default
---
apiVersion: v1
kind: Service
metadata:
  name: grafana-agent-eventhandler-svc
spec:
  ports:
  - port: 12345
    name: http-metrics
  clusterIP: None
  selector:
    name: grafana-agent-eventhandler
---
kind: ConfigMap
metadata:
  name: grafana-agent-eventhandler
  namespace: default
apiVersion: v1
data:
  agent.yaml: |
    server:
      log_level: info

    integrations:
      eventhandler:
        cache_path: "/etc/eventhandler/eventhandler.cache"

    logs:
      configs:
      - name: default
        clients:
        - url: https://logs-prod-us-central1.grafana.net/api/prom/push
          basic_auth:
            username: YOUR_LOKI_USER
            password: YOUR_LOKI_API_KEY
          external_labels:
            cluster: "cloud"
        positions:
          filename: /tmp/positions0.yaml
---
apiVersion: apps/v1
kind: StatefulSet
metadata:
  name: grafana-agent-eventhandler
  namespace: default
spec:
  serviceName: "grafana-agent-eventhandler-svc"
  selector:
    matchLabels:
      name: grafana-agent-eventhandler
  replicas: 1
  template:
    metadata:
      labels:
        name: grafana-agent-eventhandler
    spec:
      terminationGracePeriodSeconds: 10
      containers:
      - name: agent
        image: grafana/agent:main
        imagePullPolicy: IfNotPresent
        args:
        - -config.file=/etc/agent/agent.yaml
        - -enable-features=integrations-next
        - -server.http.address=0.0.0.0:12345
        command:
        - /bin/grafana-agent
        env:
        - name: HOSTNAME
          valueFrom:
            fieldRef:
              fieldPath: spec.nodeName
        ports:
        - containerPort: 12345
          name: http-metrics
        volumeMounts:
        - name: grafana-agent
          mountPath: /etc/agent
        - name: eventhandler-cache
          mountPath: /etc/eventhandler
      serviceAccount: grafana-agent-eventhandler
      volumes:
        - configMap:
            name: grafana-agent-eventhandler
          name: grafana-agent
  volumeClaimTemplates:
  - metadata:
      name: eventhandler-cache
    spec:
      accessModes: [ "ReadWriteOnce" ]
      resources:
        requests:
          storage: 1Gi

snmp config next

Wed, 15 Apr 2026 03:22:24 +0000

snmp config next

The snmp block configures the snmp integration, which is an embedded version of snmp_exporter. This allows collection of SNMP metrics from the network devices with ease.

Quick configuration example

To get started, define SNMP targets in Grafana agent’s integration block:

metrics:
  wal_directory: /tmp/wal
integrations:
  snmp:
    snmp_targets:
      - name: network_switch_1
        address: 192.168.1.2
        module: if_mib
        walk_params: public
        auth: public
      - name: network_router_2
        address: 192.168.1.3
        module: mikrotik
        walk_params: private
        auth: private
    walk_params:
      private:
        retries: 2
      public:
        retries: 1

Prometheus service discovery use case

If you need to scrape SNMP devices in more dynamic environment, and cannot define devices in snmp_targets because targets would change over time, you can use service discovery approach. For instance, with DNS discovery:


metrics:
  wal_directory: /tmp/wal
  configs:
    - name: snmp_targets
      scrape_configs:
        - job_name: 'snmp'
          dns_sd_configs:
            - names:
              - switches.srv.example.org
              - routers.srv.example.org
          params:
            module: [if_mib]
            walk_params: [private]
            auth: [private]
          metrics_path: /integrations/snmp/metrics
          relabel_configs:
            - source_labels: [__address__]
              target_label: __param_target
            - source_labels: [__param_target]
              target_label: instance
            - replacement: 127.0.0.1:12345 # address must match grafana agent -server.http.address flag
              target_label: __address__
integrations:
  snmp:
    autoscrape:
      enable: false # set autoscrape to off
    walk_params:
      private:
        retries: 2

Full reference of options:

  # Provide an explicit value to uniquely identify this instance of the
  # integration. If not provided, a reasonable default will be inferred based
  # on the integration.
  #
  # The value here must be unique across all instances of the same integration.
  [instance: <string>]

  # Override autoscrape defaults for this integration.
  autoscrape:
    # Enables autoscrape of integrations.
    [enable: <boolean> | default = <integrations.metrics.autoscrape.enable>]

    # Specifies the metrics instance name to send metrics to.
    [metrics_instance: <string> | default = <integrations.metrics.autoscrape.metrics_instance>]

    # Autoscrape interval and timeout.
    [scrape_interval: <duration> | default = <integrations.metrics.autoscrape.scrape_interval>]
    [scrape_timeout: <duration> | default = <integrations.metrics.autoscrape.scrape_timeout>]

  # An optional extra set of labels to add to metrics from the integration target. These
  # labels are only exposed via the integration service discovery HTTP API and
  # added when autoscrape is used. They will not be found directly on the metrics
  # page for an integration.
  extra_labels:
    [ <labelname>: <labelvalue> ... ]

  #
  # Exporter-specific configuration options
  #

  # SNMP configuration file with custom modules.
  # See https://github.com/prometheus/snmp_exporter#generating-configuration for more details how to generate custom snmp.yml file.
  # If not defined, embedded snmp_exporter default set of modules is used.
  [config_file: <string> | default = ""]

  # Embedded SNMP configuration. You can specify your modules here instead of an external config file.
  # See https://github.com/prometheus/snmp_exporter/tree/main#generating-configuration for more details how to specify your SNMP modules.
  # If this and config_file are not defined, embedded snmp_exporter default set of modules is used.
  snmp_config:
    [- <modules> ... ]
    [- <auths> ... ]

  # List of SNMP targets to poll
  snmp_targets:
    [- <snmp_target> ... ]

  # Map of SNMP connection profiles that can be used to override default SNMP settings.
  walk_params:
    [ <string>: <walk_param> ... ]

snmp_target config

  # Name of a snmp_target
  [name: <string>]

  # The address of SNMP device
  [address: <string>]

  # SNMP module to use for polling
  [module: <string> | default = ""]

  # SNMP authentication profile to use
  [auth: <string> | default = ""]

  # walk_param config to use for this snmp_target
  [walk_params: <string> | default = ""]

  # snmp_context overrides the `context_name` parameter in the SNMP configuration file.
  [snmp_context: <string> | default = ""]

walk_param config

  # How many objects to request with GET/GETBULK, defaults to 25.
  # May need to be reduced for buggy devices.
  [max_repetitions: <int> | default = 25]

  # How many times to retry a failed request, defaults to 3.
  [retries: <int> | default = 3]

  # Timeout for each SNMP request, defaults to 5s.
  [timeout: <duration> | default = 5s]

About SNMP modules

SNMP module is the set of SNMP counters to be scraped together from the specific network device.

SNMP modules available can be found in the embedded snmp.yml file here. If not specified, if_mib module is used.

If you need to use custom SNMP modules, you can generate your own snmp.yml file and specify it using config_file parameter.

vsphere config (beta) next

Wed, 15 Apr 2026 03:22:24 +0000

vsphere config (beta) next

The vsphere_config block configures the vmware_exporter integration, an embedded version of vmware_exporter, configured to collect vSphere metrics. This integration is considered beta.

Configuration reference:

  autoscrape:
    # Enables autoscrape of integrations.
    [enable: <boolean> | default = true]

    # Specifies the metrics instance name to send metrics to. Instance
    # names are located at metrics.configs[].name from the top-level config.
    # The instance must exist.
    #
    # As it is common to use the name "default" for your primary instance,
    # we assume the same here.
    [metrics_instance: <string> | default = "default"]

    # Autoscrape interval and timeout. Defaults are inherited from the global
    # section of the top-level metrics config.
    [scrape_interval: <duration> | default = <metrics.global.scrape_interval>]
    [scrape_timeout: <duration> | default = <metrics.global.scrape_timeout>]

  # Integration instance name. This will default to the host:port of the configured
  # vsphere_url.
  [instance: <string> | default = <vsphere_url>]

  # Number of managed objects to include in each request to vsphere when
  # fetching performance counters.
  [request_chunk_size: <int> | default = 256]

  # Number of concurrent requests to vsphere when fetching performance counters.
  [collect_concurrency: <int> | default = 8]

  # Interval on which to run vsphere managed object discovery. Setting this to a
  # non-zero value will result in object discovery running in the background. Each
  # scrape will use object data gathered during the last discovery.
  # When this value is 0, object discovery occurs per scrape.
  [discovery_interval: <duration> | default = 0]
  [enable_exporter_metrics: <boolean> | default = true]

  # The url of the vCenter SDK endpoint
  vsphere_url: <string>

  # vCenter username
  vsphere_user: <string>

  # vCenter password
  vsphere_password: <string>

Quick configuration example

integrations:
  vsphere_configs:
    - vsphere_url: https://127.0.0.1:8989/sdk
      vsphere_user: user
      vsphere_password: pass
      request_chunk_size: 256
      collect_concurrency: 8
      instance: vsphere
      autoscrape:
        enable: true
        metrics_instance: default

metrics:
  wal_directory: /tmp/grafana-agent-wal
server:
  log_level: debug