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
ListTracesAPI calls per 60 seconds. - Make 10
ListTracesAPI calls and 50GetTraceAPI 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 views100 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.