Collect Diagnostic Data¶

When troubleshooting does not resolve the issue, the Excalibur support team may request diagnostic data. This page covers how to export logs from the application server and the mobile app.

Contact Excalibur Support¶

If the troubleshooting entries in Deployment Issues and Configuration and Operation Issues do not resolve your issue, contact the Excalibur support team:

E-mail — support@xclbr.com
Support ticket — submit a ticket through your organization's support channel

Include a description of the issue, the steps you have already tried, and any error messages or log excerpts. If the support team requests diagnostic data, follow the instructions below.

Application Server Logs¶

When a server-side issue requires deeper analysis, the support team may request application server logs. Excalibur includes a centralized log aggregation service (Loki) that captures logs from every application component. The Excalibur Chronicler tool exports these logs into a portable archive you can share with support.

What is Chronicler?

Excalibur Chronicler is a Bash utility that runs on the application server. It queries Loki through the running Excalibur container stack, packages the results into a compressed .tar.gz archive, and optionally encrypts the output so that only Excalibur support can read it.

Read-only — does not modify, delete, or write any data to the Excalibur stack
No network calls — the exported archive stays on the local filesystem until you send it manually

Prerequisites¶

Before exporting logs, ensure the following:

The Excalibur stack is running with the Loki service active
Docker or kubectl is installed and available in PATH on the application server
(Optional) openssl on the host for encrypted exports — if not available, the script uses openssl from the api container automatically

Download and Verify Chronicler¶

Download the script:

curl -fsSL \
 https://raw.githubusercontent.com/excalibur-enterprise/excalibur-v4-chronicler/refs/heads/devel/excalibur-chronicler.sh \
 -o excalibur-chronicler.sh

Verify the download integrity:

echo "76a4b1d7bd1862044496fcacfc4d14df5fe544dacb6ee089659697038a75c3f6  excalibur-chronicler.sh" | sha256sum -c

The output should show excalibur-chronicler.sh: OK.

Make the script executable:
```
chmod +x excalibur-chronicler.sh
```

Export Logs¶

Run the script on the application server to export logs. The recommended approach is to run the script without --service or --level filtering. This exports all log levels and all services, which gives the support team the full context needed for analysis.

Do not filter by log level or service

Excalibur uses correlation IDs to track request flows across application containers. Filtering by log level (e.g., --level error) or by a single service strips out the surrounding info and debug entries from other components that provide essential context for tracing these flows. Always export all levels and all services unless the support team explicitly requests otherwise.

Kubernetes deployment¶

./excalibur-chronicler.sh --runtime kubectl

If your Excalibur namespace differs from the default (excalibur), specify it with --namespace:

./excalibur-chronicler.sh --runtime kubectl --namespace <your-namespace>

Docker deployment¶

./excalibur-chronicler.sh

Docker is the default runtime. The script auto-detects the api container, exports all log levels and all services from the last 24 hours, and saves the archive to the current directory.

Narrow the time range¶

If the support team asks you to export a specific time window, use --since or --from / --to:

# Last 6 hours
./excalibur-chronicler.sh --runtime kubectl --since 6h

# Specific date range (ISO 8601)
./excalibur-chronicler.sh --runtime kubectl --from 2026-03-20 --to 2026-03-22

# From a specific date until now
./excalibur-chronicler.sh --runtime kubectl --from 2026-03-25T14:00:00

Export logs for a single service¶

./excalibur-chronicler.sh --runtime kubectl --service core

Replace core with the service name relevant to the issue (e.g., api, repository). The support team will tell you which service to target.

Encrypted Export¶

For sensitive environments, encrypt the archive so that only Excalibur support can decrypt it:

./excalibur-chronicler.sh --runtime kubectl --encrypt

The script uses ECDH envelope encryption (AES-256-CBC + EC P-384) with the Excalibur support public key. The encrypted archive has an .enc.tar extension. Send the entire .enc.tar file to support — do not extract or modify it.

Available Options¶

