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 quotas

The following table summarizes the quota units available for read and write operations, and the daily quota for ingesting spans. For example, you have a total of 300 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.
Category Total quota units
Read operations1 300 per 60 seconds
Write operations2 4,800 per 60 seconds
Ingested spans3 3,000,000 per day - 5,000,000,000 per day

1 Read operations include GetTrace, ListTraces, ListSpan. A call to ListTraces consumes 25 quota units. Calls to GetTrace consume ListSpan 1 quota unit.
2 Write operations include PatchTraces, BatchWrite, and CreateSpan. Each write operation consumes 1 quota unit.
3 Your daily trace span ingestion quota is determined by your billing account history and requests you have made for quota increases.

Trace limits

This section lists limits that apply when using the Cloud Trace API.

Limits for API methods

Limits for API methods 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 the ROOTSPAN and MINIMAL views
100 in the COMPLETE view

Limits on spans

Limits on spans Value
Maximum length of a span name 128 bytes
Maximum number of labels or attributes per span 32
Maximum size of key for a label or attribute 128 bytes
Maximum size of value for a label or attribute 256 bytes
Maximum number of events per span 128
Maximum past timestamp for a span to be ingested 14 days
Maximum future timestamp for a span to be ingested 3 days
Maximum past timestamp for event relative to span timestamp 365 days

You can annotate spans by creating an attributes object and attaching it to the Span object when you use Cloud Trace API v2 batchWrite. Similarly, you can annotate spans by creating a labels object and attaching it to the TraceSpan object when you use the Cloud Trace API v1 patchTraces method.

Limits on traces

Limits on traces Value
Maximum number of spans per trace 1,000
Maximum trace size 50 MB

Trace retention periods

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

Manage your quota

This section describes how to request a change in a quota and how to monitor your quota usage.

Request changes to Cloud Trace API quota

You can request higher or lower Cloud Trace API limits using the Google Cloud console. For more information, see View and manage 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.

Monitor you quota usage

To make sure that you don't run out of quota and lose observability into your apps' performance, ensure that you batch your updates and monitor your quota usage. For example, you might create an alerting policy that notifies you when your usage exceeds a threshold. 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.