metrics/gcp: docs say roles/monitoring.metricWriter but the endpoint is telemetry.googleapis.com, whose reference mandates roles/telemetry.writer

Follow-up to #4112 (point 3 of the closing comment) — the question that closed unanswered. Filing with what I've since checked.

Summary

The gcp exporter's package doc and README both instruct the user to grant roles/monitoring.metricWriter. The exporter dials telemetry.googleapis.com:443, and that API's own reference mandates roles/telemetry.writer plus roles/serviceusage.serviceUsageConsumer on the quota project. One of the two is wrong, and a user following the wrong one gets a permission failure at the point where it is least visible.

The two sources

GoFr — gcp.go, package doc:

On Cloud Run this authenticates via the attached service account (no key file). Grant that service account roles/monitoring.metricWriter.

and gcp.go:28:

defaultEndpoint = "telemetry.googleapis.com:443"

Google — the Telemetry API v1 metrics reference: to send telemetry data you grant Cloud Telemetry Writer (roles/telemetry.writer) on the project, and roles/serviceusage.serviceUsageConsumer on the quota project.

What the permission lists say

Comparing by permission rather than by name (predefined role names are not reliable indicators of what they confer):

roles/monitoring.metricWriter
  monitoring.metricDescriptors.create
  monitoring.metricDescriptors.get
  monitoring.metricDescriptors.list
  monitoring.monitoredResourceDescriptors.get
  monitoring.monitoredResourceDescriptors.list
  monitoring.timeSeries.create

roles/telemetry.writer
  logging.logEntries.create
  monitoring.timeSeries.create
  telemetry.traces.write

They overlap on exactly monitoring.timeSeries.create, so if that is the permission the endpoint enforces, both roles happen to work. monitoring.metricWriter's extra metricDescriptors.create buys nothing for this path — descriptors for prometheus.googleapis.com/<name>/<kind> on prometheus_target are created service-side by GMP.

Why the docs still need to agree

• The quota project grant is only on one side. roles/serviceusage.serviceUsageConsumer is documented as required for this endpoint and is not implied by either metric role. A user following the README grants monitoring.metricWriter alone and may still be denied, with the README giving no hint why.
• telemetry.writer is not a superset either — it lacks the descriptor permissions, so the two are not interchangeable in general.
• The failure surfaces as a gRPC PermissionDenied on a background push, which is the least observable place for it.

I have not made an authenticated call against telemetry.googleapis.com to settle which check actually fires — that would be the definitive test and I'd expect you're better placed to run it. Everything above is from the two documents and from gcloud iam roles describe.

Suggested fix

Whichever way the live check resolves, align gcp.go's package doc and the README with it, and mention the serviceusage.serviceUsageConsumer requirement on the quota project if it applies. If both roles genuinely work, saying so (and why) is more useful than naming one.

Environment

• gofr.dev/pkg/gofr/metrics/exporters/gcp v0.1.0, gofr.dev v1.60.0