Deploy the OpenTelemetry Collector on GCP Cloud Run

The OpenTelemetry Collector is the engine of the GCP integration: it pulls metrics from Cloud Monitoring, receives logs pushed from Pub/Sub, and exports both to SigNoz over OTLP. This guide deploys it as a Cloud Run service in your deployment project. This is step 3 of the GCP integration.

Cloud Run is optional. It's the quickest managed way to run the Collector, so these steps use it, but you can run the Collector on any compute you prefer (a Compute Engine VM, GKE, or an existing Kubernetes cluster). The Collector must be able to authenticate to the Monitoring API, for example via a service account with roles/monitoring.viewer. To collect logs, Pub/Sub must also be able to reach the Collector over HTTPS. If you use different compute, apply the config ideas below to your platform and skip the Cloud Run-specific commands.

Prerequisites

You have created the signoz-integration-collector service account and granted it roles/monitoring.viewer on your monitored projects.
You have connected your GCP account in SigNoz and noted your SigNoz Cloud region (from the Ingestion URL) and copied the Ingestion Key.
The Cloud Run Admin API and the Secret Manager API are enabled in your <deployment-project-id>.
The gcloud CLI is installed and authenticated, or use Cloud Shell.

<deployment-project-id> and <deployment-region> below are the Deployment Project ID and Deployment Region from the connection fields you entered when connecting the account.

Which Collector image to use

Deploy the otel/opentelemetry-collector-contrib image. It includes everything this integration uses:

the googlecloudmonitoring receiver, which pulls metrics from the Cloud Monitoring API
the googlecloudpubsubpush receiver, which accepts logs that Pub/Sub pushes to the Collector
the health_check extension used in the deployment below

Check the tags list for the latest version and use that tag (for example, otel/opentelemetry-collector-contrib:0.163.1) instead of latest, so deployments stay reproducible. Use 0.163.1 or later. Older versions don't include the googlecloudpubsubpush receiver that Collect logs needs. Note that these tags have no v prefix.

Step 1: Prepare the Collector configuration

Create a file named otel-collector-config.yaml. The starter below is complete except for the metrics you want. You fill those in next, in Collect metrics, so it's normal for the metrics_list to be a placeholder now. If you also want logs, Collect logs adds a logs receiver to this file later.

receivers:
  # Metrics: one block per monitored project.
  # See "Collect metrics" for the metrics_list per service.
  googlecloudmonitoring:
    project_id: "<monitored-project-id>"
    collection_interval: 300s
    metrics_list:
      - metric_name: "compute.googleapis.com/instance/cpu/utilization"
 
processors:
  batch:
    timeout: 10s
    send_batch_size: 1024
  memory_limiter:
    check_interval: 5s
    limit_percentage: 80
    spike_limit_percentage: 25
 
exporters:
  otlphttp:
    endpoint: "https://ingest.<region>.signoz.cloud:443"
    headers:
      "signoz-ingestion-key": "<ingestion-key>"
    tls:
      insecure: false
 
extensions:
  # Serves the port Cloud Run health-checks. See the note below.
  health_check:
    endpoint: 0.0.0.0:8080
    path: /healthz
 
service:
  extensions: [health_check]
  pipelines:
    metrics:
      receivers: [googlecloudmonitoring]
      processors: [memory_limiter, batch]
      exporters: [otlphttp]

Verify these values:

<region>: Your SigNoz Cloud region (for example, us, eu, or in). This is the region in the Ingestion URL shown on the SigNoz connection panel; use the region only, not the full URL.
<ingestion-key>: Your SigNoz ingestion key, copied from the connection panel.

Why the health_check extension is here. A metrics-only Collector only makes outbound calls, so nothing else listens on a port, and a Cloud Run service marks a revision ready only once the container accepts connections on --port. health_check provides that listener. Keep the extension's endpoint port and the Cloud Run --port the same (8080 here).

The /healthz path matters. With the default path /, the health endpoint would answer Pub/Sub log pushes with a success code, and Pub/Sub would drop those messages. On /healthz, a push sent before the logs receiver is ready gets an error, so Pub/Sub keeps it and retries.

When you add logs, the logs receiver takes over port 8080 and health_check moves to port 13133. See Collect logs.

A ready revision means the Collector started and its config parsed. It does not confirm metrics are flowing: a config that parses but names the wrong project_id, or a service account missing roles/monitoring.viewer on a monitored project, still reports healthy. Confirm collection in Collect metrics.

If you only want metrics and prefer no health endpoint, you can deploy to a Cloud Run worker pool instead, which needs no port listener. A worker pool has no URL, so Pub/Sub can't push logs to it. Use a Cloud Run service if you plan to collect logs.

Step 2: Store the config in Secret Manager

Rather than baking a custom image, keep your otel-collector-config.yaml in Secret Manager and run the stock otel/opentelemetry-collector-contrib image directly. Cloud Run injects the secret as an environment variable, and the Collector reads its config from that variable at startup. Your config (and the ingestion key inside it) stays out of any image.

Create the secret from your otel-collector-config.yaml, then grant the signoz-integration-collector service account permission to read it.

