Documentation Grafana Cloud Observe and act Optimize data Adaptive Logs Archive logs

Archive logs

Keep the logs you might need later without storing them in Grafana Cloud Logs. Archive logs copies the log streams you choose to a bucket in your own cloud account. You can then drop those streams from Grafana Cloud Logs and still have every line for compliance, audit, or a later investigation.

You own the bucket and decide how long it keeps your logs. You can query the archive in place with tools such as Amazon Athena, DuckDB, or BigQuery. To set it up, you configure a bucket once, point one or more archive rules at it, and Adaptive Logs writes matching streams to that bucket.

When to use Archive logs

Archive logs is for teams that want to store less in Grafana Cloud Logs without losing logs they might need later. A platform or observability team usually sets it up, often because a security, compliance, or audit team needs certain logs kept.

Use Archive logs when you want to:

• Drop a stream without losing it. You’re ready to stop storing a noisy stream in Cloud Logs, but you aren’t sure you’ll never need it. Create an archive rule with Drop these logs from live ingestion selected, and the stream goes to your bucket instead.
• Keep logs for compliance or audit. A regulation or auditor asks you to keep access or security logs for longer than you need them in Grafana. Keep a copy in your own bucket, under your own retention policy.
• Keep logs for a later investigation. You rarely query verbose debug logs, but you want them after an incident. Archive them, then read them from your bucket when you need them.
• Lower your storage costs. Move high-volume, low-value streams out of Cloud Logs. Archiving alone doesn’t reduce what’s written to Cloud Logs. You also need to drop the streams, which an archive rule can do for you. Refer to Stop sending archived logs to Cloud Logs.

How it works

Archiving has two parts:

• Archive destination: A connection to a bucket in your own cloud account. It stores the bucket name, region, optional path prefix, and any provider-specific settings.
• Archive rule: A named LogQL stream selector that picks which log streams go to a destination. A destination can have several rules.

When you save an archive rule, Adaptive Logs starts archiving matching streams. It doesn’t archive logs it received before then.

You can’t search archived logs in Grafana. To read them, use your cloud provider’s console or a query engine that reads your bucket. Refer to Find and query your archived logs.

Archiving matches whole streams, while drop rules work line by line. A matching stream is captured before drop rules and exemptions are checked, so every line is archived, including lines a drop rule removes. Exemptions don’t change what’s archived. If more than one rule matches a stream, the first match wins, so a stream goes to only one destination.

An archive rule can also stop the archived streams from being written to Cloud Logs. Its Drop these logs from live ingestion option creates a separate 100% drop rule on the same stream selector, which you manage on its own. Refer to Create an archive rule.

Manage access

Use role-based access control (RBAC) to manage who can configure archive destinations and archive rules.

Roles and permissions

Adaptive Logs provides dedicated roles for archiving. Assign these roles to users who need access to archive destinations and archive rules.

The standard Adaptive Logs Admin role also grants full access to archive destinations and archive rules.

To use Drop these logs from live ingestion when you create an archive rule, you also need permission to create drop rules. The archive roles don’t include it.

For details on how to assign roles, refer to Configure RBAC for Adaptive Logs.

Before you begin

To use Adaptive Logs archive, you need:

• A Cloud Logs instance you’re actively sending logs to.
• Permissions in your cloud account to create a bucket, or a container on Azure Blob Storage, and to grant Grafana access to it. On Google Cloud Storage, that includes creating a custom IAM role. Use the cloud provider and region that the wizard shows. To see them, open the Archives page and click Create archive destination. The Cloud provider step shows your provider, and your region when it knows it.
• The Archive Configuration Admin role to create destinations and the Archive Rules Editor role to create rules, or the Adaptive Logs Admin role. Refer to Manage access.

Configure your archive destination

The archive destination tells Adaptive Logs where to write your archived logs. It points at a bucket in your own cloud account.

Setting up a destination moves between the Create archive destination wizard in Adaptive Logs and your cloud provider’s console. Keep the wizard open while you work in your console, so you can copy what you need and return to finish.

The wizard has four steps: Cloud provider, Enter bucket details, Set up access, and Name and save. On Azure Blob Storage, the second step is Enter container details.

Follow the section for your cloud provider:

• Set up an Amazon S3 destination
• Set up a Google Cloud Storage destination
• Set up an Azure Blob Storage destination

Set up an Amazon S3 destination

Create an Amazon S3 bucket, give Grafana access with a bucket policy, and connect the bucket in the wizard.

1. In Grafana Cloud, navigate to Adaptive Telemetry, then select Adaptive Logs.

2. Open the Archives page, then click Create archive destination.

3. On Cloud provider, check that the provider is Amazon S3, or choose it if the wizard asks. Note the region.

4. In the AWS Management Console, create an Amazon S3 bucket in the region the wizard shows.

