Introduction
This document outlines several strategies to help you protect and optimize your self-hosted Artifactory instance from unexpected issues caused by AQL queries. It is intended for customers experiencing issues related to AQL. If you are using a SaaS solution, this article will not apply, as JFrog manages and monitors these parameters on your behalf.
Artifactory Query Language (AQL) allows you to uncover data related to your artifacts and builds stored in your Artifactory instances using a specialized syntax and rich search criteria.
Issues you may encounter
AQL queries are translated into database queries. When executing AQLs on large data sets, unexpected issues may arise. For instance, excessive data retrieval or automated requests can overload Artifactory or the database, potentially causing downtime due to out-of-memory errors, high CPU usage, or slow performance. Although blocking problematic users can sometimes help, it may not be an immediate solution.
Solution - AQL Rate Limit Monitoring
Artifactory offers the ability to implement rate limiting of AQL queries. This article offers guidance on using the rate limit mechanism to address these issues.
It will cover all the system properties related to AQL rate limit parameters.
These can be adjusted by editing the $JFROG_HOME/artifactory/var/etc/artifactory/artifactory.system.properties file and restarting Artifactory.Note
Before enabling rate limiting, it’s essential to understand how users will be notified when they are rate-limited. If a user exceeds the AQL rate limit, they will receive a status code 429 message indicating “too many requests.”
Configuration Values
To enable the AQL rate limit:
artifactory.aql.queries.limit.enabled=true
(default: false, available from version 7.77)Note
Please read the following information before enabling this setting.
Key parameters
Enabling the AQL rate limit will lead to several changes that you may want to adjust beforehand:
1. Artifactory will be able to execute up to 3 AQL queries in parallel. If you frequently use multiple AQL queries simultaneously, you may need to adjust this limit using the following system property:
artifactory.aql.queries.limit=10
(default value: 3)
2. If an AQL query waits more than 10 seconds in the queue to be executed in the database, it will be rate limited:
artifactory.aql.queries.pending.timeout.millis=60000
(default value: 10000 millis)
Additional optional parameter
Starting from Artifactory 7.84.20:
artifactory.aql.search.query.max.limit = 500000
(default value: -1, which means no limit).
When set, any AQL exceeding this limit will have its results trimmed and only the number of rows matching the limit will return.
For example, if the query exceeds 500000 rows, only 500000 rows will return.
Note that you will only be notified of this trimming from version 7.104, with a message in the artifactory-service.log stating:
“AQL query reached the search hard limit; results are trimmed. Please address the configurable limit.”
Workers
Specific to Workers (if you are not using Workers, this can be ignored):
#1
artifactory.aql.queries.workers.pending.timeout.millis=10000
(default value: 5000 millis):
If an AQL generated by a Worker remains in the queue for more than 10 seconds before being executed in the database, it will be rate limited.
#2
artifactory.aql.queries.workers.limit=8
(default value: 6):
Artifactory will be able to execute up to 8 AQL generated by a Worker in parallel, and if we pass this value, it will be rate-limited.Note
The Worker parameters do not conflict with the general AQL parameters. If an AQL query originates from a Worker, the Worker’s limit and timeout settings will apply. If not, the standard AQL limits and timeouts will take effect.