otelcol.exporter.file: add file exporter component with configu…

CHANGELOG.md

@@ -12,6 +12,7 @@ Main (unreleased)
 
 ### Features
 
+ - Add `otelcol.exporter.file` component to write metrics, logs, and traces to disk with optional rotation, compression, and grouping by resource attribute. (@madhub)
 - (_Experimental_) Additions to experimental `database_observability.mysql` component:
   - `explain_plans` collector now changes schema before returning the connection to the pool (@cristiangreco)
 

docs/sources/reference/components/otelcol/otelcol.exporter.file.md

@@ -0,0 +1,246 @@
+---
+canonical: https://grafana.com/docs/alloy/latest/reference/components/otelcol/otelcol.exporter.file/
+description: Learn about otelcol.exporter.file
+labels:
+  stage: general-availability
+  products:
+    - oss
+  tags:
+    - text: Community
+      tooltip: This component is developed, maintained, and supported by the Alloy user community.
+title: otelcol.exporter.file
+---
+
+# `otelcol.exporter.file`
+
+{{< docs/shared lookup="stability/community.md" source="alloy" version="<ALLOY_VERSION>" >}}
+
+`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.
+
+{{< admonition type="note" >}}
+`otelcol.exporter.file` is a wrapper over the upstream OpenTelemetry Collector Contrib [`fileexporter`][] exporter.
+Bug reports or feature requests will be redirected to the upstream repository, if necessary.
+
+[`fileexporter`]: https://github.com/open-telemetry/opentelemetry-collector-contrib/tree/{{< param "OTEL_VERSION" >}}/exporter/fileexporter
+{{< /admonition >}}
+
+You can specify multiple `otelcol.exporter.file` components by giving them different labels.
+
+## Usage
+
+```alloy
+otelcol.exporter.file "<LABEL>" {
+  path = "<PATH>"
+}
+```
+
+## Arguments
+
+You can use the following arguments with `otelcol.exporter.file`:
+
+| 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.
+
+{{< admonition type="note" >}}
+The upstream `encoding` argument isn't supported.
+Use `format` instead.
+{{< /admonition >}}
+
+## Blocks
+
+You can use the following blocks with `otelcol.exporter.file`:
+
+| Block                            | Description                                                          | Required |
+| -------------------------------- | -------------------------------------------------------------------- | -------- |
+| [`debug_metrics`][debug_metrics] | Configures internal metrics for this component.                      | no       |
+| [`group_by`][group_by]           | Writes to separate files based on a resource attribute value.        | no       |
+| [`rotation`][rotation]           | Configures file rotation. Ignored when `group_by.enabled` is `true`. | no       |
+
+You can't enable `append` and `rotation` together.
+
+[debug_metrics]: #debug_metrics
+[group_by]: #group_by
+[rotation]: #rotation
+
+### `debug_metrics`
+
+{{< docs/shared lookup="reference/components/otelcol-debug-metrics-block.md" source="alloy" version="<ALLOY_VERSION>" >}}
+
+### `group_by`
+
+The `group_by` block writes telemetry to separate files based on a resource attribute.
+
+| 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.
+
+| 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
+otelcol.exporter.file "default" {
+  path = "/tmp/traces.json"
+}
+```
+
+### File export with rotation
+
+```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
+otelcol.exporter.file "compressed" {
+  path        = "/tmp/traces.jsonl"
+  format      = "proto"
+  compression = "zstd"
+}
+```
+
+### Group by resource attribute
+
+```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
+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`
+
+<!-- START GENERATED COMPATIBLE COMPONENTS -->
+
+## Compatible components
+
+`otelcol.exporter.file` can accept arguments from the following components:
+
+- Components that export [OpenTelemetry `otelcol.Consumer`](../otelcol/#opentelemetry-otelcolconsumer-exporters)
+
+`otelcol.exporter.file` has exports that can be consumed by the following components:
+
+- Components that consume [OpenTelemetry `otelcol.Consumer`](../otelcol/#opentelemetry-otelcolconsumer-exporters)
+
+{{< admonition type="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.
+{{< /admonition >}}
+
+<!-- END GENERATED COMPATIBLE COMPONENTS -->

go.mod

@@ -120,6 +120,7 @@ require (
 	github.com/open-telemetry/opentelemetry-collector-contrib/exporter/awss3exporter v0.134.0
 	github.com/open-telemetry/opentelemetry-collector-contrib/exporter/datadogexporter v0.134.0
 	github.com/open-telemetry/opentelemetry-collector-contrib/exporter/faroexporter v0.134.0
+	github.com/open-telemetry/opentelemetry-collector-contrib/exporter/fileexporter v0.134.0
 	github.com/open-telemetry/opentelemetry-collector-contrib/exporter/googlecloudexporter v0.134.0
 	github.com/open-telemetry/opentelemetry-collector-contrib/exporter/googlecloudpubsubexporter v0.134.0
 	github.com/open-telemetry/opentelemetry-collector-contrib/exporter/kafkaexporter v0.134.0

go.sum

@@ -1194,8 +1194,6 @@ github.com/grafana/tail v0.0.0-20230510142333-77b18831edf0 h1:bjh0PVYSVVFxzINqPF
 github.com/grafana/tail v0.0.0-20230510142333-77b18831edf0/go.mod h1:7t5XR+2IA8P2qggOAHTj/GCZfoLBle3OvNSYh1VkRBU=
 github.com/grafana/vmware_exporter v0.0.5-beta.0.20250218170317-73398ba08329 h1:Rs4H1yv2Abk3xE82qpyhMGGA8rswAOA0HQZde/BYkFo=
 github.com/grafana/vmware_exporter v0.0.5-beta.0.20250218170317-73398ba08329/go.mod h1:Z28219aViNlsLlPvuCnlgHDagRdZBAZ7JOnQg1b3eWg=
-github.com/grafana/walqueue v0.0.0-20250916201216-152b1f10cca2 h1:6HRYKHfWwdIoBF5jvVAYnARFHJiKe+++j1Oxh6A1mNw=
-github.com/grafana/walqueue v0.0.0-20250916201216-152b1f10cca2/go.mod h1:LJm4P3SayTHSbHBYepsAf3WqlY/gwSYQyMs7OLLAi6A=
 github.com/grafana/walqueue v0.0.0-20250919134944-0471c03aa304 h1:0Mllr6XQcAzwxGh/zHQbL/BtVGNRzRmIRBZRHqTiG3E=
 github.com/grafana/walqueue v0.0.0-20250919134944-0471c03aa304/go.mod h1:RokiltsxYrF3qitnIdaFBGLz5UrCo7DZMMoJrrzHyPc=
 github.com/grobie/gomemcache v0.0.0-20230213081705-239240bbc445 h1:FlKQKUYPZ5yDCN248M3R7x8yu2E3yEZ0H7aLomE4EoE=
@@ -1770,6 +1768,8 @@ github.com/open-telemetry/opentelemetry-collector-contrib/exporter/datadogexport
 github.com/open-telemetry/opentelemetry-collector-contrib/exporter/datadogexporter v0.134.0/go.mod h1:x9vD3qo0vtkNl7Bvxtwo4LyOPtsizSZuNbXK1pHrKRo=
 github.com/open-telemetry/opentelemetry-collector-contrib/exporter/faroexporter v0.134.0 h1:lVff5+2fwzBLf4wnOonXTwBY4oN6hht2OYoW+R06RMA=
 github.com/open-telemetry/opentelemetry-collector-contrib/exporter/faroexporter v0.134.0/go.mod h1:ElZcmWlUZ9Jl8vpsJRiYcCI2kcVHkEUdSqZbSnMu6Tg=
+github.com/open-telemetry/opentelemetry-collector-contrib/exporter/fileexporter v0.134.0 h1:LR7GBN4SBKQPPcwui3XMVgU1d+VJrqU07pNvf8txtHU=
+github.com/open-telemetry/opentelemetry-collector-contrib/exporter/fileexporter v0.134.0/go.mod h1:pFeJM8yYk+brSkyFxS5inaKlfVDCL9cbU1b3Jtzaahw=
 github.com/open-telemetry/opentelemetry-collector-contrib/exporter/googlecloudexporter v0.134.0 h1:TTqncvaDZISq+jqCG1V/4lKoGSIq/Nv9sW/HASwJQo0=
 github.com/open-telemetry/opentelemetry-collector-contrib/exporter/googlecloudexporter v0.134.0/go.mod h1:6f9ylFRHEqwTHCNbBTW4WWw3HI6Q5GeBRWq5b9nTQ5k=
 github.com/open-telemetry/opentelemetry-collector-contrib/exporter/googlecloudpubsubexporter v0.134.0 h1:iSpowIqU8wF+EgZSAmNANwnitx63K7no3rzZagkEw2Y=
@@ -1792,6 +1792,8 @@ github.com/open-telemetry/opentelemetry-collector-contrib/extension/bearertokena
 github.com/open-telemetry/opentelemetry-collector-contrib/extension/bearertokenauthextension v0.134.0/go.mod h1:NF7VV+vfnSyVotWgH43lq3oJnp4Oe4fDY3POPBWt1Dw=
 github.com/open-telemetry/opentelemetry-collector-contrib/extension/encoding v0.134.0 h1:LMTVY3+1lM1T0OvxeuxpH2TX/pXBSbReKjU3kf37YxY=
 github.com/open-telemetry/opentelemetry-collector-contrib/extension/encoding v0.134.0/go.mod h1:EeGcRmCclYghmsurA7W5mDmvDB9nRK7ThzgpbLfqMM0=
+github.com/open-telemetry/opentelemetry-collector-contrib/extension/encoding/otlpencodingextension v0.134.0 h1:54kuw6U1Cf//N3u1O4Gl65yLCGIPeosSxe6XFNKNX5w=
+github.com/open-telemetry/opentelemetry-collector-contrib/extension/encoding/otlpencodingextension v0.134.0/go.mod h1:DVSHP3A9Cro/rRtF/kphMUKupwy6pRcGnPHD9xduz1c=
 github.com/open-telemetry/opentelemetry-collector-contrib/extension/headerssetterextension v0.134.0 h1:7N3nnnLpSNVp4TU/H8pAaRoOAwThYEqpgIJET7LDjps=
 github.com/open-telemetry/opentelemetry-collector-contrib/extension/headerssetterextension v0.134.0/go.mod h1:2Fm98wBqfvQ2cKwtWrj8o300aWTNGyhTeIRE8T8EBnM=
 github.com/open-telemetry/opentelemetry-collector-contrib/extension/jaegerremotesampling v0.134.0 h1:EwYASIRndllOlBeIpk1GLFuodnFBAiOh75xeWk9ygRM=

internal/component/all/all.go

@@ -75,6 +75,7 @@ import (
 	_ "github.com/grafana/alloy/internal/component/otelcol/exporter/datadog"                 // Import otelcol.exporter.datadog
 	_ "github.com/grafana/alloy/internal/component/otelcol/exporter/debug"                   // Import otelcol.exporter.debug
 	_ "github.com/grafana/alloy/internal/component/otelcol/exporter/faro"                    // Import otelcol.exporter.faro
+	_ "github.com/grafana/alloy/internal/component/otelcol/exporter/file"                    // Import otelcol.exporter.file
 	_ "github.com/grafana/alloy/internal/component/otelcol/exporter/googlecloud"             // Import otelcol.exporter.googlecloud
 	_ "github.com/grafana/alloy/internal/component/otelcol/exporter/googlecloudpubsub"       // Import otelcol.exporter.googlecloudpubsub
 	_ "github.com/grafana/alloy/internal/component/otelcol/exporter/kafka"                   // Import otelcol.exporter.kafka