5. In the wizard, click Next.

6. On Enter bucket details, complete these fields, then click Next:

   • Bucket name: The exact name of your bucket as shown in your cloud console.
   • Path prefix (optional): A folder inside the bucket, for example, logs/. Leave it blank unless you want logs under a specific path. Grafana adds a tenant folder under this prefix.
   • Bucket region: If the wizard locks your provider, the region is shown read-only and you can’t change it later. Otherwise, choose the region where you created the bucket.
   • Archive path: Shown under the fields once you enter the bucket name. Check that it’s where you expect logs to go.

7. On Set up access, expand Set up your bucket. The instructions already include your bucket name and the Grafana principal.

8. Attach a bucket policy to your bucket. Choose Versioned bucket if you’ve enabled bucket versioning, or Non-versioned bucket if you haven’t. Copy that policy and attach it to your bucket.

9. Expand Upload the ownership marker. It shows the Ownership marker folder, the Ownership marker file name, and the Full path of ownership marker, each ready to copy.

10. Upload the ownership marker with the AWS CLI. Replace BUCKET_NAME with your bucket name, FULL_PATH_OF_OWNERSHIP_MARKER with the path from the wizard, and BUCKET_REGION with your bucket’s region:

    Bash Copy

    aws s3api put-object --bucket <BUCKET_NAME> --key "<FULL_PATH_OF_OWNERSHIP_MARKER>" --region <BUCKET_REGION>

    Without a --body, put-object creates an empty object. Don’t use aws s3 cp /dev/null, because the AWS CLI skips /dev/null and uploads nothing. To use the console instead, refer to Upload the marker from your console.

11. Click Check access. When all three checks pass, the wizard shows Access confirmed. Click Next.

12. Name and save the destination.

If a check fails, refer to Check access and fix failures.

Set up a Google Cloud Storage destination

Create a Cloud Storage bucket, give Grafana access with a custom IAM role, and connect the bucket in the wizard.

1. In Grafana Cloud, navigate to Adaptive Telemetry, then select Adaptive Logs.

2. Open the Archives page, then click Create archive destination.

3. On Cloud provider, check that the provider is Google Cloud Storage, or choose it if the wizard asks. Note the region.

4. In the Google Cloud console, create a Cloud Storage bucket in the region the wizard shows. Create it with uniform bucket-level access enabled.

5. In the wizard, click Next.

6. On Enter bucket details, complete these fields, then click Next:

   • Bucket name: The exact name of your bucket as shown in your cloud console.
   • Path prefix (optional): A folder inside the bucket, for example, logs/. Leave it blank unless you want logs under a specific path. Grafana adds a tenant folder under this prefix.
   • Archive path: Shown under the fields once you enter the bucket name. Check that it’s where you expect logs to go.

7. On Set up access, expand Set up your bucket.

8. Create a custom IAM role in the project that owns the bucket. The role needs these permissions:

   Expand table

   Permission	Used to
   storage.buckets.get	Read the bucket’s location to confirm it matches the region that Adaptive Logs expects
   storage.objects.get, storage.objects.create	Read and write archived logs, and check access during setup
   storage.objects.list	List archived logs so they can be read back

   The role can’t delete or change your data, change retention, or change IAM. Replace PROJECT_ID with your project ID:

   Bash Copy

   gcloud iam roles create grafanaArchiveWriter --project=<PROJECT_ID> \
     --title="Grafana Archive Writer" \
     --permissions=storage.buckets.get,storage.objects.get,storage.objects.create,storage.objects.list

   If you use a different role ID, use only letters, numbers, underscores, or periods, from 3 to 64 characters.

9. Grant the role to the Grafana service account on your bucket. Replace PROJECT_ID with your project ID:

   Bash Copy

   gcloud storage buckets add-iam-policy-binding gs://<BUCKET_NAME> \
     --member=serviceAccount:<GRAFANA_SERVICE_ACCOUNT> \
     --role=projects/<PROJECT_ID>/roles/grafanaArchiveWriter

   The instructions fill in BUCKET_NAME and GRAFANA_SERVICE_ACCOUNT for you. The wizard doesn’t collect your project ID, so replace PROJECT_ID in both commands yourself.

10. Expand Upload the ownership marker and copy the Full path of ownership marker.

11. Upload the ownership marker with the gcloud CLI. Replace BUCKET_NAME with your bucket name and FULL_PATH_OF_OWNERSHIP_MARKER with the path from the wizard:

    Bash Copy

    touch grafana-archive-ownership
    gcloud storage cp grafana-archive-ownership gs://<BUCKET_NAME>/<FULL_PATH_OF_OWNERSHIP_MARKER>

    To use the console instead, refer to Upload the marker from your console.

12. Click Check access. When all three checks pass, the wizard shows Access confirmed. Click Next.

13. Name and save the destination.

If a check fails, refer to Check access and fix failures.

Set up an Azure Blob Storage destination

Create a storage account and container, authorize Grafana, assign it a role, and connect the container in the wizard.

1. In Grafana Cloud, navigate to Adaptive Telemetry, then select Adaptive Logs.

2. Open the Archives page, then click Create archive destination.

3. On Cloud provider, check that the provider is Azure Blob Storage, or choose it if the wizard asks.

4. In the Azure portal, create a storage account with a container for block blobs.

5. In the wizard, click Next.

6. On Enter container details, complete these fields, then click Next:

   • Container name: The container Grafana writes logs into. This isn’t the storage account name.
   • Path prefix (optional): A folder inside the container, for example, logs/. Leave it blank unless you want logs under a specific path. Grafana adds a tenant folder under this prefix.
   • Azure tenant ID: Your directory tenant ID. Find it in Microsoft Entra ID under Overview as Directory (tenant) ID.
   • Storage account name: The name of your storage account, not the container.
   • Archive path: Shown under the fields once you enter the container name. Check that it’s where you expect logs to go.

7. On Set up access, expand Set up your container.

8. Authorize Grafana. Open the OAuth authorization URL shown in the instructions, which has the form:

   Copy

   https://login.microsoftonline.com/<YOUR_AZURE_TENANT_ID>/oauth2/authorize?client_id=<GRAFANA_APPLICATION_ID>&response_type=code&redirect_uri=https://grafana.com

   The instructions fill in YOUR_AZURE_TENANT_ID with the tenant ID you entered and GRAFANA_APPLICATION_ID with the Grafana application ID.

9. Grant Grafana access to the container with a role assignment for the Grafana application ID. Copy the ID from Grafana application ID in Set up your container. Adaptive Logs doesn’t generate a policy template for Azure, so assign this role yourself, on the container:

   Expand table

   Role	Covers
   Storage Blob Data Contributor	blobs/read, blobs/write

   Azure has no built-in role that grants read and write without delete. Grafana doesn’t delete objects; the extra permission is unused.

10. Expand Upload the ownership marker to see where to upload the marker.

11. Upload the ownership marker from the Azure portal. Refer to Upload the marker from your console.

12. Click Check access. When all three checks pass, the wizard shows Access confirmed. Click Next.

13. Name and save the destination.

If a check fails, refer to Check access and fix failures.

Check access and fix failures

When you click Check access, Adaptive Logs runs three checks in order and shows the result of each: Read access, Ownership marker, and Write access. The checks short-circuit, so at most one is reported as failed.

If Read access or Write access fails, Grant Grafana access appears under that check, and the Set up your bucket section opens. On Azure Blob Storage, the section is Set up your container. If you’ve closed the section, click its name in the message to open it again. Check the access you granted in your cloud console, then click Check access again.

If the Ownership marker check fails, the Upload the ownership marker section opens. Upload the marker, then click Check access again.

If Grafana can’t reach the bucket at all, Couldn’t reach this bucket appears instead (Couldn’t reach this container on Azure Blob Storage). Check the bucket name, and on Amazon S3 the region, then go back to Enter bucket details (Enter container details on Azure Blob Storage). For other settings problems, Validation failed appears. Go back to that step to fix them.

If you go Back from Set up access and return, validation resets and you have to click Check access again.

Understand the ownership marker

The ownership marker is an empty file that proves you control the bucket. It must exist before Grafana writes anything. You don’t need to run a check first. The Upload the ownership marker section on Set up access shows the Ownership marker folder, the Ownership marker file name, and the Full path of ownership marker, each ready to copy. The full path has the form:

Copy

[<path-prefix>/]tenant=<instance-id>/grafana-archive-ownership

Here, instance-id is the ID of your Cloud Logs instance. The wizard fills it in for you.

Checking access also uploads a small probe object to [<path-prefix>/]tenant=<instance-id>/grafana-archive-healthcheck/ to confirm write access. This probe isn’t removed automatically. You can delete it, or leave it for your bucket’s lifecycle policy to clean up.

Upload the marker from your console

If you don’t use a CLI, upload the marker from your cloud provider’s web console:

1. Create an empty local file named grafana-archive-ownership, with no file extension. For example, run touch grafana-archive-ownership.
2. In the console, open your bucket or container and create the folders shown in Ownership marker folder. That includes your path prefix, if you set one, and the tenant=<instance-id> folder. The Amazon S3, Google Cloud Storage, and Azure Blob Storage consoles all let you create folders as you navigate.
3. Upload the empty file into the tenant=<instance-id> folder. The console uses the local filename as the object name, so don’t rename the file.

Then click Check access.

Name and save the destination

After Access confirmed, finish the wizard.

