Query logging in AWS Clean Rooms - AWS Clean Rooms
Receiving query logsUsing query logs

Query logging in AWS Clean Rooms

Query logging is a feature in AWS Clean Rooms. When you create a collaboration and turn on Query logging, members can store query logs relevant to them in Amazon CloudWatch Logs.

With query logs, members can determine if the queries comply with the analysis rules and align with the collaboration agreement. In addition, query logs help support audits.

When the Query logging option is turned on in the AWS Clean Rooms console, the query logs include the following:

  • analysisRule – The analysis rule for the configured table.

  • analysisTemplateArn – The analysis template that was run (appears depending on analysis rule).

  • collaborationId – The unique identifier for collaboration in which the query was run.

  • configuredTableID – The unique identifier for configured table referenced in the query.

  • directQueryAnalysisRulePolicy.custom.allowedAnalysis – The analysis template allowed to run on configured table (appears depending on analysis rule).

  • directQueryAnalysisRulePolicy.v1.custom.allowedAnalysisProviders – The query providers allowed to create query (appears depending on analysis rule).

  • errorCode – The error code when a query failed to execute properly.

  • errorMessage – The error message when a query failed to execute properly.

  • eventID – The unique identifier for the query run. After August 31, 2023, the unique identifier is the same as the protectedQueryID.

  • eventTimestamp – The query run time.

  • parameters.parametervalue – The parameter values (appears depending on the query text).

  • queryText – The SQL definition of query run. If there are parameters, they are labelled as :parametervalue.

  • queryValidationErrors – The query errors at query validation.

  • schemaName – The name of configured table association referenced in the query.

  • status – The execution status of the query.

Receiving query logs

You don't need to perform any actions outside of AWS Clean Rooms to set up query logs. AWS Clean Rooms creates log groups for collaborations after each collaboration member creates a membership.

Members who can query, members who can receive results, and members whose configuration tables are referenced in the query will receive a query log.

The member who can query and member who can receive results will receive query logs for each configured table that is referenced in the query. If they don’t own the configured table, they won't be able to view the configured table ID (configuredTableID).

If a member has multiple configured table associations referenced in the query, they will receive a query log for each configured table.

Logs are created for queries that contain unsupported and supported SQL in AWS Clean Rooms. For more details, see the AWS Clean Rooms SQL Reference.

Logs are also created when queries reference configured tables that are not associated to the collaboration.

Logs are not created for incorrect SQL in AWS Clean Rooms.

Query logs indicate the status of a query but don't report whether query output was delivered. They confirm that a query was submitted by the member who can query. Query logs also confirm that the query contains supported SQL in AWS Clean Rooms and references configured tables associated to the collaboration.

For example, a log isn't produced if the query was cancelled after AWS Clean Rooms validated its compliance with analysis rules and during query processing.

If you delete the log group, you must re-create the log group manually with the same log group name (collaboration ID of the collaboration). Or, you can turn the logging off and on in your membership.

For more information about how to turn on query logging, see Creating a collaboration.

For more information about Amazon CloudWatch Logs, see the Amazon CloudWatch Logs User Guide.

Using query logs

We recommend that members periodically take the following actions:

  • To verify that the queries match the use cases or queries that were agreed upon for the collaboration, review the queries that are run in the collaboration.

    For more information about how to view recent queries, see Viewing recent queries.

  • To verify that the configured table columns match what was agreed upon for the collaboration, review the configured table columns that are used in collaboration members’ analysis rules and in queries.

    For more information about how to view the configured columns, see Viewing tables and analysis rules.