Quotas and limits

Cloud Trace enforces two different types of quotas: a rate quota on your API requests and an ingestion quota on spans you send to Trace.

Trace API usage limits

API method Total quota units
300 per 60 seconds
4,800 per 60 seconds

1 Each API call consumes 1 quota unit.
2 Each API call consumes 25 quota units.

You have a total of 300 quota units per 60 seconds for the three API commands GetTrace, ListTraces, and ListSpan. Here are two different examples of how you could use all of the available quota units:

  • Make 12 ListTraces API calls per 60 seconds.
  • Make 10 ListTraces API calls and 50 GetTrace API calls per 60 seconds.

Additional restrictions and limits for the Cloud Trace API are:

Restrictions and limits Value
Maximum number of spans per GetTrace call 1,000
Maximum number of spans per PatchTraces call 25,000
Maximum number of traces per ListTraces call 1,000 in ROOTSPAN/Minimal view
100 in COMPLETE view
Maximum number of spans per trace 1,000
Maximum number of bytes per trace 50 MB
Maximum number of label/attributes per span 32
Size of key per label/attribute 128 bytes
Size of value per label/attribute 256 bytes

Request changes to Cloud Trace API quota

You can request higher or lower Cloud Trace API limits using the Google Cloud console:

  1. In the Quotas page of the Google Cloud console, use the checkboxes to select Cloud Trace API, and then click Edit quotas.

    If you get an error Edit is not allowed for this quota, you can contact Support to request changes to the quota. Note also that billing must be enabled on the Google Cloud project to click the checkboxes.

  2. In the Quota changes panel, select the service to expand the view and then fill in the New limit and Request description fields. Click Next.

  3. Complete the form in the Contact details panel.

  4. Click Submit request.

For more information, see View and manage quotas.

Trace daily span ingestion limit

Your daily trace span ingestion quota is determined by your billing account history and requests you have made for a quota increase. The table lists the range of quota allocations:

Category Quota units
Ingested spans 3,000,000 per day - 5,000,000,000 per day

How do quotas relate to pricing?

Cloud Trace pricing is based on Trace span ingestion and scanning. Latency data is packaged into a trace, which is composed of spans. The spans are ingested by the Cloud Trace backend which then makes the data available for real-time viewing and reporting in the Google Cloud console. When you view trace data, the stored spans are scanned as part of the retrieval process.

Daily span quotas define the limit on the number of spans that can be ingested prior to the API call failing with a resource exhausted error. API rate quotas define the limits on the rate of API calls that can be made prior to the API call failing with a resource exhausted error.

Each API call consumes API quota. Each write API call also consumes daily span ingestion quota. For example, if you need to patch 10,000 spans, you can:

  • Send one patchTraces request with the 10,000 spans.

  • Send 10,000 patchTraces requests each with 1 span, and distribute these over several minutes to avoid API quota limits.

The first approach uses 1 API quota unit and the second approach uses 10,000 API quota units. Both approaches use 10,000 daily span ingestion quota units. The price of the two approaches is the same because the price is determined by the number of spans ingested, not the number of API calls.

Trace retention periods

Category Retention period
Span data stored by Cloud Trace 30 days
Analysis reports 30 days

Managing your quota

To make sure that you don't run out of quota and lose observability into your apps' performance, periodically view your quota usage or create an alerting policy. For detailed information on monitoring your API requests and understanding their responses, see Monitoring your API usage.

  • To view your Cloud Trace API and your daily span ingestion quotas, see View and manage quotas.

  • To learn how to decrease your API quota units and your daily span ingestion quota units, see Capping usage.

  • To request an increase in your API quota units or your daily span ingestion quotas, see Request more quota

  • See Creating an over-quota alert for detailed information on creating alerting policies to monitor your Trace API quota and your rate trace span ingestion.