Query Log Database

This page discusses the Query Log Database which preserves information about queries which have been executed by Stardog over time.

Page Contents

• Overview
• Permissions
• Examples
• Model
  • Logged Properties
  • Inferred Properties
• Settings

---

Overview

The Query Log database allows users to see the history of queries executed along with metadata such as query execution time, user, database, etc. Stardog has extensive audit logging capabilities that includes a logger to identify slow queries. However these logs are only accessible to the infrastructure operators and is not in a form easy to analyze.

The Query Log Database stores that information as RDF and makes it queryable with SPARQL similar to the Data Catalog database. The feature is enabled by default. After the server starts, it will automatically log all SPARQL queries at predefined intervals (see the settings below). To disable query logging, set the server option query.log.enabled to false.

The database comes with a built-in model describing the data it records, which facilitates manual as well as Voicebox-powered querying and browsing in Explorer.

The Query Log Database works with the Stardog cluster out of the box. Each cluster node executes and logs queries independently but changes to the Query Log Database are replicated to all nodes (like changes to any user database).

Updates to the Query Log Database are batched to minimize the overhead of logging queries and replicating the log in the cluster.

The Query Log Database provides built-in functionality to truncate old query log events to prevent the database size from growing continuously.

Permissions

Read access to this database must be granted manually. It is the responsibility of the Stardog administrator.

Examples

This basic query may be used to fetch the last 20 queries executed against the querylog database

prefix : <tag:stardog:api:query:>
select * { 
  ?query a :Query ;
     :user ?user ;
     :type ?query_type ;
     :db ?db ;
     :start ?start_time ;
     :end ?end_time ;
     :query ?query_str ;
     :preExecutionTime ?pre_exec_time .
     OPTIONAL { ?query :status ?status. }
     OPTIONAL { ?query :plan ?query_plan. }
     OPTIONAL { ?query :reasoning ?reasoning. }
     OPTIONAL { ?query :ip ?user_ip. }
}
ORDER BY DESC(?start_time)
LIMIT 20

Model

The Query Log Database comes with a built-in model that describes the data it records: a schema declaring the classes and properties of the query log, plus Stardog Rules that infer the part of that schema the query log does not write directly.

The model is loaded into the named graph tag:stardog:api:context:schema, which is the default schema graph for reasoning, so it is used automatically by queries run with reasoning and no configuration is required. Logged queries themselves are written to the default graph, so the model does not interfere with queries over the log.

Unlike the Data Catalog model, the query log model is reloaded every time the server starts, replacing the contents of the schema graph. It always matches the running server version and never needs to be reloaded manually after an upgrade.

Logged Properties

These properties are written by the query log itself and are available whether or not reasoning is enabled.

Inferred Properties

The rules in the model turn the logged literals into values and individuals that are more convenient to query: durations computed from the start and end times, and a resource for each user, database, query type, status, reasoning schema and day, so that queries can group and navigate by them.

These properties only exist for queries run against the Query Log Database with reasoning enabled, e.g. stardog query querylog --reasoning ....

The inferred datatype properties:

The inferred object properties, each pointing at an individual of the corresponding class:

The IRI of each individual is the IRI of its class, a colon, and the logged value, e.g. the user admin becomes tag:stardog:api:query:User:admin. Users additionally carry their name as an rdfs:label.

This query summarizes query activity per user and day, and must be run with reasoning:

prefix : <tag:stardog:api:query:>
prefix rdfs: <http://www.w3.org/2000/01/rdf-schema#>
select ?user_name ?day (count(?query) as ?queries) (avg(?seconds) as ?avg_seconds) {
  ?query a :Query ;
     :executed_by_user ?user ;
     :start_date ?day ;
     :query_time_in_seconds ?seconds .
  ?user rdfs:label ?user_name .
}
group by ?user_name ?day
order by desc(?day) desc(?queries)

$ stardog query querylog --reasoning activity.sparql

Settings

Currently query.log.enabled is both a database and a server’s option. If set to true for the server, queries are logged for all databases unless it’s set to false for a specific database. All other options are server-wide.

---