---
title: "otelcol.receiver.awss3 | Grafana Alloy documentation"
description: "Learn about otelcol.receiver.awss3"
---

# `otelcol.receiver.awss3`

> **EXPERIMENTAL**: This is an [experimental](/docs/release-life-cycle/) component. Experimental components are subject to frequent breaking changes, and may be removed with no equivalent replacement. To enable and use an experimental component, you must set the `stability.level` [flag](/docs/alloy/latest/reference/cli/run/) to `experimental`.

`otelcol.receiver.awss3` receives telemetry stored in S3 by the [AWS S3 Exporter](./otelcol.exporter.awss3.md).

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

The receiver has two modes of operation:

- **Time Range Mode** - Specify start and end to fetch data from a specific time range.
- **SQS Message Mode** - Subscribe to SQS messages to process objects as they arrive.

The receiver supports the following encodings:

- `otlp_json` (OpenTelemetry Protocol format represented as JSON) with a suffix of `.json`
- `otlp_proto` (OpenTelemetry Protocol format represented as Protocol Buffers) with a suffix of `.binpb`

> Note
> 
> Currently, `otelcol.receiver.awss3` receiver doesn’t support encoding extensions.

You can specify multiple `otelcol.receiver.awss3` components by giving them different labels.

## Usage

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

```alloy
otelcol.receiver.awss3 "<LABEL>" {
  start_time = "..."
  end_time = "..."

  s3downloader {
    s3_bucket = "..."
    s3_prefix = "..."
  }

  output {
    logs = [...]
    metrics = [...]
    trace = [...]
  }
}
```

## Arguments

You can use the following arguments with `otelcol.receiver.awss3`:

Expand table

| Name         | Type     | Description                                 | Default | Required                      |
|--------------|----------|---------------------------------------------|---------|-------------------------------|
| `start_time` | `string` | The time at which to start retrieving data. |         | Required if fetching by time. |
| `end_time`   | `string` | The time at which to stop retrieving data.  |         | Required if fetching by time. |

The `start_time` and `end_time` fields use one of the following time formats: RFC3339, `YYYY-MM-DD HH:MM`, or `YYYY-MM-DD`. When using `YYYY-MM-DD`, the time defaults to `00:00`.

