Troubleshooting the IBM Security QRadar AQL Plugin

Use the following information to troubleshoot your IBM® Security QRadar® AQL Plugin.

Important: If you are unable to resolve an issue with your IBM Security QRadar AQL Plugin, Grafana dashboards, Grafana dashboard panels, or AQL query, contact Customer Support (www.ibm.com/support/).

QRadar Ariel Search API Performance

The IBM Security QRadar AQL Plugin dashboard panel total request time can vary according to the QRadar Ariel Search API response time. This response time can be impacted by several factors including:

state of the QRadar Ariel server
QRadar resource availability

AQL query syntax can be optimised for performance.

For more information, see Tips for creating AQL queries for dashboard charts.

Troubleshooting data source errors

Table 1. Common data source issues and solutions
Error message	Issue	Solution
`check your QRadar host` `connection refused. Check your QRadar Port`	The host cannot be contacted because the host address or port number is incorrect.	In your Grafana instance, from the navigation menu, click Connections > Data sources. On the Data sources page, click IBM Security QRadar AQL Plugin. In the QRadar Host field, enter your QRadar URL. In the QRadar Port field, enter your QRadar port. Click Save & test.
`failed to verify certificate for the requested data source. Please check your SSL certificate` `unauthorized access to the requested data source. Please check your Authorized Service Token`	The information in your SSL Certificate or Authorized Service Token field is incorrect or missing.	In your Grafana instance, from the navigation menu, click Connections > Data sources. On the Data sources page, click QRadar AQL Plugin. In the SSL Certificate field, enter your QRadar SSL certificate. In the Authorized Service Token field, enter your QRadar authorized service token. Click Save & test.
`dial tcp 9.30.167.223:443: connect: connection refused`	The plugin is unable to connect to QRadar.	Check your network connection.
`time zone not found:`	The entered time zone value does not match the expected format, Region/City, or is not valid.	In your Grafana instance, from the navigation menu, click Connections > Data sources. On the Data Sources page, click QRadar AQL Plugin. In the Plugin TimeZone field, select a time zone for all queries from the time zone drop down (default is UTC).
`error while closing response body`	Internal HTTP client error.	Contact Customer Support (www.ibm.com/support/).

Troubleshooting query errors

Table 2. Common AQL query issues
Error message	Issue
`Parse error: no viable alternative at input ''. The query_expression contains invalid AQL syntax.`	Your AQL query syntax contains a keyword error.
`Field "usernam" does not exist in catalog "events". The query_expression contains invalid AQL syntax.`	The column that is referenced in your AQL query does not exist.
`Catalog "event" does not exist. The query_expression contains invalid AQL syntax.`	The table that is referenced in your AQL query does not exist.
`Unrecognized context (Line: 1, Position: 32): "%s". The query_expression contains invalid AQL syntax.`	Your AQL query syntax contains a keyword error.
`Parse error: missing SELECT at 'Selet'. The query_expression contains invalid AQL syntax.`	Your AQL query syntax contains a keyword error.
`Parse error: extraneous input 'NT' expecting {TRUE, FALSE, NULL}. The query_expression contains invalid AQL syntax.`	Your AQL query syntax contains a keyword error.
`Parse error: mismatched input 'minute' expecting {MINUTES, HOURS, DAYS}. The query_expression contains invalid AQL syntax.`	Your AQL query syntax contains a keyword error.
`Failed to connect to ariel server. Please try again later. The Ariel server might be temporarily unavailable or offline. Please try again later.`	QRadar ariel server is not running. Contact QRadar admin.
`parsed response has no data.`	Your AQL query result set is empty. Tip: Use the Advanced Search feature in QRadar Log Activity / Network Activity to run AQL queries and verify the existence of query results.
`query error: the QRadar AQL plugin currently supports only the events, flows, and globalview databases.`	An unsupported Ariel database was used in an AQL query, for example, simarc.
Timeout getting query status after ``. QRadar Search `` has been cancelled.	The wait query results exceeded the configured timeout value.
`Unable to parse time: "00:00 2023-10-04". Unable to parse '00:00 2023-10-04'.. The query_expression contains invalid AQL syntax.`	Plugin START / STOP values are in an unsupported datetime format.

To resolve these issues, you must correct your AQL query. To edit your query, follow these steps:

In your Grafana instance, from the navigation menu, click Dashboards.
On the Dashboards page, click the dashboard that you want to edit.
On the panel that you want to edit, click the Menu icon (), and then click Edit.
Edit your query, and then click Save.
In the Save dashboard panel, enter a description of your changes, and then click Save.

For more information about AQL queries, see Ariel Query Language (AQL)

Enabling Grafana logging

All plugin log entries are DEBUG level. To provide more details during troubleshooting, enable Grafana DEBUG level logging in the configuration settings.

To open the grafana.ini file, run the following command:
```
 vi /etc/grafana/grafana.ini
```

In the grafana.ini file, in the plugins configuration section, update the following line:

#################################### Logging ##########################
[log]
;level=

with the following entry:

#################################### Logging ##########################
[log]
level=debug

To restart Grafana and apply the changes, run the following command:
```
sudo /bin/systemctl restart grafana-server.service
```

Time Zone

To ensure that your dashboards return accurate results, the plugin time zone must match the QRadar instance time zone.

From the navigation menu, click the Connections > Data Sources.
On the Data Sources page, select a time zone for all queries from the time zone drop down (default is UTC).
Click Save & test.