---
title: Amazon Athena Query History
description: >-
  Connect Amazon Athena to Datadog Data Observability to monitor query history,
  failures, performance, and cost.
breadcrumbs: >-
  Docs > Data Observability Overview > Quality Monitoring > Data Lake
  Integrations > Amazon Athena Query History
---

> For the complete documentation index, see [llms.txt](https://docs.datadoghq.com/llms.txt).

# Amazon Athena Query History

{% callout %}
# Important note for users on the following Datadog sites: app.ddog-gov.com, us2.ddog-gov.com

{% alert level="danger" %}
This product is not supported for your selected [Datadog site](https://docs.datadoghq.com/getting_started/site.md). ({% placeholder "user-datadog-site-name" /%}).
{% /alert %}

{% /callout %}

{% callout %}
# Important note for users on the following Datadog sites: app.datadoghq.com, us3.datadoghq.com, us5.datadoghq.com, app.datadoghq.eu, ap1.datadoghq.com, ap2.datadoghq.com, uk1.datadoghq.com

{% callout %}
##### Preview

Amazon Athena query history monitoring is in Preview. Contact your Datadog representative to enable it for your organization.
{% /callout %}

{% /callout %}

## Overview{% #overview %}

The Amazon Athena integration collects the history of queries that run in your Athena workgroups. Use it to:

- Track query volume, data scanned, and duration across workgroups and regions.
- Find failing and long-running queries.
- Estimate Athena query compute cost.
- Build lineage between the AWS Glue tables that your queries read and write.

{% image
   source="https://docs.dd-static.net/images/data_observability/amazon_athena/query-history-explorer.9e58e71014dc886a3453506c63e344ab.png?auto=format&fit=max&w=850 1x, https://docs.dd-static.net/images/data_observability/amazon_athena/query-history-explorer.9e58e71014dc886a3453506c63e344ab.png?auto=format&fit=max&w=850&dpr=2 2x"
   alt="Athena queries in Data Observability, showing normalized queries with workgroup, count, duration, bytes scanned, and estimated cost." /%}

Datadog collects query metadata from the Athena API. It does not read query results or access your query result location in Amazon S3.

## Prerequisites{% #prerequisites %}

Before you begin, make sure you have:

- An [AWS account connected in Datadog](https://docs.datadoghq.com/integrations/amazon-web-services.md).
- IAM permissions to modify the Datadog role's policies.
- (Recommended) The [AWS Glue integration](https://docs.datadoghq.com/data_observability/quality_monitoring/data_lakes/aws_glue.md) configured for the same AWS account, so that Datadog can link queries to your Glue tables in lineage.

## Add required IAM permissions{% #add-required-iam-permissions %}

Attach the following policy to the Datadog IAM role configured for your AWS integration:

```json
{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Sid": "AthenaQueryHistory",
      "Effect": "Allow",
      "Action": [
        "athena:ListQueryExecutions",
        "athena:BatchGetQueryExecution",
        "athena:ListWorkGroups"
      ],
      "Resource": "*"
    }
  ]
}
```

## Configure query history{% #configure-query-history %}

1. Navigate to [Datadog Data Observability > Settings](https://app.datadoghq.com/data-obs/settings/integrations).

1. Click Configure next to Amazon Athena.

1. Select an existing AWS account that is already connected to Datadog, or add a new one. For help adding a new account, see the [AWS integration documentation](https://docs.datadoghq.com/integrations/amazon-web-services.md). Then, click Next.

1. Enable the Athena query history toggle.

1. Click Add AWS Region and select a region.

1. (Optional) Enter workgroup names to monitor in that region:

   - **Leave the list empty** to discover and monitor all workgroups in the region, including workgroups created later.
   - **Enter one or more workgroup names** to monitor only those workgroups.

Datadog does not check workgroup names with AWS during setup, so make sure each name matches an existing workgroup.

1. Repeat steps 5 and 6 for each additional region.

   {% image
      source="https://docs.dd-static.net/images/data_observability/amazon_athena/query-history-configuration.b09eb843d623ded0cf966fee0de858a8.png?auto=format&fit=max&w=850 1x, https://docs.dd-static.net/images/data_observability/amazon_athena/query-history-configuration.b09eb843d623ded0cf966fee0de858a8.png?auto=format&fit=max&w=850&dpr=2 2x"
      alt="Amazon Athena configuration with query history enabled, a region selected, and the required IAM permissions." /%}

1. Click Add Account.

To stop monitoring a region, remove it from the configuration. To stop monitoring all regions, disable the Athena query history toggle.

## How query history is collected{% #how-query-history-is-collected %}

- Datadog syncs query history hourly for each configured workgroup.
- The first sync collects queries submitted in the previous 24 hours. Datadog does not backfill older queries.
- Datadog collects queries once they have finished: succeeded, failed, or canceled. Query history does not include queued and in-progress queries.

Collected queries may take longer than an hour to appear, depending on when they finish relative to the sync schedule.

### Collected data{% #collected-data %}

For each query, Datadog collects:

- The SQL text, statement type, catalog, and database.
- The workgroup, AWS region, and Athena engine version.
- The final state and, for failed queries, the error category and type.
- Timing statistics, including total, queue, planning, and engine execution time.
- Data scanned and, for capacity reservation queries, the DPU count.
- Whether Athena reused a previous query result.

## Cost estimates{% #cost-estimates %}

Datadog classifies each query by how Athena billed its compute:

| Billing mode         | Description                                                     |
| -------------------- | --------------------------------------------------------------- |
| On-demand            | Athena billed the query based on data scanned.                  |
| Capacity reservation | The query ran on provisioned capacity.                          |
| Unknown              | Athena did not return enough information to classify the query. |

Based on the billing mode, Datadog reports two cost measures:

- **Estimated on-demand cost**: The estimated compute charge for queries billed on demand. This measure is not reported for capacity reservation queries, because the reservation cost is not attributable to an individual query.
- **On-demand equivalent**: What the query would cost under on-demand pricing based on data scanned. This measure is reported for both on-demand and capacity reservation queries. Use it to compare workloads or evaluate whether a workgroup is a good fit for capacity reservations. It does not represent actual spend.

Both measures cover Athena query compute only. They exclude reserved capacity fees, Amazon S3 storage and requests, data transfer, AWS Glue Data Catalog charges, federated connector charges, and any discounts, credits, or negotiated rates.

## Lineage{% #lineage %}

Datadog parses the SQL text of collected queries to build lineage between the AWS Glue tables that each query reads and writes. Queries against the default `AwsDataCatalog` catalog link to the corresponding tables from the [AWS Glue integration](https://docs.datadoghq.com/data_observability/quality_monitoring/data_lakes/aws_glue.md). For more information, see [Lineage](https://docs.datadoghq.com/data_observability/lineage.md).

## Further reading{% #further-reading %}

Additional helpful documentation, links, and articles:

- [AWS Glue](https://docs.datadoghq.com/data_observability/quality_monitoring/data_lakes/aws_glue.md)
- [Data Observability Lineage](https://docs.datadoghq.com/data_observability/lineage.md)
- [AWS Integration](https://docs.datadoghq.com/integrations/amazon-web-services.md)
- [Data Observability Monitor](https://docs.datadoghq.com/monitors/types/data_observability.md)