In the deployment project, go to Security > Secret Manager > + Create secret.
Set Name to signoz-integration-collector-config.
Under Secret value, choose Upload file and select your otel-collector-config.yaml (or paste its contents into the value box).
Click Create secret.
Open the new secret, go to the Permissions tab, and click Grant access.
In New principals, paste signoz-integration-collector@<deployment-project-id>.iam.gserviceaccount.com.
In Role, select Secret Manager > Secret Manager Secret Accessor, then click Save.

Create the secret:

gcloud secrets create signoz-integration-collector-config \
  --data-file=otel-collector-config.yaml \
  --project=<deployment-project-id>

Grant the service account read access:

gcloud secrets add-iam-policy-binding signoz-integration-collector-config \
  --member="serviceAccount:signoz-integration-collector@<deployment-project-id>.iam.gserviceaccount.com" \
  --role="roles/secretmanager.secretAccessor" \
  --project=<deployment-project-id>

When you change the config later, add a new secret version (gcloud secrets versions add signoz-integration-collector-config --data-file=otel-collector-config.yaml, or Add new version in the Console) and redeploy the service to pick it up.

Step 3: Deploy to Cloud Run

Deploy the stock otel/opentelemetry-collector-contrib image as a Cloud Run service. Attach the signoz-integration-collector service account, mount the config secret as the OTEL_CONFIG environment variable, and point the Collector at it with --config=env:OTEL_CONFIG.

In the deployment project, go to Cloud Run > Deploy container > Service.
Set the Container image URL to otel/opentelemetry-collector-contrib:<tag>, using a tag from the tags list (0.163.1 or later).
Set Region to your <deployment-region>.
Under Authentication, choose Require authentication (do not allow unauthenticated invocations).
Under Ingress control, choose Internal.
Expand Container(s), Volumes, Networking, Security:
- Container port: 8080.
- Resources: 2 vCPU, 4 GiB memory.
- Security > Service account: signoz-integration-collector@<deployment-project-id>.iam.gserviceaccount.com.
- Variables & Secrets > Reference a secret: select signoz-integration-collector-config, expose it as the environment variable OTEL_CONFIG, and use the latest version.
- Container > Container arguments: add --config=env:OTEL_CONFIG.
- Autoscaling: set both Minimum number of instances and Maximum number of instances to 1, so the Collector always runs and never scales to a second scraping replica.
- Billing: choose Instance-based billing so CPU stays allocated between requests. With the default request-based billing, the metrics receiver's polling loop is throttled while the instance is idle.
Click Create.

gcloud run deploy signoz-integration-collector \
  --image=otel/opentelemetry-collector-contrib:<tag> \
  --region=<deployment-region> \
  --project=<deployment-project-id> \
  --service-account=signoz-integration-collector@<deployment-project-id>.iam.gserviceaccount.com \
  --set-secrets=OTEL_CONFIG=signoz-integration-collector-config:latest \
  --args=--config=env:OTEL_CONFIG \
  --port=8080 \
  --ingress=internal \
  --no-allow-unauthenticated \
  --min-instances=1 \
  --max-instances=1 \
  --no-cpu-throttling \
  --cpu=2 \
  --memory=4Gi

Why these flags:

--ingress=internal and --no-allow-unauthenticated keep the Collector off the public internet. Pub/Sub push from the same project still reaches it, and only callers you allow can sign in.
--min-instances=1 keeps one instance warm, since scaling to zero pauses metric scrapes and delays pushed logs.
--no-cpu-throttling keeps CPU allocated between requests. Without it, Cloud Run throttles the idle instance and stalls the receiver's polling loop.
--max-instances=1 prevents extra replicas from scraping the same metrics and duplicating data points. Scale up (--cpu/--memory), not out.
--cpu=2 --memory=4Gi matches the ~$110/month cost estimate. Drop to --cpu=1 --memory=2Gi for low volumes; scale up on memory pressure or dropped data.

Step 4: Verify the Collector is running

In the Console, open Cloud Run > signoz-integration-collector > Logs.
Confirm the Collector started without configuration errors. Look for Everything is ready. Begin running and processing data.
If the revision fails to become ready, the most common cause is a port mismatch. Confirm that whatever listens on the Cloud Run container port (8080) is configured on that port: the health_check extension for a metrics-only Collector, or the googlecloudpubsubpush receiver once you add logs.

A running Collector is not yet a working one: it has nothing to pull until you give it a metrics_list, and it reports healthy either way. Continue to the next steps, which end with a check that data actually reaches SigNoz.

Next steps

Collect metrics: configure the googlecloudmonitoring receiver.
Collect logs: add the logs receiver, then create the Pub/Sub topic, push subscription, and log sinks.

After changing otel-collector-config.yaml, add a new secret version (step 2) and redeploy the service (step 3) to roll the new configuration out.

Get Help

If you need help with the steps in this topic, please reach out to us on SigNoz Community Slack. If you are a SigNoz Cloud user, please use in product chat support located at the bottom right corner of your SigNoz instance or contact us at cloud-support@signoz.io.