> Note
> 
> Time-based configuration (`start_time` and `end_time` arguments) can’t be combined together with [`sqs`](#sqs) block.

Refer to the upstream receiver [documentation](https://github.com/open-telemetry/opentelemetry-collector-contrib/tree/v0.147.0/receiver/awss3receiver#configuration) for more details.

## Blocks

You can use the following blocks with `otelcol.receiver.awss3`:

No valid configuration blocks found.

### `s3downloader`

Required

The `s3downloader` block contains AWS S3 downloader related configuration to control things like bucket, prefix, batching, connections, retries, etc.

The following arguments are supported:

Expand table

| Name                    | Type     | Description                                                                                                                          | Default                                       | Required |
|-------------------------|----------|--------------------------------------------------------------------------------------------------------------------------------------|-----------------------------------------------|----------|
| `s3_bucket`             | `string` | S3 bucket.                                                                                                                           |                                               | yes      |
| `s3_prefix`             | `string` | Prefix for the S3 key (root directory inside bucket).                                                                                |                                               | yes      |
| `endpoint_partition_id` | `string` | Partition id to use if `endpoint` is specified.                                                                                      | `"aws"`                                       | no       |
| `endpoint`              | `string` | Overrides the endpoint used by the exporter instead of constructing it from `region` and `s3_bucket`.                                |                                               | no       |
| `file_prefix`           | `string` | Prefix used to filter files for download.                                                                                            |                                               | no       |
| `region`                | `string` | AWS region.                                                                                                                          | `"us-east-1"`                                 | no       |
| `s3_force_path_style`   | `bool`   | When enabled, forces the request to use [path-style addressing](http://docs.aws.amazon.com/AmazonS3/latest/dev/VirtualHosting.html). | `false`                                       | no       |
| `s3_partition_format`   | `string` | Format for the partition key. See [strftime](https://www.man7.org/linux/man-pages/man3/strftime.3.html) for format specification.    | `"year=%Y/month=%m/day=%d/hour=%H/minute=%M"` | no       |
| `s3_partition_timezone` | `string` | IANA timezone name applied when formatting the partition key.                                                                        | Local time                                    | no       |

### `sqs`

The `sqs` block holds SQS queue configuration for receiving object change notifications.

The following arguments are supported:

Expand table

| Name                     | Type     | Description                                                     | Default | Required |
|--------------------------|----------|-----------------------------------------------------------------|---------|----------|
| `queue_url`              | `string` | The URL of the SQS queue that receives S3 bucket notifications. |         | yes      |
| `region`                 | `string` | AWS region of the SQS queue.                                    |         | yes      |
| `endpoint`               | `string` | Custom endpoint for the SQS service.                            |         | no       |
| `max_number_of_messages` | `int`    | Maximum number of messages to retrieve in a single SQS request. | `10`    | no       |
| `wait_time_seconds`      | `int`    | Wait time in seconds for long polling SQS requests.             | `20`    | no       |

> Note
> 
> You must configure your S3 bucket to send event notifications to the SQS queue. Time-based configuration (`start_time`/`end_time`) and SQS configuration can’t be used together.

### `output`

Required

The `output` block configures a set of components to forward resulting telemetry data to.

The following arguments are supported:

Expand table

| Name      | Type                     | Description                           | Default | Required |
|-----------|--------------------------|---------------------------------------|---------|----------|
| `logs`    | `list(otelcol.Consumer)` | List of consumers to send logs to.    | `[]`    | no       |
| `metrics` | `list(otelcol.Consumer)` | List of consumers to send metrics to. | `[]`    | no       |
| `traces`  | `list(otelcol.Consumer)` | List of consumers to send traces to.  | `[]`    | no       |

You must specify the `output` block, but all its arguments are optional. By default, telemetry data is dropped. Configure the `metrics`, `logs`, and `traces` arguments accordingly to send telemetry data to other components.

## Exported fields

`otelcol.receiver.awss3` doesn’t export any fields.

## Component health

`otelcol.receiver.awss3` is only reported as unhealthy if given an invalid configuration.

## Debug information

`otelcol.receiver.awss3` doesn’t expose any component-specific debug information.

## Example

This example forwards received traces through a batch processor before finally sending it to an OTLP-capable endpoint:

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

```alloy
// Time range mode:
otelcol.receiver.awss3 "default" {
  start_time = "2024-01-01 01:00"
  end_time = "2024-01-02"

  s3downloader {
    region = "us-west-1"
    s3_bucket = "mybucket"
    s3_prefix = "trace"
    s3_partition = "minute"
  }

  output {
    traces = [otelcol.processor.batch.default.input]
  }
}

// SQS message mode:
otelcol.receiver.awss3 "sqs_traces" {
  s3downloader {
    region = "us-east-1"
    s3_bucket = "mybucket"
    s3_prefix = "mytrace"
  }

  sqs {
    queue_url = "https://sqs.us-east-1.amazonaws.com/123456789012/test-queue"
    region = "us-east-1"
  }

  output {
    traces = [otelcol.processor.batch.default.input]
  }
}

otelcol.processor.batch "default" {
  output {
    metrics = [otelcol.exporter.otlphttp.default.input]
    logs    = [otelcol.exporter.otlphttp.default.input]
    traces  = [otelcol.exporter.otlphttp.default.input]
  }
}

otelcol.exporter.otlphttp "default" {
  client {
    endpoint = sys.env("<OTLP_ENDPOINT>")
  }
}
```

## Compatible components

`otelcol.receiver.awss3` can accept arguments from the following components:

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

> 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.