---
title: "otelcol.exporter.file | Grafana Alloy documentation"
description: "Learn about otelcol.exporter.file"
---

# `otelcol.exporter.file`

`otelcol.exporter.file` accepts metrics, logs, and traces telemetry data from other `otelcol` components and writes it to files on disk. You can write data in JSON or Protocol Buffers `proto` format. You can optionally enable file rotation, compression, and separate output files based on a resource attribute.

> Note
> 
> `otelcol.exporter.file` is a wrapper over the upstream OpenTelemetry Collector Contrib [`fileexporter`](https://github.com/open-telemetry/opentelemetry-collector-contrib/tree/v0.147.0/exporter/fileexporter) exporter. Bug reports or feature requests will be redirected to the upstream repository, if necessary.

You can specify multiple `otelcol.exporter.file` components by giving them different labels.

## Usage

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

```alloy
otelcol.exporter.file "<LABEL>" {
  path = "<PATH>"
}
```

## Arguments

You can use the following arguments with `otelcol.exporter.file`:

Expand table

| Name             | Type       | Description                                              | Default  | Required |
|------------------|------------|----------------------------------------------------------|----------|----------|
| `path`           | `string`   | Path to the file to write telemetry data.                |          | yes      |
| `append`         | `bool`     | Append to the file when `true`; truncate when `false`.   | `false`  | no       |
| `compression`    | `string`   | Compression algorithm. Alloy supports only `"zstd"`.     |          | no       |
| `flush_interval` | `duration` | Time between flushes to disk. Must be greater than zero. | `"1s"`   | no       |
| `format`         | `string`   | Data format. Must be `"json"` or `"proto"`.              | `"json"` | no       |

You can’t enable `append` and `compression` together.

> Note
> 
> The upstream `encoding` argument isn’t supported. Use `format` instead.

## Blocks

You can use the following blocks with `otelcol.exporter.file`:

No valid configuration blocks found.

You can’t enable `append` and `rotation` together.

### `debug_metrics`

The `debug_metrics` block configures the metrics that this component generates to monitor its state.

The following arguments are supported:

Expand table

| Name                               | Type      | Description                                          | Default | Required |
|------------------------------------|-----------|------------------------------------------------------|---------|----------|
| `disable_high_cardinality_metrics` | `boolean` | Whether to disable certain high cardinality metrics. | `true`  | no       |

`disable_high_cardinality_metrics` is the Alloy equivalent to the `telemetry.disableHighCardinalityMetrics` feature gate in the OpenTelemetry Collector. It removes attributes that could cause high cardinality metrics. For example, attributes with IP addresses and port numbers in metrics about HTTP and gRPC connections are removed.

> Note
> 
> If configured, `disable_high_cardinality_metrics` only applies to `otelcol.exporter.*` and `otelcol.receiver.*` components.

### `group_by`

The `group_by` block writes telemetry to separate files based on a resource attribute.

Expand table

| Name                 | Type     | Description                                            | Default                       | Required |
|----------------------|----------|--------------------------------------------------------|-------------------------------|----------|
| `enabled`            | `bool`   | Enable `group_by` behavior.                            | `false`                       | no       |
| `max_open_files`     | `int`    | Maximum number of simultaneously open files.           | `100`                         | no       |
| `resource_attribute` | `string` | Resource attribute whose value replaces `*` in `path`. | `"fileexporter.path_segment"` | no       |

When `group_by.enabled` is `true`:

- `path` must contain exactly one `*` character.
- The exporter replaces the `*` with the `resource_attribute` value.
- `rotation` settings don’t apply.

### `rotation`

The `rotation` block configures rolling log file behavior.

Expand table

| Name            | Type   | Description                                                           | Default | Required |
|-----------------|--------|-----------------------------------------------------------------------|---------|----------|
| `localtime`     | `bool` | Use local time instead of UTC in rotated filenames.                   | `false` | no       |
| `max_backups`   | `int`  | Maximum number of rotated files to retain.                            | `100`   | no       |
| `max_days`      | `int`  | Maximum number of days to retain files. `0` keeps files indefinitely. | `0`     | no       |
| `max_megabytes` | `int`  | Maximum size in megabytes before the file rotates.                    | `100`   | no       |

## Exported fields

`otelcol.exporter.file` doesn’t export any fields.

## Component health

`otelcol.exporter.file` is only reported as unhealthy if given an invalid configuration.

## Debug information

`otelcol.exporter.file` doesn’t expose any component-specific debug information.

## Examples

The following examples demonstrate how you can use `otelcol.exporter.file`.

### Basic file export

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

```alloy
otelcol.exporter.file "default" {
  path = "/tmp/traces.json"
}
```

### File export with rotation

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

```alloy
otelcol.exporter.file "rotated" {
  path   = "/var/log/telemetry.json"
  format = "json"

  rotation {
    max_megabytes = 50
    max_days      = 7
    max_backups   = 10
    localtime     = true
  }
}
```

### File export with compression

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

```alloy
otelcol.exporter.file "compressed" {
  path        = "/tmp/traces.jsonl"
  format      = "proto"
  compression = "zstd"
}
```

### Group by resource attribute

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

```alloy
otelcol.exporter.file "grouped" {
  path = "/tmp/logs/*/service.log"
  
  group_by {
    enabled           = true
    resource_attribute = "service.name"
    max_open_files     = 50
  }
}
```

### Complete pipeline

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

```alloy
otelcol.receiver.otlp "default" {
  grpc {
    endpoint = "0.0.0.0:4317"
  }

  http {
    endpoint = "0.0.0.0:4318"
  }

  output {
    metrics = [otelcol.exporter.file.default.input]
    logs    = [otelcol.exporter.file.default.input]
    traces  = [otelcol.exporter.file.default.input]
  }
}

otelcol.exporter.file "default" {
  path           = "/tmp/telemetry.json"
  format         = "json"
  flush_interval = "5s"

  rotation {
    max_megabytes = 100
    max_backups   = 5
  }
}
```

## Technical details

The `otelcol.exporter.file` component writes telemetry data to files on disk in either JSON or Protocol Buffers format. It supports:

- **File rotation**: Automatically rotate files based on size, age, or number of backups
- **Compression**: Compress output files using `zstd` algorithm
- **Group by attributes**: Write to different files based on resource attribute values
- **Flushing**: Configurable flush intervals to control write frequency

### File formats

- **JSON format**: Each telemetry record is written as a separate line in JSON format (JSONL)
- **`proto` format**: Binary Protocol Buffers format with length-prefixed messages

### File naming with rotation

When rotation is enabled, rotated files are renamed with a timestamp:

- Original: `data.json`
- Rotated: `data-2023-09-20T10-30-00.123.json`

### Group by functionality

When `group_by` is enabled, files are created dynamically based on resource attribute values:

- Path template: `/logs/*/app.log`
- Resource attribute `service.name=frontend`
- Resulting file: `/logs/frontend/app.log`

## Compatible components

`otelcol.exporter.file` has exports that can be consumed by the following components:

- Components that consume [OpenTelemetry `otelcol.Consumer`](../../../compatibility/#opentelemetry-otelcolconsumer-consumers)

> Note
> 
> Connecting some components may not be sensible or components may require further configuration to make the connection work correctly. Refer to the linked documentation for more details.