Documentation Grafana Cloud Monitor applications Profiles Ingestion control

Cloud Profiles ingestion control

The Grafana Cloud Profiles ingestion control feature allows you to set a daily cap on the volume of profiling data ingested per stack. This helps you manage costs by rejecting data once the specified limit is reached—useful when trying to ensure more predictable billing.

How it works

If a limit is configured, your Grafana Cloud stack checks how many bytes of profiles have been ingested since the beginning of the current day, which begins at 00:00 UTC. After the limit is reached, your Grafana Cloud stack discards all the data it receives for the rest of the day. You aren’t billed for the discarded data. At the start of each new day, your Grafana Cloud stack begins accepting profiling data again, regardless of how much data was discarded the previous day.

When the daily ingestion limit is reached, your Grafana Cloud stack rejects additional requests with a custom HTTP status code, 422. The volume of discarded profiles data is tracked in the metric grafanacloud_profiles_instance_discarded_bytes_per_second{reason="ingest_limit_reached"}, which can be found in your grafanacloud-usage Prometheus data source.

How to configure the limit

Authentication

All requests require a token with appropriate scopes:

Read access: profiles-config:read Write access: profiles-config:write

You can create new tokens in the Grafana Cloud > Security > Access Policies section. First, you need to create an access policy (if you still don’t have one) and then add a token.

You can find the user and the URL you need later in the Details section for Profiles in your instance.

It is the same you use for your SDK or Grafana Alloy configuration. Include your username and token using basic auth:

Copy

-u '<user>:<token>'      # this is how you do that with curl

View the existing configuration

We are going to show how to set a limit for a 24h period. To fetch the current configuration:

Copy

curl -s -u '<user>:<token>' \
  https://profiles-prod-008.grafana.net/api/v1/config-manager/ingestlimits/config

Sample response (if a limited is currently configured):

Copy

{
  "config": {
    "metadata": {
      "generation": "2",
      "timestamp": "1758202785"
    },
    "periodType": "PERIOD_TYPE_DAY",
    "periodLimitMb": "10240",
    "usageGroups": []
  }
}

Sample response (if no limit is currently configured):

Copy

{
  "config": {
    "metadata": {
      "generation": "5",
      "timestamp": "1759394587"
    },
    "periodType": "PERIOD_TYPE_DAY",
    "periodLimitMb": "0",
    "usageGroups": []
  }
}

Update the existing configuration

To update the configuration, include the latest metadata.generation returned from the GET response to prevent conflicts.

Copy

curl -s -u '<user>:<token>' -d '{"metadata": {"generation":"3","timestamp":"1758202785"},"periodType": "PERIOD_TYPE_DAY","periodLimitMb":"20480","usageGroups": []}' https://profiles-prod-001.grafana.net/api/v1/config-manager/ingestlimits/config

You can also use usageGroup configuration as shown below:

Copy

curl -s -u '<user>:<token>' -d '{
  "metadata": {
    "generation": "3"
  },
  "periodType": "PERIOD_TYPE_DAY",
  "periodLimitMb": "20480",
  "usageGroups": [
    {
      "usageGroup": {
        "name": "cart-service",
        "labelSelector": "{service_name="cart-service"}"
      },
      "periodLimitMb": "512"
    },
    {
      "usageGroup": {
        "name": "order-service",
        "labelSelector": "{service_name="order-service"}"
      },
      "periodLimitMb": "64"
    }
  ]
}' https://profiles-prod-008.grafana.net/api/v1/config-manager/ingestlimits/config

Remove the limit

To remove the limit entirely, set the periodLimitMb parameter to “0”.

Copy

curl -s -u '<user>:<token>' -d '{"metadata":{"generation":"<generation>"},"periodType":"PERIOD_TYPE_UNSPECIFIED","periodLimitMb":"0","usageGroups":[]}' <url>/api/v1/config-manager/ingestlimits/config

Notes

• All numeric values (like limits) have to be provided as strings.
• The metadata.generation field must match the current value to avoid update conflicts.
• labelSelector uses PromQL-style matching to apply limits to services.

The limit takes effect within 1-3 minutes.

Metrics and monitoring

When a limit is set, you can monitor the following metrics in your Grafana Cloud stack to understand the configured limit and track your usage relative to it. The metrics can be found in your grafanacloud-usage Prometheus data source:

• grafanacloud_profiles_instance_ingest_limit_megabytes: The configured ingest limit, in megabytes.

• grafanacloud_profiles_instance_period_ingested_megabytes: The ingested volume in megabytes within the current period (since the start of the day).

• grafanacloud_profiles_instance_discarded_bytes_per_second{reason="ingest_limit_reached"}: The rate, in bytes per second, at which profiling data is being discarded, due to having exceeded the ingestion limit. This value is zero if the limit has not been reached and no profiling data is being discarded.

Usage Insights dashboard

Instead of querying the monitoring metrics directly, you can use Grafana Cloud’s pre-built dashboard to visualize them. To access it, go to the GrafanaCloud folder and open the dashboard titled Usage Insights - 7 - Profiles Ingestion.

The panels in the Ingest Limits row show the configured limit, as well as the volume of profiles ingested in the current period. This helps you understand how close you are to the limit.

Troubleshooting

If you’re experiencing issues with ingestion control:

1. Verify you have a Grafana Admin role. Without this, you cannot view or set a profiles ingestion limit.
2. Check that the limit was applied by looking at the grafanacloud_profiles_instance_ingest_limit_megabytes metric
3. If data is still being ingested after reaching the limit, check the grafanacloud_profiles_instance_discarded_bytes_per_second metric to confirm if the limit is being enforced
4. Contact Grafana Support if the issue persists