---
title: "module.file | Grafana Agent documentation"
description: "Learn about module.file"
---

> For a curated documentation index, see [llms.txt](/llms.txt). For the complete documentation index, see [llms-full.txt](/llms-full.txt).

# module.file (deprecated)

> Caution
> 
> Starting with release v0.40, `module.string` is deprecated and is replaced by `import.string`. `module.string` will be removed in a future release.

> **BETA**: This is a [beta](/docs/agent/v0.43/stability/#beta) component. Beta components are subject to breaking changes, and may be replaced with equivalent functionality that cover the same use case.

`module.file` is a *module loader* component. A module loader is a Grafana Agent Flow component which retrieves a [module](../../../concepts/modules/) and runs the components defined inside of it.

`module.file` simplifies the configurations for modules loaded from a file by embedding a [local.file](../local.file/) component. This allows a single module loader to do the equivalence of using the more generic [module.string](../module.string/) paired with a [local.file](../local.file/) component.

## Usage

Alloy ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy

```alloy
module.file "LABEL" {
  filename = FILENAME

  arguments {
    MODULE_ARGUMENT_1 = VALUE_1
    MODULE_ARGUMENT_2 = VALUE_2
    ...
  }
}
```

## Arguments

The following arguments are supported:

Expand table

| Name             | Type       | Description                                                                                                      | Default      | Required |
|------------------|------------|------------------------------------------------------------------------------------------------------------------|--------------|----------|
| `filename`       | `string`   | Path of the file on disk to watch                                                                                |              | yes      |
| `detector`       | `string`   | Which file change detector to use (fsnotify, poll)                                                               | `"fsnotify"` | no       |
| `poll_frequency` | `duration` | How often to poll for file changes                                                                               | `"1m"`       | no       |
| `is_secret`      | `bool`     | Marks the file as containing a [secret](../../../concepts/config-language/expressions/types_and_values/#secrets) | `false`      | no       |

### File change detectors

File change detectors detect when the file needs to be re-read from disk. `local.file` supports two detectors: `fsnotify` and `poll`.

#### fsnotify

The `fsnotify` detector subscribes to filesystem events, which indicate when the watched file is updated. This detector requires a filesystem that supports events at the operating system level. Network-based filesystems like NFS or FUSE won’t work.

The component re-reads the watched file when a filesystem event is received. This re-read happens for any filesystem event related to the file, including a permissions change.

`fsnotify` also polls for changes to the file with the configured `poll_frequency` as a fallback.

`fsnotify` stops receiving filesystem events if the watched file has been deleted, renamed, or moved. The subscription is re-established on the next poll once the watched file exists again.

#### poll

The `poll` file change detector causes the watched file to be re-read every `poll_frequency`, regardless of whether the file changed.

## Blocks

The following blocks are supported inside the definition of `module.file`:

Expand table

| Hierarchy | Block                         | Description                      | Required |
|-----------|-------------------------------|----------------------------------|----------|
| arguments | [arguments](#arguments-block) | Arguments to pass to the module. | no       |

### arguments block

The `arguments` block specifies the list of values to pass to the loaded module.

The attributes provided in the `arguments` block are validated based on the [argument blocks](../../config-blocks/argument/) defined in the module source:

- If a module source marks one of its arguments as required, it must be provided as an attribute in the `arguments` block of the module loader.
- Attributes in the `argument` block of the module loader will be rejected if they are not defined in the module source.

## Exported fields

The following fields are exported and can be referenced by other components:

Expand table

| Name      | Type       | Description                       |
|-----------|------------|-----------------------------------|
| `exports` | `map(any)` | The exports of the Module loader. |

`exports` exposes the `export` config block inside a module. It can be accessed from the parent config via `module.file.LABEL.exports.EXPORT_LABEL`.

Values in `exports` correspond to [export blocks](../../config-blocks/export/) defined in the module source.

## Component health

`module.file` is reported as healthy if the most recent load of the module was successful.

If the module is not loaded successfully, the current health displays as unhealthy and the health includes the error from loading the module.

## Debug information

`module.file` does not expose any component-specific debug information.

## Debug metrics

`module.file` does not expose any component-specific debug metrics.

## Example

In this example, we pass credentials from a parent config to a module which loads a `prometheus.remote_write` component. The exports of the `prometheus.remote_write` component are exposed to parent config, allowing the parent config to pass metrics to it.

Parent:

Alloy ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy

```alloy
module.file "metrics" {
  filename = "/path/to/prometheus_remote_write_module.river"

  arguments {
    username = env("PROMETHEUS_USERNAME")
    password = env("PROMETHEUS_PASSWORD")
  }
}

prometheus.exporter.unix "default" { }

prometheus.scrape "local_agent" {
  targets         = prometheus.exporter.unix.default.targets
  forward_to      = [module.file.metrics.exports.prometheus_remote_write.receiver]
  scrape_interval = "10s"
}
```

Module:

Alloy ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy

```alloy
argument "username" { }

argument "password" { }

export "prometheus_remote_write" {
  value = prometheus.remote_write.grafana_cloud
}

prometheus.remote_write "grafana_cloud" {
  endpoint {
    url = "https://prometheus-us-central1.grafana.net/api/prom/push"

    basic_auth {
      username = argument.username.value
      password = argument.password.value
    }
  }
}
```