Option	Description	Default
`-t`, `--since` DURATION	Time range to export: `30m`, `6h`, `2d`, `1w`	`24h`
`--from` DATETIME	Start of date range (ISO 8601)	—
`--to` DATETIME	End of date range (requires `--from`)	now
`-l`, `--level` LEVEL	Filter by log level: `error`, `warn`, `info`, `debug`	all
`-s`, `--service` NAME	Filter by service name (e.g., `api`, `core`, `repository`)	all
`-o`, `--output` DIR	Output directory for the archive	`.`
`-e`, `--encrypt`	Encrypt with Excalibur support public key	off
`-r`, `--runtime` RT	Container runtime: `docker` or `kubectl`	`docker`
`-N`, `--namespace` NS	Kubernetes namespace (ignored for Docker)	`excalibur`
`-y`, `--yes`	Skip the confirmation prompt	off
`-v`, `--verbose`	Enable verbose/debug output	off

Output Format¶

The script produces an excalibur-chronicle-<timestamp>.tar.gz archive containing one or more JSON batch files:

excalibur-chronicle-20260326-141500.tar.gz
└── excalibur-chronicle-20260326-141500/
    ├── batch-0001.json
    ├── batch-0002.json
    └── batch-0003.json

When --encrypt is used, the output is an .enc.tar file containing the encrypted data and an ephemeral public key.

Troubleshoot Chronicler¶

Cannot find the api container/pod

The Excalibur stack is not running, or the container has a non-standard name.

# Docker — verify the api container is running
docker ps | grep api

# Kubernetes — verify the api pod is running
kubectl -n excalibur get pods -l app=api

You can specify the container manually with --container <name>.

Cannot reach Loki

Loki is not running or is not accessible from the api container.

# Verify Loki is running
docker ps | grep loki

# Test connectivity from inside the api container
docker exec api curl -sf http://loki:3100/ready

If Loki uses a non-standard URL, specify it with --loki-url <url>.

No log entries found

Verify the time range covers a period when the system was active.
Check that services are configured to push logs to Loki.
Try a broader filter — remove --level or --service.
Use --verbose to see the exact LogQL query and Loki responses.

Send the Archive to Support¶

After the export completes, send the archive file to the Excalibur support team:

E-mail — attach the archive to support@xclbr.com
Support ticket — upload the archive to your existing ticket

Include a brief description of the issue, the time window when it occurred, and any error messages you observed. If you used --encrypt, no additional encryption is needed for transfer — the archive can only be read by Excalibur support.

Excalibur Token (Mobile Application)¶

The Excalibur Token mobile app continuously collects diagnostic logs locally on your device. These logs are stored in a limited-size queue and are automatically rotated — older entries are replaced by newer ones.

By default, Usage & diagnostics is disabled. While disabled, logs never leave your device. When you enable diagnostic sending, the app pushes the locally stored log queue to the Excalibur server responsible for log collection. This includes logs captured before the feature was enabled, as long as they have not been rotated out of the queue.

What is collected:

Timestamps, app events, error details
Device model and OS version

What is not collected: personal information of any kind.

How it works:

Disabled (default) — the app collects logs locally. Nothing is sent to the server.
Enabled — the local log queue is pushed to the Excalibur log collection server. The support team can then access and analyze the logs.
Disabled again — the app stops sending logs immediately. Local collection continues.

When to use this

The support team may ask you to enable diagnostics and share your Unique Device ID so they can locate your device's logs and match them with your reported issue. Because the app retains a local log history, enabling diagnostics after a problem occurs still captures relevant data.

Enable Usage and Diagnostics¶

Open the Excalibur Token app → tap the Settings icon (gear) in the bottom-right corner.

Figure 1. Settings icon
Go to General → turn the Usage & diagnostics toggle on.

Two things happen:
- The app pushes the locally stored log queue to the Excalibur server.
- A Unique Device ID appears below the toggle.
Figure 2.Usage & diagnostics toggle — enabled
Tap the Unique Device ID value → it is copied to your clipboard automatically.

You will see a "Copied to clipboard" confirmation.

Figure 3.Unique Device ID — tap to copy
Send the copied ID to your Excalibur contact via e-mail, support ticket, or chat.

Disable Usage and Diagnostics¶

After the issue is resolved, disable diagnostic sending:

Open Settings in the Excalibur Token app.
Go to General → turn the Usage & diagnostics toggle off.

The app stops sending logs to the server immediately. Local log collection continues on-device as usual.