Query tags are name-value pairs embedded in query comments. This gives added visibility into your query workload in two ways:

• You can see overall performance by tag, e.g. the total number of query executions and total query time (only available on-host)
• You can filter by tag, seeing only query families where an execution had the specified tag (available on-host or off-host when samples are enabled)

For example, suppose you’re considering allocating a dedicated database server to interact exclusively with requests coming from your mobile app, as you suspect traffic coming from it to be significant. You might create a query tag called app, with an application name as the value, to rank applications by the workload they send to the database and thus be able to differentiate them. Or, perhaps the queries the database executes varies considerably between clients. Tagging your queries with client will let you filter down to queries for that specific client.

Adding tags to queries

Tags are associated with queries in two ways:

• Comments are included with a query which contains key-value pairs that we can parse into a tag. This allows for both filtering digests in the Profiler as well as seeing query data (such as count, total time, etc.) grouped by tag.
• When installed on-host using packet sniffing, we automatically capture the user, database, and origin of a query and tag it appropriately. This can be used for filtering down to queries executed by a specific user, database, and/or origin in the Profiler and Explorer.

Alter your queries to include the tag embedded in a comment to identify its source. For example, we could differentiate queries coming from the mobile-dedicated infrastructure, which we’ll tag as app=mobile, from the ones originating from other sources, which we’ll simply tag as app=desktop, by using tags. The exact syntax for query comments is database specific: MySQL and PostgreSQL implement nested block comments while MongoDB employs a $comment meta-operator.

The table below illustrates our example for each of those databases:

Database	Example
MySQL	SELECT /* app=mobile */ ...
PostgreSQL	SELECT /* app=mobile */ ...
MongoDB	db.collection.find( { <query> } ).comment('app=mobile' )

We currently do not parse comments using the -- comment syntax.

The default delimiters for query tags are = and a space, but this is configurable through the tag-delimiters agent option: you can use a different 2-character string for representing the delimiters between name-value pairs and tags, respectively. In case you need, there’s also a tag-blacklist agent option, a comma-separated list of tags to be ignored. We automatically blacklist tags whose values have extremely high cardinality, as that data is typically to granular to be useful and does not provide meaningful statistics.

Please note that both MySQL and PostgreSQL command line tools will strip comments. If you are looking at testing this functionality you will need to use a different client to the native ones (or, in the case of MySQL, use option --comments to prevent the client from discarding comments and sending them to the server with the query).

Viewing performance by tag

You can see data (count, total time, etc.) grouped by query tag (on-host only). In the Profiler or Explorer, rank by “Query Tags”. In the “Filter By” you can specify specific tags to filter on (key, value, or both). In our example above, you could filter with app in the “Tag Name” field and mobile (or desktop) in the “Tag Value” field. Press “Apply” to apply the changes and update the data. The result should be similar to the images below:

Filtering queries by tag

When monitoring via packet sniffing (on-host) or off-host and capturing samples, you can filter queries by tag in the Profiler. Set it to rank by category “Query”. Then, click the filter icon and you will see a box labeled “Tags” (the app will not display this option if you do not have any hosts monitored via packet sniffing). Similarly, you can filter queries in the Explorer in the “Filter by Query Tags” box on the left. You can filter queries by specific tags, for example app=mobile or app=desktop. Type your filter and hit enter.

You can also filter by searching only tag keys or values like app or mobile. Searching this way will return all queries with a tag key or value equal to the search term. In other words, if a query A had a tag app=mobile and a second query B had a tag type=app, both queries would appear when you searched for app.

An important thing to note is that this will show you query families which had at least one instance of the tag. The data displayed is for all executions of the query, not executions which had a specific tag (currently not possible).