1. On Name and save, review the summary of the destination, then complete:

   • Destination name (required): A descriptive name for the destination, for example, compliance-archive.
   • Description (optional): A short description to help teammates identify the destination.

2. Click Save destination.

   The wizard shows Destination saved. Nothing is archived until you add an archive rule. Click this destination to open it, then create an archive rule.

Remove an archive destination

Remove a destination when you no longer want to archive logs to its bucket. You need the Archive Configuration Admin role or the Adaptive Logs Admin role.

1. On the Archives page, click the destination to open it.
2. Click Remove archive destination.
3. In Remove archive destination?, click Remove. If the destination has archive rules, type the destination name to confirm first.

Removing a destination permanently deletes all of its archive rules. Files already in your bucket stay there.

Configure archive rules

An archive rule tells Adaptive Logs which log streams to write to a destination. Each rule is a LogQL stream selector. You can create as many archive rules as you need for a destination.

Create an archive rule

1. On the Archives page, click an archive destination to open it.
2. Click Add new archive rule. The Create a new archive rule dialog box opens.
3. Enter a Name for the rule, for example, Production API logs.
4. Build the stream selector:
   • Use label name, operator, and value matchers to target the streams you want to archive. Add more matchers with Add label matcher.
   • Or, switch to Edit as LogQL to type the selector directly, for example, {cluster=~"prod-us-east-0|prod-us-east-1"}.
5. Choose whether to drop the matched logs from live ingestion. Refer to Stop sending archived logs to Cloud Logs.
6. Click Create archive rule.

Check that archiving is working

After you create an archive rule, open the destination from the Archives page. The Archival volume written to this destination panel shows how much data Adaptive Logs has written to your bucket over the last 6 hours.

You can also check your bucket for new files. Refer to Where archived logs are stored.

If the panel stays empty, check that you’re still sending logs that match your stream selector, and that your bucket still grants Grafana access.

Stop sending archived logs to Cloud Logs

Archiving a stream doesn’t stop Grafana Cloud Logs from writing it to Cloud Logs. To archive a stream instead of writing it, the archive rule creates a companion drop rule.

When the option is selected, a Drop rule name field appears. It’s required and pre-filled as Archived {selector}. Drop rule names must be unique, so the dialog box rejects a name that an existing drop rule already uses.

You can only choose Drop these logs from live ingestion when you create an archive rule. To start or stop dropping the logs later, create or delete the matching 100% drop rule on the Drop rules page.

The option is unavailable when:

• Your stream selector is empty or {}, which is the default. A 100% drop rule on a match-all selector would drop all of your live logs, so the dialog box shows An empty selector archives all logs instead of the checkbox. The logs are archived and still ingested.
• You don’t have permission to create drop rules. The archive rule is created on its own, and the matched logs keep being written.

The archive rule is always created first. If the drop rule then fails, the dialog box shows Archive rule created, but the drop rule failed. You can still change the Drop rule name, then click Retry, or click Keep archive rule to keep the archive rule without a drop rule.

Edit and delete archive rules

From the archive destination view, you can:

• Edit a rule to change its name or stream selector.
• Delete a rule to stop archiving the matching streams.

Changes to a rule only affect future log writes. Objects already in your bucket aren’t modified or removed.

To delete a rule, click Delete, then confirm in Delete archive rule?.

Find and query your archived logs

Archived logs are files in your own bucket, so you can read them with any tool that works with your cloud storage. Adaptive Logs can’t delete them or change your bucket settings. You decide how long to keep them, for example, with a lifecycle rule that moves older files to a colder storage class or deletes them after a set time.

Where archived logs are stored

Adaptive Logs writes archived logs under a folder for your instance, with one folder for each minute, in UTC:

Copy

[<PATH_PREFIX>/]tenant=<INSTANCE_ID>/signal=logs/year=<YEAR>/month=<MONTH>/day=<DAY>/hour=<HOUR>/minute=<MINUTE>/<FILE_ID>.json.gz

INSTANCE_ID is the ID of your Cloud Logs instance. You don’t need to look it up: the Full path of ownership marker in the wizard already includes it.

For example:

Copy

tenant=123456/signal=logs/year=2026/month=06/day=05/hour=15/minute=30/018f3a1c-8a2b-7e4d-9f1a-2c3d4e5f6a7b.json.gz

Query engines such as Amazon Athena, DuckDB, and BigQuery read the year, month, day, hour, and minute folders as partitions. Filter on them so a query reads only the time range you need.

Each file is gzip-compressed OpenTelemetry Protocol (OTLP) JSON, the standard OpenTelemetry log format.

Other files in your bucket

Your instance folder also holds two files that aren’t archived logs:

• grafana-archive-ownership: The ownership marker you uploaded when you created the destination.
• grafana-archive-healthcheck/: Small test files that Adaptive Logs writes each time you click Check access. You can delete them.