gofr-dev / gofr-dev/gofr

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

Open
#4,138 0 comments 0 reactions 0 assignees View on GitHub
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

Open the contributing 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.