Menu
Grafana Cloud

loki.source.awsfirehose

loki.source.awsfirehose receives log entries over HTTP from AWS Firehose and forwards them to other loki.* components.

The HTTP API exposed is compatible with the Firehose HTTP Delivery API. Since the API model that AWS Firehose uses to deliver data over HTTP is generic enough, the same component can be used to receive data from multiple origins:

The component uses a heuristic to try to decode as much information as possible from each log record, and it falls back to writing the raw records to Loki. The decoding process goes as follows:

  • AWS Firehose sends batched requests
  • Each record is treated individually
  • For each record received in each request:

The component exposes some internal labels, available for relabeling. The following tables describes internal labels available in records coming from any source.

NameDescriptionExample
__aws_firehose_request_idFirehose request ID.a1af4300-6c09-4916-ba8f-12f336176246
__aws_firehose_source_arnFirehose delivery stream ARN.arn:aws:firehose:us-east-2:123:deliverystream/aws_firehose_test_stream

If the source of the Firehose record is CloudWatch logs, the request is further decoded and enriched with even more labels, exposed as follows:

NameDescriptionExample
__aws_ownerThe AWS Account ID of the originating log data.111111111111
__aws_cw_log_groupThe log group name of the originating log data.CloudTrail/logs
__aws_cw_log_streamThe log stream name of the originating log data.111111111111_CloudTrail/logs_us-east-1
__aws_cw_matched_filtersThe list of subscription filter names that match the originating log data. The list is encoded as a comma-separated list.Destination,Destination2
__aws_cw_msg_typeData messages will use the DATA_MESSAGE type. Sometimes CloudWatch Logs may emit Kinesis Data Streams records with a CONTROL_MESSAGE type, mainly for checking if the destination is reachable.DATA_MESSAGE

Refer to Examples for a full example configuration showing how to enrich each log entry with these labels.

Usage

alloy
loki.source.awsfirehose "LABEL" {
    http {
        listen_address = "LISTEN_ADDRESS"
        listen_port = PORT
    }
    forward_to = RECEIVER_LIST
}

The component will start an HTTP server on the configured port and address with the following endpoints:

You can use the X-Amz-Firehose-Common-Attributes header to set extra static labels. You can configure the header in the Parameters section of the Amazon Data Firehose delivery stream configuration. Label names must be prefixed with lbl_. The prefix is removed before the label is stored in the log entry. Label names and label values must be compatible with the Prometheus data model specification.

Example of the valid X-Amz-Firehose-Common-Attributes value with two custom labels:

json
{
  "commonAttributes": {
    "lbl_label1": "value1",
    "lbl_label2": "value2"
  }
}

Arguments

loki.source.awsfirehose supports the following arguments:

NameTypeDescriptionDefaultRequired
forward_tolist(LogsReceiver)List of receivers to send log entries to.yes
use_incoming_timestampboolWhether or not to use the timestamp received from the request.falseno
relabel_rulesRelabelRulesRelabeling rules to apply on log entries.{}no
access_keysecretIf set, require AWS Firehose to provide a matching key.""no

The relabel_rules field can make use of the rules export value from a loki.relabel component to apply one or more relabeling rules to log entries before they’re forwarded to the list of receivers in forward_to.

Blocks

The following blocks are supported inside the definition of loki.source.awsfirehose:

HierarchyNameDescriptionRequired
httphttpConfigures the HTTP server that receives requests.no
grpcgrpcConfigures the gRPC server that receives requests.no

http

The http block configures the HTTP server.

You can use the following arguments to configure the http block. Any omitted fields take their default values.

NameTypeDescriptionDefaultRequired
conn_limitintMaximum number of simultaneous HTTP connections. Defaults to no limit.0no
listen_addressstringNetwork address on which the server listens for new connections. Defaults to accepting all incoming connections.""no
listen_portintPort number on which the server listens for new connections.8080no
server_idle_timeoutdurationIdle timeout for HTTP server."120s"no
server_read_timeoutdurationRead timeout for HTTP server."30s"no
server_write_timeoutdurationWrite timeout for HTTP server."30s"no

grpc

The grpc block configures the gRPC server.

You can use the following arguments to configure the grpc block. Any omitted fields take their default values.

NameTypeDescriptionDefaultRequired
conn_limitintMaximum number of simultaneous HTTP connections. Defaults to no limit.0no
listen_addressstringNetwork address on which the server listens for new connections. It defaults to accepting all incoming connections.""no
listen_portintPort number on which the server listens for new connections. Defaults to a random free port.0no
max_connection_age_gracedurationAn additive period after max_connection_age after which the connection is forcibly closed."infinity"no
max_connection_agedurationThe duration for the maximum time a connection may exist before it is closed."infinity"no
max_connection_idledurationThe duration after which an idle connection is closed."infinity"no
server_max_concurrent_streamsintLimit on the number of concurrent streams for gRPC calls (0 = unlimited).100no
server_max_recv_msg_sizeintLimit on the size of a gRPC message this server can receive (bytes).4MBno
server_max_send_msg_sizeintLimit on the size of a gRPC message this server can send (bytes).4MBno

Exported fields

loki.source.awsfirehose doesn’t export any fields.

Component health

loki.source.awsfirehose is only reported as unhealthy if given an invalid configuration.

Debug metrics

The following are some of the metrics that are exposed when this component is used.

Note

The metrics include labels such as status_code where relevant, which you can use to measure request success rates.
  • loki_source_awsfirehose_request_errors (counter): Count of errors while receiving a request.
  • loki_source_awsfirehose_record_errors (counter): Count of errors while decoding an individual record.
  • loki_source_awsfirehose_records_received (counter): Count of records received.
  • loki_source_awsfirehose_batch_size (histogram): Size (in units) of the number of records received per request.
  • loki_source_awsfirehose_invalid_static_labels_errors (counter): Count number of errors while processing AWS Firehose static labels.

Example

This example starts an HTTP server on 0.0.0.0 address and port 9999. The server receives log entries and forwards them to a loki.write component. The loki.write component will send the logs to the specified loki instance using basic auth credentials provided.

alloy
loki.write "local" {
    endpoint {
        url = "http://loki:3100/api/v1/push"
        basic_auth {
            username = "<your username>"
            password_file = "<your password file>"
        }
    }
}

loki.source.awsfirehose "loki_fh_receiver" {
    http {
        listen_address = "0.0.0.0"
        listen_port = 9999
    }
    forward_to = [
        loki.write.local.receiver,
    ]
}

As another example, if you are receiving records that originated from a CloudWatch logs subscription, you can enrich each received entry by relabeling internal labels. The following configuration builds upon the one above but keeps the origin log stream and group as log_stream and log_group, respectively.

alloy
loki.write "local" {
    endpoint {
        url = "http://loki:3100/api/v1/push"
        basic_auth {
            username = "<your username>"
            password_file = "<your password file>"
        }
    }
}

loki.source.awsfirehose "loki_fh_receiver" {
    http {
        listen_address = "0.0.0.0"
        listen_port = 9999
    }
    forward_to = [
        loki.write.local.receiver,
    ]
    relabel_rules = loki.relabel.logging_origin.rules
}

loki.relabel "logging_origin" {
  rule {
    action = "replace"
    source_labels = ["__aws_cw_log_group"]
    target_label = "log_group"
  }
  rule {
    action = "replace"
    source_labels = ["__aws_cw_log_stream"]
    target_label = "log_stream"
  }
  forward_to = []
}

Compatible components

loki.source.awsfirehose can accept arguments from the following components:

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.