> ## Documentation Index
> Fetch the complete documentation index at: https://otel.fyi/llms.txt
> Use this file to discover all available pages before exploring further.

# Googlecloudpubsub

> OpenTelemetry receiver for Googlecloudpubsub

# Googlecloudpubsub Receiver

![Status](https://img.shields.io/badge/status-beta-yellow)

**Available in:** `contrib`

**Maintainers:** [@alexvanboxel](https://github.com/alexvanboxel)

**Source:** [opentelemetry-collector-contrib](https://github.com/open-telemetry/opentelemetry-collector-contrib/tree/main/receiver/googlecloudpubsubreceiver)

## Supported Telemetry

![Logs](https://img.shields.io/badge/logs-beta-blue) ![Metrics](https://img.shields.io/badge/metrics-beta-green) ![Traces](https://img.shields.io/badge/traces-beta-orange)

## Overview

> ⚠️ This is a community-provided module. It has been developed and extensively tested at Collibra, but it is not officially supported by GCP.

The following configuration options are supported:

* `project` (Optional): The Google Cloud Project of the client connects to.
* `subscription` (Required): The subscription name to receive OTLP data from. The subscription name should be a
  fully qualified resource name (eg: `projects/otel-project/subscriptions/otlp`).
* `encoding` (Optional): The encoding that will be used to received data from the subscription. This can either be
  `otlp_proto_trace`, `otlp_proto_metric`, `otlp_proto_log` or and encoding extension (see `encoding`).  This will only
  be used as a fallback, when no `content-type` attribute is present.
* `compression` (Optional): The compression that will be used on received data from the subscription. When set it can
  only be `gzip`. This will only be used as a fallback, when no `content-encoding` attribute is present.
* `endpoint` (Optional): Override the default Pubsub Endpoint, useful when connecting to the PubSub emulator instance
  or switching between [global and regional service endpoints](https://cloud.google.com/pubsub/docs/reference/service_apis_overview#service_endpoints).
* `insecure` (Optional): allows performing “insecure” SSL connections and transfers, useful when connecting to a local
  emulator instance. Only has effect if Endpoint is not ""
* `ignore_encoding_error` (Optional): Ignore errors when the configured encoder fails to decoding a PubSub messages.
  It's advised to set this to `true` when using a custom encoder, and use `receiver.googlecloudpubsub.encoding_error`
  metric to monitor the number of errors. Ignoring the error will cause the receiver to drop the message.
* `flow_control` (Optional): Allows to fine tune the flow control settings for the subscription stream. See
  [Flow control](#flow-control) for more details.

```yaml theme={null}
receivers:
  googlecloudpubsub:
    project: otel-project
    subscription: projects/otel-project/subscriptions/otlp-logs
```

## Encoding

The `encoding` options allows you to specify Encoding Extensions for decoding messages on the subscription. An
extension need to be configured in the `extensions` section, and added to pipeline in the collectors configuration file.

The following example shows how to use the text encoding extension for ingesting arbitrary text message on a
subscription, wrapping them in OTLP Log messages. Note that not all extensions support all signals.

```yaml theme={null}
extensions:
  text_encoding:
    encoding: utf8
    unmarshaling_separator: "\r?\n"

service:
  extensions: [text_encoding]
  pipelines:
    logs:
      receivers: [googlecloudpubsub]
      processors: []
      exporters: [debug]
```

The receiver also supports build in encodings for the native OTLP Protobuf encodings, without the need to specify an
Encoding Extensions.

| encoding            | description               |
| ------------------- | ------------------------- |
| otlp\_proto\_trace  | Decode OTLP trace message |
| otlp\_proto\_metric | Decode OTLP trace message |
| otlp\_proto\_log    | Decode OTLP trace message |

The build-in encoding `cloud_logging` and `raw_text` where removed since v0.132.0, use the encoding extensions
`googlecloudlogentry` and `text` encoding extension instead.

When no encoding is specified, the receiver will try to discover the type of the data by looking at the `ce-type` and
`content-type` attributes of the message. These message attributes are set by the `googlepubsubexporter`.

| ce-type                           | ce-datacontenttype   | encoding | description                |
| --------------------------------- | -------------------- | -------- | -------------------------- |
| org.opentelemetry.otlp.traces.v1  | application/protobuf |          | Decode OTLP trace message  |
| org.opentelemetry.otlp.metrics.v1 | application/protobuf |          | Decode OTLP metric message |
| org.opentelemetry.otlp.logs.v1    | application/protobuf |          | Decode OTLP log message    |

[Cloud Logging]: https://cloud.google.com/logging

[LogEntry]: https://cloud.google.com/logging/docs/reference/v2/rest/v2/LogEntry

[sink-docs]: https://cloud.google.com/logging/docs/export/configure_export_v2#creating_sink

## Pubsub subscription

The Google Cloud [Pubsub](https://cloud.google.com/pubsub) receiver doesn't automatically create subscriptions,
it expects the subscription to be created upfront. Security wise it's best to give the collector its own
service account and give the subscription `Pub/Sub Subscriber` permission.

The subscription should also be of delivery type `Pull`.

### Flow control

The flow control allows to fine tune the flow control settings for the subscription stream.

* `trigger_ack_batch_duration` (Optional): Part of the control loop, the time between each message
  acknowledge batch.
* `stream_ack_deadline` (Optional): The ack deadline to use for the stream. The minimum deadline you can specify
  is 10 seconds. The maximum deadline you can specify is 600 seconds (10 minutes).
* `max_outstanding_messages` (Optional): Flow control settings for the maximum number of outstanding messages. When
  there are max\_outstanding\_messages currently sent to the streaming pull client that have not yet been acked or
  nacked, the server stops sending more messages. The sending of messages resumes once the number of outstanding
  messages is less than this value. If the value is \<= 0, there is no limit to the number of outstanding messages.
* `max_outstanding_bytes` (Optional): Flow control settings for the maximum number of outstanding bytes. When there
  are max\_outstanding\_bytes or more worth of messages currently sent to the streaming pull client that have not yet
  been acked or nacked, the server will stop sending more messages. The sending of messages resumes once the number
  of outstanding bytes is less than this value. If the value is \<= 0, there is no limit to the number of outstanding
  bytes.

```yaml theme={null}
flow_control:
  trigger_ack_batch_duration: 1s
  stream_ack_deadline: 60s
  max_outstanding_messages: 1000000
  max_outstanding_bytes: 1000000
```

More details can be found at [Pub/Sub gRPC StreamingPullRequest](https://docs.cloud.google.com/pubsub/docs/reference/rpc/google.pubsub.v1#streamingpullrequest)

### Filtering

When the messages on the subscription are accompanied by the correct attributes and you only need a specific
type in your pipeline, the messages can be [filtered](https://cloud.google.com/pubsub/docs/filtering) on the
subscription saving on egress fees.

An example of filtering on trace message only:

```
attributes.ce-type = "org.opentelemetry.otlp.traces.v1"
AND
attributes.content-type = "application/protobuf"
```

## Configuration

### Example Configuration

```yaml theme={null}
googlecloudpubsub:
googlecloudpubsub/customname:
  project: my-project
  user_agent: opentelemetry-collector-contrib {{version}}
  timeout: 20s
  subscription: projects/my-project/subscriptions/otlp-subscription
googlecloudpubsub/sovereign:
  project: my-sovereign-project
  subscription: projects/my-sovereign-project/subscriptions/otlp-subscription
  universe_domain: apis.example.com
```

***

*Last generated: 2026-07-06*