Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

[release/v1.5] Update linting in local.* topics #2581

Merged
merged 1 commit into from
Jan 30, 2025
Merged

[release/v1.5] Update linting in local.* topics #2581

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
34 changes: 19 additions & 15 deletions docs/sources/reference/components/local/local.file.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -6,61 +6,65 @@ description: Learn about local.file
title: local.file
---

# local.file
# `local.file`

`local.file` exposes the contents of a file on disk to other components.
The file will be watched for changes so that its latest content is always exposed.

The most common use of `local.file` is to load secrets (e.g., API keys) from files.
The most common use of `local.file` is to load secrets (for example, API keys) from files.

Multiple `local.file` components can be specified by giving them different labels.

## Usage

```alloy
local.file "LABEL" {
filename = FILE_NAME
local.file "<LABEL>" {
filename = "<FILE_NAME>"
}
```

## Arguments

The following arguments are supported:

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][] | `false` | no
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
`is_secret` | `bool` | Marks the file as containing a [secret][]. | `false` | no
`poll_frequency` | `duration` | How often to poll for file changes. | `"1m"` | no

[secret]: ../../../../get-started/configuration-syntax/expressions/types_and_values/#secrets

{{< docs/shared lookup="reference/components/local-file-arguments-text.md" source="alloy" version="<ALLOY_VERSION>" >}}

## Blocks

The `local.file` component doesn't support any blocks. You can configure this component with arguments.

## Exported fields

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

Name | Type | Description
----------|----------------------|---------------------------------------------------
`content` | `string` or `secret` | The contents of the file from the most recent read
----------|----------------------|----------------------------------------------------
`content` | `string` or `secret` | The contents of the file from the most recent read.

The `content` field will have the `secret` type only if the `is_secret` argument was true.
The `content` field has the `secret` type only if the `is_secret` argument is true.

You can use `local.file.LABEL.content` to access the contents of the file.

## Component health

`local.file` will be reported as healthy whenever if the watched file was read successfully.
`local.file` is reported as healthy whenever if the watched file was read successfully.

Failing to read the file whenever an update is detected (or after the poll period elapses) will cause the component to be reported as unhealthy.
When unhealthy, exported fields will be kept at the last healthy value.
The read error will be exposed as a log message and in the debug information for the component.

## Debug information

`local.file` does not expose any component-specific debug information.
`local.file` doesn't expose any component-specific debug information.

## Debug metrics

Expand Down
54 changes: 32 additions & 22 deletions docs/sources/reference/components/local/local.file_match.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -6,7 +6,7 @@ description: Learn about local.file_match
title: local.file_match
---

# local.file_match
# `local.file_match`

`local.file_match` discovers files on the local filesystem using glob patterns and the [doublestar][] library.

Expand All @@ -22,18 +22,22 @@ local.file_match "LABEL" {

## Arguments

The following arguments are supported:
You can use the following arguments with `local.file_match`:

Name | Type | Description | Default | Required
--------------- | ------------------- | ------------------------------------------------------------------------------------------ |---------| --------
`path_targets` | `list(map(string))` | Targets to expand; looks for glob patterns on the `__path__` and `__path_exclude__` keys. | | yes
`sync_period` | `duration` | How often to sync filesystem and targets. | `"10s"` | no

`path_targets` uses [doublestar][] style paths.
* `/tmp/**/*.log` will match all subfolders of `tmp` and include any files that end in `*.log`.
* `/tmp/apache/*.log` will match only files in `/tmp/apache/` that end in `*.log`.
* `/tmp/**` will match all subfolders of `tmp`, `tmp` itself, and all files.

* `/tmp/**/*.log` matches all subdirectories of `tmp` and include any files that end in `*.log`.
* `/tmp/apache/*.log` matches only files in `/tmp/apache/` that end in `*.log`.
* `/tmp/**` matches all subdirectories of `tmp`, `tmp` itself, and all files.

## Blocks

The `local.file_match` component doesn't support any blocks. You can configure this component with arguments.

## Exported fields

Expand All @@ -43,7 +47,7 @@ Name | Type | Description
----------|---------------------|---------------------------------------------------
`targets` | `list(map(string))` | The set of targets discovered from the filesystem.

Each target includes the following labels:
Each target includes the following label:

* `__path__`: Absolute path to the file.

Expand All @@ -54,14 +58,16 @@ In those cases, exported fields retain their last healthy values.

## Debug information

`local.file_match` does not expose any component-specific debug information.
`local.file_match` doesn't expose any component-specific debug information.

## Debug metrics

`local.file_match` does not expose any component-specific debug metrics.
`local.file_match` doesn't expose any component-specific debug metrics.

## Examples

The following examples show you how to use `local.file_match` to find and send log files to Loki

### Send `/tmp/logs/*.log` files to Loki

This example discovers all files and folders under `/tmp/logs`.
Expand All @@ -79,22 +85,24 @@ loki.source.file "files" {

loki.write "endpoint" {
endpoint {
url = LOKI_URL
url = <LOKI_URL>
basic_auth {
username = USERNAME
password = PASSWORD
username = <USERNAME>
password = <PASSWORD>
}
}
}
```

Replace the following:
- `LOKI_URL`: The URL of the Loki server to send logs to.
- `USERNAME`: The username to use for authentication to the Loki API.
- `PASSWORD`: The password to use for authentication to the Loki API.

### Send Kubernetes pod logs to Loki
* _`<LOKI_URL>`_: The URL of the Loki server to send logs to.
* _`<USERNAME>`_: The username to use for authentication to the Loki API.
* _`<PASSWORD>`_: The password to use for authentication to the Loki API.

This example finds all the logs on pods and monitors them.
### Send Kubernetes Pod logs to Loki

This example finds all the logs on Pods and monitors them.

```alloy
discovery.kubernetes "k8s" {
Expand Down Expand Up @@ -129,18 +137,20 @@ loki.source.file "pods" {

loki.write "endpoint" {
endpoint {
url = LOKI_URL
url = <LOKI_URL>
basic_auth {
username = USERNAME
password = PASSWORD
username = <USERNAME>
password = <PASSWORD>
}
}
}
```

Replace the following:
- `LOKI_URL`: The URL of the Loki server to send logs to.
- `USERNAME`: The username to use for authentication to the Loki API.
- `PASSWORD`: The password to use for authentication to the Loki API.

* _`<LOKI_URL>`_: The URL of the Loki server to send logs to.
* _`<USERNAME>`_: The username to use for authentication to the Loki API.
* _`<PASSWORD>`_: The password to use for authentication to the Loki API.

<!-- START GENERATED COMPATIBLE COMPONENTS -->

Expand Down