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

# Google Cloud PubSub

<Badge className="hny-badge-enterprise-addon" stroke>Ent+</Badge>

<Note>
  This feature is available as an add-on for the [Honeycomb Enterprise plan](https://www.honeycomb.io/pricing/).
  Please contact your Honeycomb account team for details.
</Note>

## Description

Read messages from a Google Cloud PubSub topic and generate logs, metrics, or traces from the result.

<Warning>
  The OpenTelemetry receiver this source uses is in beta and is subject to change.
</Warning>

## Supported Platforms

| Platform | Supported |
| -------- | --------- |
| Linux    | ✓         |
| Windows  | ✓         |
| macOS    | ✓         |

## Configuration

<table><thead><tr><th>Field</th><th>Description</th></tr></thead><tbody><tr><td>Telemetry Types</td><td>The types of telemetry to read from PubSub.</td></tr><tr><td>Project ID</td><td>The Google Cloud project ID where the PubSub client will connect to.</td></tr><tr><td>Subscription Name</td><td>Name of the pre-existing PubSub subscription to read messages from.</td></tr><tr><td>Payload Encoding</td><td>Use "none" for attribute based detection. If the "content-type" attribute is missing from data, this is used to determine the encoding. Metrics and traces can only be OTLP Proto. See <a href="#attribute-labels">Attribute Labels</a> for more information.</td></tr><tr><td>Payload Compression</td><td>Use "none" for attribute based detection. If the "content-encoding" attribute is missing from data, this is used to determine the compression. See <a href="#attribute-labels">Attribute Labels</a> for more information.</td></tr><tr><td>Client ID</td><td>The client ID to be used by PubSub to make load balancing decisions.</td></tr><tr><td>User Agent</td><td>The user agent that will be used by the PubSub client to connect to the service.</td></tr><tr><td>Timeout</td><td>Timeout for all API calls, default is 12 seconds if unset.</td></tr><tr><td>Endpoint</td><td>Override of the default PubSub endpoint. Leave empty for default.</td></tr><tr><td>Insecure</td><td>If using a custom endpoint, determines if connection should be insecure.</td></tr></tbody></table>

### Authentication

The service account used by the collector should have the `Pub/Sub Subscriber` permission to read from the subscription. Additionally, make sure the subscription channel being read from is configured with `Pull` delivery.

Authentication is handled via the `GOOGLE_APPLICATION_CREDENTIALS` environment variable. This should point to a file containing the service account key for the project.

To set this for the collector, you need to modify the service file depending on your OS.

### Linux

Use a [Systemd override](https://wiki.archlinux.org/title/systemd):

```bash theme={}
sudo systemctl edit observiq-otel-collector
```

Then run the following command to reload the systemd configuration:

```bash theme={}
sudo systemctl daemon-reload
sudo systemctl restart observiq-otel-collector
```

### Windows

Start powershell as administrator and run the following command:

```powershell theme={}
reg add "HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Services\observiq-otel-collector" /v Environment /t REG_MULTI_SZ /d "GOOGLE_APPLICATION_CREDENTIALS=<path to key file>" /f
```

Then restart the collector service:

```powershell theme={}
Restart-Service observiq-otel-collector
```

### macOS

Add `GOOGLE_APPLICATION_CREDENTIALS` to the `EnvironmentVariables` dict in the launchd service file `/Library/LaunchDaemons/com.observiq.collector.plist` (other values are shown for context):

```xml theme={}
<key>EnvironmentVariables</key>
<dict>
    <key>GOOGLE_APPLICATION_CREDENTIALS</key>
    <string><path to key file></string>
    <key>OIQ_OTEL_COLLECTOR_HOME</key>
    <string>/opt/observiq-otel-collector/</string>
    <key>OIQ_OTEL_COLLECTOR_STORAGE</key>
    <string>/opt/observiq-otel-collector/storage</string>
</dict>
```

Then restart the collector:

```bash theme={}
sudo launchctl unload /Library/LaunchDaemons/com.observiq.collector.plist
sudo launchctl load /Library/LaunchDaemons/com.observiq.collector.plist
```

### Attribute Labels

The Google Cloud PubSub receiver looks for the following attributes on the message to determine the message encoding and compression:

* `content-type` - How the message content should be interpreted.
  * If this value is set to `application/protobuf`, another attribute, `ce-type`, is expected to determine telemetry type. This attribute should be one of `org.opentelemetry.otlp.traces.v1`, `org.opentelemetry.otlp.metrics.v1`, or `org.opentelemetry.otlp.logs.v1`.
* `content-encoding` - Despite being called the "content-encoding" this controls the compression of the message.

If these attributes are present on the message data, the `Payload Encoding` and `Payload Compression` source parameters are ignored and should be set to "none".

If these attributes are not present on the message data, the receiver will use the `Payload Encoding` and `Payload Compression` parameters to determine the encoding and compression.

Metrics and traces can only be OTLP Proto. Logs can be OTLP JSON, OTLP Proto, or Raw Text. For more information, see the [OpenTelemetry Receiver Documentation](https://github.com/open-telemetry/opentelemetry-collector-contrib/tree/main/receiver/googlecloudpubsubreceiver#encoding).

### Example Configuration

In this example, we are parsing log data from the given PubSub subscription. The expected attributes are not present on the PubSub message data, so the `Payload Encoding` and `Payload Compression` parameters are used to determine the encoding and compression.

If these attributes were present, then the `Payload Encoding` and `Payload Compression` parameters should be set to "none".

Standalone Source:

```yaml theme={}
apiVersion: bindplane.observiq.com/v1
kind: Source
metadata:
  id: googlecloudpubsub
  name: googlecloudpubsub
spec:
  type: googlecloudpubsub
  parameters:
    - name: telemetry_types
      value: ['Logs']
    - name: project
      value: 'my_project_id'
    - name: subscription
      value: 'my_subscription_name'
    - name: encoding
      value: 'raw_text'
    - name: compression
      value: 'gzip'
```