The Query History Starter

This feature is experimental.

Introduction

The Query History Starter automatically sets up query history persistence, a REST API, and security rules for tracking MDX query executions in an Atoti Server application. When enabled, it records MDX queries executed against the server, including their status, duration, user, and metadata. It also exposes REST endpoints to browse, filter, cancel, and delete recorded queries, as well as retrieve query execution plans. The following metadata attributes are automatically attached to queries:

apiType — set to rest for queries executed via the REST API.
failureCause — added automatically when a query fails, containing the message of the error that made it fail, such as the query result limit it exceeded.

A query received over XMLA carries an attribute per identifier its client supplied, named after the XMLA property carrying it. The id recorded for a query is its query id, written by default as 16 lowercase hexadecimal characters, such as 00f067aa0ba902b7. That value is also reported in the query execution reports and on the OpenTelemetry spans of the query. By default, a recorded query can therefore be joined with its log lines and its trace. See What identifies a query in a trace?. The Query History Starter is typically used alongside the Atoti Server Starter.

Installation

To use the starter, add the following dependency to your pom.xml.

<dependency>
  <groupId>com.activeviam.springboot</groupId>
  <artifactId>query-history-starter</artifactId>
  <version>${activepivot.version}</version>
</dependency>

Configuration

All properties live under the atoti.server.query-history namespace.

Enabling and disabling

The starter is enabled by default. To disable it:

atoti:
  server:
    query-history:
      enabled: false

Database

Query history is persisted using Hibernate. The database property accepts standard Hibernate and HikariCP connection pool settings. The following example configures an H2 in-memory database:

atoti:
  server:
    query-history:
      database:
        hibernate:
          dialect: org.hibernate.dialect.H2Dialect
          hbm2ddl.auto: update
          show_sql: false
          format_sql: false
          connection:
            driver_class: org.h2.Driver
            autocommit: false
            provider_class: org.hibernate.hikaricp.internal.HikariCPConnectionProvider
          hikari:
            maximumPoolSize: 10
            maxLifetime: 300000
            idleTimeout: 0
            dataSourceClassName: org.h2.jdbcx.JdbcDataSource
            dataSource:
              url: "jdbc:h2:mem:query_history;DB_CLOSE_DELAY=-1;IGNORECASE=TRUE"
            poolName: QueryHistory-ConnectionPool

H2 in-memory databases are not recommended for production. Use a persistent database such as PostgreSQL or MySQL to retain query history across restarts.

Field limits

Maximum character lengths for stored fields can be tuned. Values exceeding the limit are truncated.

Property	Default	Applies to
`field-limits.query`	10 000	Query text
`field-limits.standard-field`	1 000	Node name, trace ID, username, metadata attribute names
`field-limits.metadata-value`	10 000	Metadata attribute values, error messages

Query id format

By default, the id of a recorded query is written as 16 lowercase hexadecimal characters, such as 00f067aa0ba902b7. Set atoti.server.query-history.legacy-id-format to true to write it as a signed decimal number instead, such as -1085102592571150095:

atoti:
  server:
    query-history:
      legacy-id-format: true

Use it when clients or database columns expect a number, for example a query history table created with your own DDL and a numeric id column. Atoti always creates the id column as a VARCHAR. Entries recorded before the format was changed keep the id they were written with. The REST endpoints that get or delete a query by id take the id as it was recorded, in either format. The endpoint that cancels a running query takes it in the configured format.

The legacy-id-format property is deprecated since 6.2.3 and will be removed in 6.3, where ids are always written as 16 hexadecimal characters.With legacy-id-format set to true, a recorded query can no longer be joined as is with its log lines and its trace by id: the value is the same 64-bit number, written differently.

Security

The Atoti Server Starter registers a SecurityFilterChain (order 330) that protects all endpoints under /activeviam/query-history/rest/v1/**. It uses the project’s MachineToMachineSecurityDsl with the following rules:

Operation	Required authority
`OPTIONS`	Permitted (CORS preflight)
`DELETE`	Admin roles (configured via `atoti.server.security.roles-admin`)
`PATCH`	Admin roles (configured via `atoti.server.security.roles-admin`)
`GET`	Admin or user roles (combined `roles-admin` and `roles-user`)

The security filter chain can be disabled via:

atoti:
  server:
    endpoint:
      query-history:
        security:
          enabled: false

Distributed setup

In a distributed environment, the Query History Starter should be activated on the query node — the node that receives and executes client MDX queries. Activating it on a data node will have no effect since data nodes do not execute client MDX queries. Query cancellation is not supported in distributed environments. The cancel endpoints only operate on queries known to the local node.

REST API

All endpoints are served under the base path /activeviam/query-history/rest/v1. See the Query History REST API for the full endpoint reference.

Releases and upgrades

Getting started

Concepts

Step 1: Bring your data into Atoti

Step 2: Design your Cube

Step 3: Build an Atoti application

Step 4: Query an Atoti application

Configure Atoti

Secure Atoti

Operate Atoti

Reference

The Query History Starter

Introduction

Installation

Configuration

Enabling and disabling

Database

Field limits

Query id format

Security

Distributed setup

REST API

​Introduction

​Installation

​Configuration

​Enabling and disabling

​Database

​Field limits

​Query id format

​Security

​Distributed setup

​REST API

Introduction

Installation

Configuration

Enabling and disabling

Database

Field limits

Query id format

Security

Distributed setup

REST API