Collecting debug logs in Omada Identity Cloud Private

This page explains how to use the debug log collection script (collect_debug_logs.sh) to gather diagnostic data from your Omada Identity Cloud Private environment. Omada Support may ask you to run this script and send the output when investigating issues.

When to run this script

Run the debug log collection script when:

• Omada Support asks you to capture logs while reproducing an issue.
• You need to gather a snapshot of current environment state for analysis before contacting support.

Prerequisites

Before running the script, ensure the following:

• Azure CLI is installed and authenticated (az login) against the correct subscription.
• kubectl, jq, zip, and curl are available on the machine running the script (curl is used by the Log Analytics collector).
• The executing identity has the following RBAC permissions on the environment resource group:

Permission	Purpose
Microsoft.ContainerService/managedClusters/read	AKS – read cluster
Microsoft.ContainerService/managedClusters/listClusterAdminCredential/action	AKS – list admin credentials
Microsoft.OperationalInsights/workspaces/read	Log Analytics – read workspace
Microsoft.OperationalInsights/workspaces/query/*/read	Log Analytics – query
Microsoft.ServiceBus/namespaces/read	Service Bus – list namespaces
Microsoft.ServiceBus/namespaces/topics/read	Service Bus – list topics
Microsoft.ServiceBus/namespaces/topics/subscriptions/read	Service Bus – list subscriptions

note

The script checks RBAC permissions automatically at startup and warns if anything is missing. Missing permissions do not abort the run; they indicate which collectors are likely to warn. Newly granted RBAC roles can take several minutes to propagate.

Running the script

From the repository root, run:

Tool: Bash shell

./scripts/collect_debug_logs.sh --global-prefix <global-prefix> [options]

Where <global-prefix> is your environment prefix (for example, oisaas-ab001).

After the pre-flight and permission checks, the script shows a confirmation prompt that lists what will be collected and notes the redaction scope.

Modes: live vs snapshot

The script supports two modes, controlled by the --mode flag:

• Live mode.
• Snapshot mode.

tip

Live mode is the default and is recommended for capturing a specific issue.

Live mode (default, recommended)

Actively monitors your environment while you reproduce the issue, then queries Log Analytics and Application Insights over that same window.

Tool: Bash shell

./scripts/collect_debug_logs.sh --global-prefix oisaas-ab001 --mode live

How it works:

• Tails AKS pod logs and polls pod status every 20 seconds for up to --duration seconds (default: 10 minutes).
• Press Ctrl+C once you have reproduced the issue to stop the window early.
• After the window closes, queries Log Analytics and Application Insights over the exact capture window – with an ingestion wait (default: 60 seconds) so recently generated telemetry has time to arrive before the query runs.

Use live mode when you are actively reproducing an issue and need correlated data from AKS logs, pod status, and Log Analytics in the same time window.

Snapshot mode

Captures the current state of your environment at a single point in time. No waiting, no reproduction step required.

Tool: Bash shell

./scripts/collect_debug_logs.sh --global-prefix oisaas-ab001 --mode snapshot

How it works:

• Captures current pod status and a tail of already-buffered logs.
• Queries Log Analytics and Application Insights with a zero-length time window (current moment only) – results from OIS_CL and Application Insights are usually empty.

note

Snapshot mode may not capture the relevant log lines if the issue occurred before you ran the script. For capturing a specific failure, use live mode instead. Snapshot is best for checking the current environment state.

Common flags

Flag	Default	Description
--global-prefix <prefix>	(required)	Environment prefix (for example, oisaas-ab001).
--mode <live|snapshot>	live	Collection mode – see above.
--duration <seconds>	600	Live monitoring window length.
--ingestion-wait <seconds>	60	Minimum time since the live window closed before Log Analytics is queried, allowing telemetry ingestion to catch up. The other collectors run first and count against this window; only the remainder (if any) is waited. Live mode only. Set to 0 to disable.
--output-dir <path>	.	Where to write the output .zip.
--max-zip-warn-mb <n>	200	Warn (without failing) if the output .zip exceeds this size in MB.
--max-log-lines <n>	2000	Maximum lines captured per pod (AKS pod logs in snapshot mode; ingress logs in both modes).
-y, --yes		Skip the pre-flight confirmation prompt.
--verbose		Show extra detail in console output and README.txt.

For the full flag reference, run ./scripts/collect_debug_logs.sh --help.

What gets collected

The script runs six collectors in sequence, numbered to match the [n/6] section headers printed during the run:

#	Collector	What it collects
1	Live window	(Live mode only) Real-time AKS pod log tailing and pod status polling during the reproduction window. Skipped in snapshot mode.
2	AKS pods	Pod status, events, and describe output. In snapshot mode, it also captures pod logs (tail-limited, plus previous container logs if crashed).
3	Ingress	Status, events, and tail-limited logs for both ingress controllers (ingress-nginx, ingress-nginx-internal). Always snapshot – never live-tailed.
4	Service Bus dead letters	Dead-letter message counts across all Service Bus topics and subscriptions. Namespaces are discovered dynamically.
5	Deployment markers	Deployment marker table entries for this workspace.
6	Log Analytics	KQL queries for OIS_CL (application diagnostic logs) and Application Insights (AppRequests, AppExceptions, AppTraces), scoped to the exact collection window.

Each collector reports one of the following statuses:

Status	Meaning
OK	Collected successfully.
WARN	Collection attempted but failed (permission issue, timeout, or unreachable resource).
SKIP	Not applicable for this environment (for example, no Service Bus namespaces found).

Output

The script produces a .zip file named omada-debug-<global-prefix>-<timestamp>.zip in the current directory (or --output-dir). The zip contains:

• manifest.json – machine-readable status per collector, exact collection window, and whether the live window was stopped early.
• README.txt – human-readable summary (use --verbose for full detail).
• Individual log and diagnostic files organized by collector.

Nothing is uploaded automatically – you send the file yourself (for example, as an attachment to your support ticket).

Redaction and privacy

The script automatically redacts the following before packaging:

• Connection string credentials (Password=, Pwd=, AccountKey=, SharedAccessKey=, SharedAccessSignature=).
• Bearer tokens and client_secret values.
• SAS signature parameters (sig=).

warning

This redaction is not exhaustive PII scrubbing. Before sending the zip file externally, review its contents to confirm no sensitive data relevant to your organization is included.

Known limitations

• Windows Event Log inside ES pods is not collected. kubectl logs captures stdout/stderr only. The application's own diagnostic stream (OIS_CL in Log Analytics) is the primary signal for ES component errors.
• App Services and Function Apps have no direct log export. Their telemetry is collected via Application Insights instead. This is expected behavior.
• Log Analytics ingestion delay. Even with --ingestion-wait, very recent telemetry may still be missing. If expected entries are absent, re-run the same KQL query manually against the workspace later using the printed collection window, or increase --ingestion-wait.
• CAG VM logs. The Windows CAG VM has no dedicated collector. Its events are captured in OIS_CL and can be filtered by Component_s.

Sending logs to Omada Support

Once the script completes:

1. Review the .zip contents for sensitive data (see Redaction and privacy above).
2. Attach the .zip to your support ticket or use your organization's secure file transfer method.
3. Include a description of what you were doing when you ran the script – which issue you were reproducing, which mode you used, and how long the collection window ran.