Connecting Grafana Cloud to CostReveal, setup guide

Grafana Cloud bills your organization once a month for logs, metrics, traces and users, and the invoice says nothing about which stack, or which team running it, used what. This guide covers how CostReveal reads what Grafana bills, how each product's bill is divided among your stacks by their usage, each setup step, how stack labels explain spend, and what to expect from a monthly billing rhythm.

What the Grafana Cloud connection reads

CostReveal reads what Grafana bills your organization each month, product by product, such as logs, metrics and users:

• Billed usage: each product's amount due for a month, once Grafana bills it on the 1st of the next. These are invoiced figures.
• Stacks: each product's amount is divided among the stacks that used it, by each one's usage, exactly, so the parts add up to the bill. Your included usage belongs to the organization, so it is shared the same way. Each stack is an account in CostReveal.
• Stack labels, read with your project's tag keys.

A monthly rhythm

Grafana bills a month on the 1st of the next, so the month in progress has no figures until Grafana bills it. That is a property of how Grafana states costs, not a delay in CostReveal: each month appears whole, as invoiced, once it closes.

What you need

• Access to your Grafana Cloud organization's Administration, to create an access policy and token.
• An owner or admin role in CostReveal.

Step by step setup

1. Start the connection

In CostReveal, go to Connections and choose Connect next to Grafana.

2. Create an access policy and token

In Grafana Cloud, under Administration, Cloud access policies, create a policy for all stacks with two scopes:

• billing-metrics:read, to read what each product was billed.
• orgs:read, to read the organization and its stacks.

Then create a token for that policy.

3. Enter the details and verify

Enter your organization's slug, as grafana.com/orgs/<slug> shows it, and the token, then choose Verify and connect. Only the format is checked as you type. When you verify, CostReveal reads the organization and its last billed month before saving anything. If something is wrong, it says which: an organization it cannot find, a token Grafana does not take, or a token without the billing scope.

The token is stored encrypted and never shown again. Deleting the access policy in Grafana Cloud ends access at once.

Freshness and history

Grafana bills each month on the 1st of the next, so CostReveal reads once a day. The first read brings in the billed months among the twelve before the current one, as far as Grafana holds them. Where Grafana holds no older months, Connections says how far back it reached, and each read asks again. After that, each read covers the current and previous month.

Connection states

Under Connections, the connection is always in one of four states:

• Setup not finished: the details have not been verified yet.
• Waiting for first data: the token was verified, and no billed month has been read yet.
• Connected: billed usage was read and the latest read succeeded.
• Needs attention: the latest read failed, for example because the access policy was deleted. Everything already read is kept.

How Grafana Cloud spend is explained

• Direct: the service, the Grafana product, which Grafana bills itself.
• Inferred: the team, feature and customer, when a stack label names them, read with the project's tag keys. A stack labelled team = search is the search team's.
• Allocated: a share of a cost an allocation rule divides, by fixed percentages, evenly, or in proportion to what each owner already explains.
• Unknown: spend no label or rule explains. It is shown as unknown, never spread across teams.

Stack names never explain spend on their own: a stack called search-prod is not the search team's until a label or a rule says so. Because each stack is an account, an allocation rule on the account can name the owner of a stack that has no labels.

How figures are checked

Every amount is recorded as Grafana bills it. A change to a month already read is recorded as a correction that keeps what was said before, and attribution runs again. Each product's amount is divided among stacks exactly, so the stack figures add up to the bill, and attribution on every dimension must add up exactly to the ledger.

Grafana states billed usage in this one source, so there is no second source to compare the total against. Home says the figures tie out with no second source named.

Getting more of Grafana spend explained

1. Label each stack with a key the project reads, such as team.
2. Write a rule per stack that belongs to one team and has no labels, on its account.
3. Split a shared stack with a rule, so shared observability is allocated in the open.
4. Compare months in Explore by product and stack, to see which product moved.

Troubleshooting

• Verify cannot find the organization. Use the slug exactly as grafana.com/orgs/<slug> shows it.
• Verify says the token lacks the billing scope. Check the access policy has billing-metrics:read and orgs:read, and applies to all stacks.
• No figures for this month. Grafana bills a month on the 1st of the next; the month appears then.
• A stack is unknown. Add a label with a key the project reads, or a rule on its account.

Using Grafana Cloud figures in CostReveal

Once Grafana Cloud spend is read, it appears everywhere the rest of your spend does:

• Explore groups it by provider, service, account, region, team, feature, customer or any custom dimension you define, and can filter to any of them. Every row shows how much of it is direct, inferred, allocated or unknown.
• Budgets can be set on Grafana Cloud as a provider, or on any one of its services, with alerts when a billed month nears or passes the limit.
• Insights has no daily forecast or anomalies for Grafana Cloud: it bills a whole month on the 1st of the next, so its spend arrives a month at a time.
• Reports export the figures as CSV or a PDF, once or on a weekly or monthly schedule.
• A worked example. Suppose each stack carries a team label. When a month is billed, Explore by team then by service shows each team's share of logs, metrics and users, inferred from the labels, and comparing it with the month before shows which product moved.

Security and access

• What CostReveal holds. The access policy token. It is encrypted with AES-256-GCM before it is stored, under keys that can be rotated, and it is never shown again after you enter it.
• What it is used for. Reading only. CostReveal never changes anything in your account.
• Who can change the connection. Only owners and admins in CostReveal can connect, change or remove a connection, and each of those actions is recorded in the organization's audit log, with who did it and when.
• Isolation. Every figure is stored in CostReveal's database with your organization isolated by PostgreSQL row level security, enforced in the database itself, below the application.
• Ending access. Delete the access policy in Grafana Cloud. CostReveal keeps every figure already read and says that new data has stopped.

Removing the connection

Removing the connection under Connections deletes every figure it brought in from the project. Delete the access policy in Grafana Cloud too. To stop reading without removing anything, delete the access policy: CostReveal keeps every figure already read and tells you new data has stopped.

Frequently asked questions

Why is there nothing for the current month? Grafana bills each month on the 1st of the next. CostReveal shows each month as invoiced once Grafana bills it.

How is a product's bill split among stacks? Each product's amount is divided among the stacks that used it, by each one's usage, exactly, so the parts add up to the bill. Included usage is shared the same way.

Which scopes does the token need? billing-metrics:read and orgs:read, on a policy for all stacks.

How often does CostReveal read Grafana? Once a day, since Grafana bills once a month.

Is Grafana spend checked against another total? No. Grafana states billed usage in one source, so CostReveal checks that attribution adds up exactly to the bill, and says no second source is named.

Do stack names count as owners? No. Owners come from stack labels or allocation rules, never from names.

Keep reading

• Connecting Datadog to CostReveal: costs by organization and product, with cost attribution by tag.
• Connecting New Relic to CostReveal: consumption priced at your contract rates.
• Connect Grafana Cloud in the docs: the reference for every setup step.