# Connections & Observability (/connectors/gcp-pub-sub/reference/connections-endpoint)



This reference documents the Pub/Sub connector's observability surface: the single **gRPC
connection endpoint** (the emulator listener), the **read-only management view** in the dashboard,
the **Prometheus metrics**, and the **audit events**. There is **no REST/JSON v1 endpoint** (gRPC
only) and no management REST API distinct from the broker's.

## Connection endpoints [#connection-endpoints]

| Endpoint                  | Default  | Transport                            | Who connects                                     | How                                       |
| ------------------------- | -------- | ------------------------------------ | ------------------------------------------------ | ----------------------------------------- |
| Pub/Sub emulator listener | `:8085`  | gRPC, **insecure** (no TLS, no auth) | unmodified Google Pub/Sub SDKs + `gcloud pubsub` | `export PUBSUB_EMULATOR_HOST=<host>:8085` |
| Native KubeMQ broker      | `:50000` | gRPC                                 | native cross-protocol consumers on `gcp.{t}`     | a KubeMQ SDK against `localhost:50000`    |
| KubeMQ REST               | `:9090`  | HTTP                                 | *not used by this connector (gRPC only)*         | —                                         |

### The emulator drop-in [#the-emulator-drop-in]

Setting `PUBSUB_EMULATOR_HOST` is the entire contract — every official client library and `gcloud`
honour it: when set, the SDK **clears credentials, skips Google auth, and dials insecure gRPC**,
exactly as against Google's local emulator.

```bash
export PUBSUB_EMULATOR_HOST=localhost:8085     # connector default port; SDK uses the insecure path
export PUBSUB_PROJECT_ID=my-project            # any id; the project segment is parsed but ignored
```

`gcloud` uses an explicit endpoint override instead of the env var:

```bash
gcloud config set api_endpoint_overrides/pubsub http://localhost:8085/
```

<Callout type="info">
  **`AdvertisedEndpoint` hint.** The cosmetic `CONNECTORS_GCP_ADVERTISED_ENDPOINT` config value
  (`host:port`) is what the dashboard shows in its `PUBSUB_EMULATOR_HOST` hint — it does **not** change
  the listen address. See [Configuration](/connectors/gcp-pub-sub/concepts/configuration).
</Callout>

### Security posture [#security-posture]

No authentication, no TLS — emulator mode by design. DoS guards (`MaxMessageBytes` /
`MaxInflightPerSubscription` / `MaxConcurrentPolls` / `MaxSeekReplay` / push backoff) stay active.
&#x2A;*Do not expose port 8085 to untrusted networks.** See
[Connectivity & Emulator Mode](/connectors/gcp-pub-sub/how-to/connectivity-and-emulator-mode).

## Prometheus metrics [#prometheus-metrics]

The connector registers these metrics; they are persisted (time-bucket history survives a restart)
like every other connector.

### Counters [#counters]

| Metric                             | Labels                           | Meaning                        |
| ---------------------------------- | -------------------------------- | ------------------------------ |
| `kubemq_gcp_operations_total`      | `service`, `operation`, `status` | RPCs, by service / op / status |
| `kubemq_gcp_push_deliveries_total` | `result`                         | push deliveries, by result     |

### Histogram [#histogram]

| Metric                                  | Labels                 | Meaning               |
| --------------------------------------- | ---------------------- | --------------------- |
| `kubemq_gcp_operation_duration_seconds` | `service`, `operation` | per-operation latency |

### Gauges [#gauges]

| Metric                              | Meaning                                 |
| ----------------------------------- | --------------------------------------- |
| `kubemq_gcp_topics`                 | registered topics                       |
| `kubemq_gcp_subscriptions`          | registered subscriptions                |
| `kubemq_gcp_snapshots`              | registered snapshots                    |
| `kubemq_gcp_schemas`                | registered schemas                      |
| `kubemq_gcp_inflight_messages`      | leased (received-but-un-acked) messages |
| `kubemq_gcp_streaming_pull_streams` | open StreamingPull streams              |

The gauge reporter refreshes every 5 s — one of the connector's three sweepers (lease 250 ms, gauges
5 s, snapshot expiry hourly).

<Callout type="info">
  There is **no Cloud Monitoring (Stackdriver) metrics emulation** — Prometheus is the metrics
  surface.
</Callout>

## Dashboard [#dashboard]

The KubeMQ web dashboard has a **Google Cloud Pub/Sub** page (route `/gcp`, in the Connectors group): summary
cards; topics / subscriptions / snapshots / schemas tables; topic and subscription detail panels; an
overview throughput chart; a resource gauge chart (topics / subscriptions / pull / push / inflight);
and an operations table plus a per-operation chart. The operation key is the bare method name (e.g.
`Publish`). A settings page edits the connector config and shows the `PUBSUB_EMULATOR_HOST` hint
(from `AdvertisedEndpoint`).

## Audit events [#audit-events]

Every broker-facing client the connector mints is branded with a `gcp.` prefix, so its connections
are identifiable as Pub/Sub traffic in the dashboard, metrics, and audit log. Control-plane
operations are audited (data-plane publishes / pulls / acks are **not**):

| Event area                  | When                                                  |
| --------------------------- | ----------------------------------------------------- |
| topic lifecycle             | create / delete (tombstone) / update                  |
| subscription lifecycle      | create / update / detach / delete                     |
| snapshot & schema lifecycle | create / commit / rollback / delete                   |
| registry conflict           | a registry-sync conflict resolved by last-writer-wins |

## Cluster notes [#cluster-notes]

Topic / subscription / snapshot / schema records live in a **per-node replicated registry**
synchronized across cluster nodes with a last-writer-wins rule. **Message data itself is not
replicated by the connector** — it rides the existing Events Store / Queues replication. **Leases and
exactly-once are node-local** (gotcha #1) — see
[Error Codes](/connectors/gcp-pub-sub/reference/error-codes) and
[Migrating from Google Cloud Pub/Sub](/connectors/gcp-pub-sub/reference/migration-from-gcp).

## Related [#related]

<Cards>
  <Card title="Connectivity & Emulator Mode" href="/connectors/gcp-pub-sub/how-to/connectivity-and-emulator-mode" description="The PUBSUB_EMULATOR_HOST drop-in, the insecure-gRPC posture, and the sticky-stream caveat." />

  <Card title="Configuration" href="/connectors/gcp-pub-sub/concepts/configuration" description="The CONNECTORS_GCP_* settings behind the port, the advertised endpoint, and the DoS guards." />

  <Card title="Capabilities" href="/connectors/gcp-pub-sub/reference/capabilities" description="Supported RPCs and why there is no REST/JSON v1 endpoint." />

  <Card title="Reliability" href="/connectors/gcp-pub-sub/how-to/reliability" description="Dead-letter, retry, exactly-once, and the node-local lease semantics behind the gauges." />
</Cards>