> For the complete documentation index, see [llms.txt](https://docs.groundcover.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.groundcover.com/use-groundcover/storage-management.md).
# Storage Management
Storage Management lets you control how long **traces**, **logs**, and **events** are kept in groundcover, and optionally when data moves to lower-cost cold storage. Policies are configured per **backend** from the groundcover app.
Because retention directly affects investigations, compliance, and cost, review the examples below before saving changes.
{% hint style="info" %}
Storage management is part of groundcover settings and can only be accessed by account admins
{% endhint %}
{% hint style="info" %}
Self serve storage management is in gradual rollout. For earlier access, please contact the groundcover team
{% endhint %}
### Where to find it
Open **Settings → Storage Management** ([`/settings/storage-management`](https://app.groundcover.com/settings/storage-management)).
The page has the following tabs:
| Tab | What you configure |
| ------------------ | -------------------------------------------------- |
| **Traces** | Default retention, cold storage, and trace indexes |
| **Logs** | Default retention, cold storage, and log indexes |
| **Events** | Default retention, cold storage, and event indexes |
| **APM** | Default retention and cold storage |
| **Monitor Issues** | Default retention |
{% hint style="info" %}
Metrics retention is currently **not** managed from this page. Reach out to the groundcover team to change the metrics retention period.
{% endhint %}
### Updating the storage management policy
Except for APM and monitor issues, each tab is split into two sections.
#### 1. Default settings
| Field | Meaning |
| ------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Default retention** | How long data is kept before deletion if no index matches. |
| **Move to cold storage** | Optional. How long data stays in hot storage before moving to lower-cost storage (queries may be slower). Requires a custom duration; the destination is currently fixed to the `cold` volume. |
Cold storage applies at the **default policy** level. Per-index cold storage is not supported in the current release.
#### 2. Indexes
Indexes serve two purposes:
1. **Query performance** — tagged data can be routed into dedicated storage tiers.
2. **Custom retention** — subsets of data can be kept longer or shorter than the default.
Each index has:
| Field | Description |
| -------------------- | ----------------------------------------------------------------------------------------------------------- |
| **Name** | Letters, numbers, underscores, and hyphens only (e.g. `prod-errors`, `billing-data`). |
| **Query filter** | A **gcQL** filter selecting which records belong to this index. |
| **Retention period** | Set a **custom retention period** (e.g. 90d) or keep as Default to align with the default retention policy. |
{% hint style="info" %}
A policy can have up to 20 indexes in total. Deleted index will be accounted as part of this limit.
{% endhint %}
### Editing a policy
Users can edit the policy of one data type at a time. In case there are unsaved changes, the users will be prompted upon attempt to navigate to another page.
Changes will only apply after the user has reviewed the changes and then applied them. The Review Changes screen will show the list of changes for the user to apply.
Applying these changes is guaranteed to apply for new data only. In some cases, changes will apply retroactively as well.
In case an index was deleted, it will not impact existing entries, only new ones.
Consider the following example:
**Logs tab**
* Default retention: `7d`
* Single index - `level:error` → `30d` retention
An entry was created with `level:error` and will be kept for 30 days.
If the index is deleted, existing entries with `level:error` will be kept for 30 days, while new ones will be retained for 7 days.
### How overlap is resolved
In case of multiple index filters matching a single row line, one index and retention policy will be chosen. Rules are evaluated **top to bottom**. The first index whose gcQL filter matches the record wins.
### Examples
#### Example 1 — Default only
**Traces tab**
* Default retention: `14d`
* Cold storage
* No indexes
| Trace | Result |
| --------- | ------------------------- |
| Any trace | Deleted after **14 days** |
| | |
***
#### Example 2 — Single Index
**Logs tab**
* Default retention: `7d`
* Indexes:
| Order | Name | Query filter | Retention |
| ----- | ----------- | -------------- | --------- |
| 1 | `prod-logs` | `cluster:prod` | `30d` |
| Log | Matches | Retention |
| -------------------------------- | ----------- | ---------------- |
| `cluster=prod`, `level=info` | `prod-logs` | **30d** |
| `cluster=staging`, `level=error` | *(none)* | **7d** (default) |
The first log matched the single index and hence the retention period was set accordingly.
***
#### Example 3 — Overlapping indexes: order matters
**Goal:** Keep all production logs for 30 days, but keep production **error** logs for 90 days.
**Wrong order** (broad rule first):
| Order | Name | Query filter | Retention |
| ----- | ------------- | -------------------------- | --------- |
| 1 | `prod-all` | `cluster:prod` | `30d` |
| 2 | `prod-errors` | `cluster:prod level:error` | `90d` |
**Log:** `cluster=prod`, `level=error`
* **30d** — `prod-all` wins because it is first.
**Correct order** (narrow rule first):
| Order | Name | Query filter | Retention |
| ----- | ------------- | -------------------------- | --------- |
| 1 | `prod-errors` | `cluster:prod level:error` | `90d` |
| 2 | `prod-all` | `cluster:prod` | `30d` |
Same log → matches `prod-errors` first → **90d**.
***
### Monitoring the changes
Once an index tier was added, it will be added an attribute to the relevant data type.
For example, if a user defined the `prod-all` index tier for traces, then all traces which match this rule from the moment the rule was saved will have that attribute on it.
---
# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.
## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:
```
GET https://docs.groundcover.com/use-groundcover/storage-management.md?ask=&goal=
```
`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.