Operational Log Collection Guide

Overview

When you need to analyze an incident or provide information for technical support, collect operational logs and diagnostic data from the QueryPie server according to the symptoms. This document describes the basic logs to collect first in an operational environment, data to collect only when additionally required, and information to include when submitting the data.

Whenever possible, the basic collection should cover a range before and after the incident time. If the issue can be reproduced, record the reproduction time as well so that the logs can be compared more easily.

Basic collection items

When an issue requires analysis, collect the following four items first.

1. QueryPie file logs
2. Container standard output logs
3. /api/config/monitoring dump
4. Multi Agent or Windows Server Agent logs

Collecting QueryPie file logs

File logs are application logs written by each component under /var/log/querypie. The path inside the container is the same, but the path visible from the host may differ by version.

Checking the log path

1. Check the QueryPie version.
2. Check the log path on the host.
   • 9.x ~ 10.4.x: /var/log/querypie
   • 11.0.x+: Generally the log path in the parent directory of the compose file
3. If necessary, check the log path directly inside the app container.

The following example checks file logs directly from the host.

ls -al ../log

In an environment where the host path is /var/log/querypie, use the following command.

ls -al /var/log/querypie

The following example checks file logs inside the app container.

docker exec -it querypie-app-1 sh
ls -al /var/log/querypie

Compressing file logs

1. Prepare a directory for collecting logs from before and after the incident time.
2. Verify that logs related to api, engine, nginx, and proxy are included.
3. Compress the logs using the path for your environment.

mkdir -p support-logs
tar -czf support-logs/querypie-file-logs.tar.gz -C .. log

In an environment where the host path is /var/log/querypie, collect the logs as follows.

mkdir -p support-logs
tar -czf support-logs/querypie-file-logs.tar.gz /var/log/querypie

Collecting container standard output logs

Along with file logs, collect the container’s stdout and stderr logs.

1. Save the app container logs.
2. If the tools profile is running, save the tools logs as well.

mkdir -p support-logs
docker logs querypie-app-1 > support-logs/app.docker.log 2>&1
docker logs querypie-tools-1 > support-logs/tools.docker.log 2>&1 || true

Collecting a monitoring dump

For suspected API hangs, response delays, or deadlocks, use /api/config/monitoring first.

1. Sign in with the Owner account or an account with the SYSTEM_PROPERTIES permission.
2. In a browser, go to /api/config/monitoring.
3. Check the required time range.
   You can also click Create New Dump to create a new dump file.
4. Select one of the following options.
   • Download only the dump
   • Download the dump and application logs together using Dumps + All Logs

Temporarily changing the log level

Only when the basic logs are insufficient to identify the cause, temporarily raise the log level to debug and collect reproduction logs.

1. Record the time before changing the log level to debug.
2. Raise the log level of the target component.
3. Reproduce the same symptom.
4. Collect the logs.
5. Restore the original level.
   1. The default log level is warn for api and info for the other components: engine, arisa, cabinet, kubepie, rotatepie, and novas. (arisa is the proxy component.)

docker exec -it querypie-app-1 /app/change-log-level.sh debug api

To apply the setting to all components, omit the component.

docker exec -it querypie-app-1 /app/change-log-level.sh debug

The following components are supported.

• api
• engine
• arisa
• cabinet
• kubepie
• rotatepie
• novas
• all

Logs to collect first by symptom

You do not always need to raise every component’s log level to debug. Use the following criteria to collect the logs that match the symptom first, and expand the scope only when necessary.

Collecting Multi Agent logs

If the environment uses Multi Agent, collect the desktop app logs as well.

1. Check the log path for the operating system in use.
   • Windows: %USERPROFILE%\.querypie-multi-agent\logs\
   • macOS: $HOME/.querypie-multi-agent/logs/
   • Linux: $HOME/.querypie-multi-agent/logs/
2. Collect the general logs and webView.log.
3. If detailed logs are required, turn on Diagnostic Tools > Enable Tracing, then reproduce the issue.
4. Turn tracing off again after collection.
5. If necessary, use Diagnostic Tools > Export Log to create an archive.

Collecting SAC Windows Server Agent logs

If the environment uses Windows Server Agent with SAC, collect the agent logs as well.

Collecting basic service logs

1. Check the following path on the Windows Server.
   • %ProgramData%\QueryPie\Server Agent\Logs\
2. Compress the service logs first.

$logRoot = "$env:ProgramData\QueryPie\Server Agent\Logs"
$outFile = "$env:TEMP\querypie-server-agent-logs.zip"
Compress-Archive -Path "$logRoot\*" -DestinationPath $outFile -Force

When per-user logs are required

If the issue is reproduced only in a specific Windows user session or you need to check per-user behavior, collect the following path as well.

• %ProgramData%\QueryPie\Server Agent\Logs\Users\<WindowsUser>\

When verbose logs are required

1. Open PowerShell on the Windows Server.
2. Check the current LogLevel.

Get-ItemProperty "HKLM:\SYSTEM\CurrentControlSet\Services\QueryPie Server Agent Persistent" | Select-Object LogLevel

3. If necessary, change LogLevel to Verbose.

Set-ItemProperty "HKLM:\SYSTEM\CurrentControlSet\Services\QueryPie Server Agent Persistent" -Name "LogLevel" -Value "Verbose"

4. Reproduce the symptom and collect the logs.
5. Restore it to Information after collection.

Set-ItemProperty "HKLM:\SYSTEM\CurrentControlSet\Services\QueryPie Server Agent Persistent" -Name "LogLevel" -Value "Information"

Collecting additional data only when required

Collect the following data only when you need to analyze a configuration issue, deployment difference, or thread dump fallback.

Collecting configuration files

1. Check the current deployment configuration files.
2. Mask sensitive information before submitting them.

Examples of additional items to collect include the following.

• .env or compose-env
• compose.yml or docker-compose.yml
• nginx.d/
• Custom configuration files
• logrotate.d/querypie

Collecting a JVM thread dump as a fallback

Use this only when /api/config/monitoring is difficult to access or you need to collect a thread dump directly inside the container.

1. Connect to the app container from the host.

docker exec -it querypie-app-1 bash

2. Find the API Java PID inside the app container and create a thread dump.

ps -ef | grep '[a]pp/api/api.jar'

3. If available, collect the thread dump using jcmd.

jcmd <PID> Thread.print > /tmp/api-thread-dump.txt

4. Exit the app container, then copy the dump file from the host.

docker cp querypie-app-1:/tmp/api-thread-dump.txt support-logs/api-thread-dump.txt

5. If jcmd is unavailable, use kill -3 inside the app container.

kill -3 <PID>

Information to include when submitting logs

Providing log files alone can increase the analysis time, so include the following information.

Checklist template

[Basic Information]
- Time of occurrence:
- Server timezone:
- Symptom:
- Impact scope:
[Reproduction Information]
- Reproducibility:
- Reproduction steps:
- Reproduction time:
[Collected Logs]
- File logs: Collected / Not collected
- docker logs: Collected / Not collected
- monitoring dump: Collected / Not collected
- Multi Agent logs: Not applicable / Collected / Not collected
- Windows Server Agent logs: Not applicable / Collected / Not collected
[Additional Collection]
- Configuration files: Collected / Not collected
- JVM thread dump fallback: Collected / Not collected
[Additional Notes]
- Notes: