metrics/gcp: docs say roles/monitoring.metricWriter but the endpoint is telemetry.googleapis.com, whose reference mandates roles/telemetry.writer
- Dominant language
- Go
- Stars
- 20.9k
- Forks
- 1.8k
- Avg merge
- 5d 18h
- Merged PRs (30d)
- 39
Description
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`:
```go
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//` 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
Contributor guide
Research direction
Start with the package documentation in gcp.go, the defaultEndpoint at gcp.go:28, and the README instructions. Compare the documented roles with the Telemetry API reference and, if available, verify the required permissions using an authenticated telemetry.googleapis.com call. Done means the package doc and README agree on the working role requirements, including the quota-project requirement if applicable.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- gcp, go
- Domain
- documentation, observability
- Issue type
- Documentation
- Difficulty
- 4/5
- Estimated time
- 3-5 days
- Activity status
- Active
- Clarity
- Mostly clear
- Newbie friendliness
- 48/100