---
title: "loki.source.gcplog | Grafana Cloud documentation"
description: "Learn about loki.source.gcplog"
---

# `loki.source.gcplog`

`loki.source.gcplog` retrieves logs from cloud resources such as GCS buckets, load balancers, or Kubernetes clusters running on GCP by making use of Pub/Sub [subscriptions](https://cloud.google.com/pubsub/docs/subscriber).

The component uses either the ‘push’ or ‘pull’ strategy to retrieve log entries and forward them to the list of receivers in `forward_to`.

You can specify multiple `loki.source.gcplog` components by giving them different labels.

## Usage

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

```alloy
loki.source.gcplog "<LABEL>" {
  pull {
    project_id   = "<PROJECT_ID>"
    subscription = "<SUB_ID>"
  }

  forward_to = <RECEIVER_LIST>
}
```

## Arguments

You can use the following arguments with `loki.source.gcplog`:

Expand table

| Name            | Type                 | Description                               | Default | Required |
|-----------------|----------------------|-------------------------------------------|---------|----------|
| `forward_to`    | `list(LogsReceiver)` | List of receivers to send log entries to. |         | yes      |
| `relabel_rules` | `RelabelRules`       | Relabeling rules to apply on log entries. | `{}`    | no       |

## Blocks

You can use the following blocks with `loki.source.gcplog`:

No valid configuration blocks found.

The `pull` and `push` inner blocks are mutually exclusive. A component must contain exactly one of the two in its definition. The `http` and `grpc` block are just used when the `push` block is configured.

### `pull`

The `pull` block defines which GCP project ID and subscription to read log entries from.

The following arguments can be used to configure the `pull` block. Any omitted fields take their default values.

Expand table

| Name                     | Type          | Description                                                               | Default | Required |
|--------------------------|---------------|---------------------------------------------------------------------------|---------|----------|
| `project_id`             | `string`      | The GCP project id the subscription belongs to.                           |         | yes      |
| `subscription`           | `string`      | The subscription to pull logs from.                                       |         | yes      |
| `labels`                 | `map(string)` | Additional labels to associate with incoming logs.                        | `{}`    | no       |
| `use_full_line`          | `bool`        | Send the full line from Cloud Logging even if `textPayload` is available. | `false` | no       |
| `use_incoming_timestamp` | `bool`        | Whether to use the incoming log timestamp.                                | `false` | no       |

The following blocks can be used to configure the `pull` block:

Expand table

| Name               | Description                                                              | Required |
|--------------------|--------------------------------------------------------------------------|----------|
| \[`limit`]\[limit] | Configures Pub/Sub flow-control limits for in-flight message processing. | no       |

To make use of the `pull` strategy, the GCP project must have been [configured](/docs/loki/next/clients/promtail/gcplog-cloud/) to forward its cloud resource logs onto a Pub/Sub topic for `loki.source.gcplog` to consume.

Typically, the host system also needs to have its GCP [credentials](https://cloud.google.com/docs/authentication/application-default-credentials) configured. One way to do it, is to point the `GOOGLE_APPLICATION_CREDENTIALS` environment variable to the location of a credential configuration JSON file or a service account key.

### `limit`

The `limit` block configures flow-control budgets for unprocessed Pub/Sub messages. When either budget is reached, Pub/Sub delivery is throttled, which limits concurrent in-flight message handling.

Expand table

| Name                       | Type     | Description                                                                               | Default  | Required |
|----------------------------|----------|-------------------------------------------------------------------------------------------|----------|----------|
| `max_outstanding_bytes`    | `string` | Byte budget for unprocessed messages, hitting this budget throttles delivery concurrency. | `"1GiB"` | no       |
| `max_outstanding_messages` | `int`    | Count budget for unprocessed messages, hitting this budget caps in-flight concurrency.    | `1000`   | no       |

### `push`

The `push` block defines the configuration of the server that receives push requests from the GCP Pub/Sub servers.

The following arguments can be used to configure the `push` block. Any omitted fields take their default values.

Expand table

| Name                        | Type          | Description                                                                                                                               | Default | Required |
|-----------------------------|---------------|-------------------------------------------------------------------------------------------------------------------------------------------|---------|----------|
| `graceful_shutdown_timeout` | `duration`    | Timeout for servers graceful shutdown. If configured, should be greater than zero.                                                        | `"30s"` | no       |
| `labels`                    | `map(string)` | Additional labels to associate with incoming entries.                                                                                     | `{}`    | no       |
| `push_timeout`              | `duration`    | Sets a maximum processing time for each incoming GCP log entry.                                                                           | `"0s"`  | no       |
| `use_full_line`             | `bool`        | Send the full line from Cloud Logging even if `textPayload` is available. If `textPayload` is present in the line, it’s used as log line. | `false` | no       |
| `use_incoming_timestamp`    | `bool`        | Whether to use the incoming entry timestamp.                                                                                              | `false` | no       |

The server listens for POST requests from GCP Push subscriptions on `HOST:PORT/gcp/api/v1/push`.

By default, for both strategies the component assigns the log entry timestamp as the time it was processed, except if `use_incoming_timestamp` is set to true.

The `labels` map is applied to every entry that passes through the component.

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

Expand table

| Name                            | Type       | Description                                                                                                         | Default      | Required |
|---------------------------------|------------|---------------------------------------------------------------------------------------------------------------------|--------------|----------|
| `conn_limit`                    | `int`      | Maximum number of simultaneous gRPC connections. Defaults to no limit.                                              | `0`          | no       |
| `listen_address`                | `string`   | Network address on which the server listens for new connections. It defaults to accepting all incoming connections. | `""`         | no       |
| `listen_port`                   | `int`      | Port number on which the server listens for new connections. Defaults to a random free port.                        | `0`          | no       |
| `max_connection_age_grace`      | `duration` | An additive period after `max_connection_age` after which the connection is forcibly closed.                        | `"infinity"` | no       |
| `max_connection_age`            | `duration` | The duration for the maximum time a connection may exist before it’s closed.                                        | `"infinity"` | no       |
| `max_connection_idle`           | `duration` | The duration after which an idle connection is closed.                                                              | `"infinity"` | no       |
| `server_max_concurrent_streams` | `int`      | Limit on the number of concurrent streams for gRPC calls (0 = unlimited).                                           | `100`        | no       |
| `server_max_recv_msg_size`      | `int`      | Limit on the size of a gRPC message this server can receive (bytes).                                                | `4MB`        | no       |
| `server_max_send_msg_size`      | `int`      | Limit on the size of a gRPC message this server can send (bytes).                                                   | `4MB`        | 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.

Expand table

| Name                   | Type       | Description                                                                                                      | Default  | Required |
|------------------------|------------|------------------------------------------------------------------------------------------------------------------|----------|----------|
| `conn_limit`           | `int`      | Maximum number of simultaneous HTTP connections. Defaults to no limit.                                           | `0`      | no       |
| `listen_address`       | `string`   | Network address on which the server listens for new connections. Defaults to accepting all incoming connections. | `""`     | no       |
| `listen_port`          | `int`      | Port number on which the server listens for new connections.                                                     | `8080`   | no       |
| `server_idle_timeout`  | `duration` | Idle timeout for HTTP server.                                                                                    | `"120s"` | no       |
| `server_read_timeout`  | `duration` | Read timeout for HTTP server.                                                                                    | `"30s"`  | no       |
| `server_write_timeout` | `duration` | Write timeout for HTTP server.                                                                                   | `"30s"`  | no       |

### `tls`

The `tls` block configures TLS for the HTTP and gRPC servers.

Expand table

| Name               | Type     | Description                                                      | Default          | Required |
|--------------------|----------|------------------------------------------------------------------|------------------|----------|
| `cert_pem`         | `string` | PEM data of the server TLS certificate.                          | `""`             | no       |
| `cert_file`        | `string` | Path to the server TLS certificate on disk.                      | `""`             | no       |
| `client_auth_type` | `string` | Client authentication to use.                                    | `"NoClientCert"` | no       |
| `client_ca_file`   | `string` | Path to the client CA file on disk to validate requests against. | `""`             | no       |
| `client_ca_pem`    | `string` | PEM data of the client CA to validate requests against.          | `""`             | no       |
| `key_file`         | `string` | Path to the server TLS key on disk.                              | `""`             | no       |
| `key_pem`          | `secret` | PEM data of the server TLS key.                                  | `""`             | no       |

The following pairs of arguments are mutually exclusive and can’t both be set simultaneously:

- `cert_pem` and `cert_file`
- `key_pem` and `key_file`

When configuring client authentication, both the client certificate (using `cert_pem` or `cert_file`) and the client key (using `key_pem` or `key_file`) must be provided.

## Exported fields

`loki.source.gcplog` doesn’t export any fields.

## Component health

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

## Debug information

`loki.source.gcplog` exposes some debug information per gcplog listener:

- The configured strategy.
- Their label set.
- When using a `push` strategy, the listen address.

## Debug metrics

When using the `pull` strategy, the component exposes the following debug metrics:

- `loki_source_gcplog_pull_entries_total` (counter): Number of entries received by the gcplog target.
- `loki_source_gcplog_pull_last_success_scrape` (gauge): Timestamp of target’s last successful poll.
- `loki_source_gcplog_pull_parsing_errors_total` (counter): Total number of parsing errors while receiving gcplog messages.

When using the `push` strategy, the component exposes the following debug metrics:

- `loki_source_gcplog_push_inflight_requests` (gauge): Current number of inflight requests.
- `loki_source_gcplog_push_request_duration_seconds` (histogram): HTTP request handling time, in seconds.
- `loki_source_gcplog_push_request_message_bytes` (histogram): Request message size, in bytes.
- `loki_source_gcplog_push_response_message_bytes` (histogram): Response message size, in bytes.
- `loki_source_gcplog_push_tcp_connections` (gauge): Current number of accepted TCP connections.
- `loki_source_gcplog_push_entries_total` (counter): Number of entries received by the gcplog target.
- `loki_source_gcplog_push_parsing_errors_total` (counter): Number of parsing errors while receiving gcplog messages.

## Example

This example listens for GCP Pub/Sub PushRequests on `0.0.0.0:8080` and forwards them to a `loki.write` component.

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

```alloy
loki.source.gcplog "local" {
  push {}

  forward_to = [loki.write.local.receiver]
}

loki.write "local" {
  endpoint {
    url = "loki:3100/api/v1/push"
  }
}
```

This example listens for GCP Pub/Sub PushRequests on `0.0.0.0:4040`, and forwards them to a `loki.write` component.

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

```alloy
loki.source.gcplog "local" {
  push {
    http {
        listen_port = 4040
    }
  }

  forward_to = [loki.write.local.receiver]
}

loki.write "local" {
  endpoint {
    url = "loki:3100/api/v1/push"
  }
}
```

## Compatible components

`loki.source.gcplog` can accept arguments from the following components:

- Components that export [Loki `LogsReceiver`](/docs/grafana-cloud/send-data/alloy/reference/compatibility/#loki-logsreceiver-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.