Debugging and Troubleshooting¶

You can debug and troubleshoot deployments in Omnistrate by leveraging the tools and features described below. These capabilities provide you with detailed visibility into each step of the deployment process, enabling you to identify, diagnose, and resolve issues efficiently.

Debugging Tools Overview¶

Omnistrate provides debugging tools to help you diagnose and resolve deployment issues:

Debug Events¶

Omnistrate's Debug Events feature provides real-time, detailed insights into your deployments, allowing you to quickly pinpoint and resolve issues by offering a transparent view of each operation's progress and status.

How Debug Events Works¶

For each instance operation—such as create, modify, upgrade, start, stop, or delete—Omnistrate launches a dedicated workflow to carry out the task. This workflow moves through several defined stages, including bootstrap, storage, network, compute, deployment, and monitoring. Within each stage, actions are tracked as individual debug events in chronological order, giving a precise view of each action's execution status. This structure enables you to monitor the workflow's progression step-by-step and quickly locate the root cause of any issues.

Debug Events Example Scenarios¶

When a workflow encounters an issue, such as an invalid instance type parameter, debug events identify the specific error within the workflow. This detailed view enables you to diagnose and resolve issues swiftly, ensuring minimal disruption.

By utilizing Omnistrate's Debug Events, you can streamline issue resolution, improve operational efficiency, and ensure a smoother service experience.

Instance Debug¶

For most day-to-day Helm, Terraform, Compose, and Operator troubleshooting, start with the instance debug view:

omnistrate-ctl instance debug <instance-id>

Use it to inspect the instance DAG, select the failing resource, and review resource-specific runtime details. The interactive view has a Resource Details tab for the deployment topology and a Metrics tab for Grafana dashboard metadata when metrics are enabled.

This is the primary place to look for:

• Workflow events for each resource
• Application logs for Compose, Helm, Terraform, and Operator resources when log streams are available
• Metrics dashboard access and published dashboard details when metrics are enabled
• Rendered Helm values and Helm client logs
• Terraform progress, rendered files, output, plan previews, execution logs, and operation history
• Compose deployment API parameters and deployment output parameters
• Operator deployment API parameters, deployment output parameters, and Operator CRD outputs

For non-interactive automation, use JSON output:

omnistrate-ctl instance debug <instance-id> --output json

If you only need the metrics dashboard details, use:

omnistrate-ctl instance dashboard <instance-id>

Resource Debug Coverage¶

Helm Troubleshooting Checklist¶

For Helm-based SaaS Products, most repeated failures fall into a small set of categories. Start with omnistrate-ctl instance debug <instance-id> and work through the following:

1. Confirm the rendered chart values match what you expect.
2. Read the Helm client logs for hook failures, timeouts, or Kubernetes API validation errors.
3. Review app logs for workload-level startup or readiness failures.
4. Check whether Jobs, hooks, Services, or load balancers are stuck in a pending state.
5. Look for leftover CRDs, finalizers, or namespaced resources if create or delete workflows keep failing.
6. Revisit Helm runtime flags such as wait, waitForJobs, skipCRDs, upgradeCRDs, and timeoutNanos if the chart behavior does not match the release lifecycle you need.

For runtime flag details, see Helm Charts Runtime Configuration.

If you changed chart inputs or rendered artifacts, publish a new Plan version instead of repeatedly restarting the same workflow. See Workflows.

Compose Troubleshooting Checklist¶

For Compose-based SaaS Products, use omnistrate-ctl instance debug <instance-id> to open the Compose resource and work through the following:

1. Review app logs for container startup, health check, or dependency errors.
2. Confirm deployment API parameters resolved to the expected runtime values.
3. Confirm deployment output parameters contain the values other resources or customers expect.
4. Check workflow events to identify whether the failure happened during bootstrap, storage, network, compute, deployment, or monitoring.
5. Use the Metrics tab or omnistrate-ctl instance dashboard <instance-id> to verify dashboard access when metrics are enabled.

Operator Troubleshooting Checklist¶

For Operator-based SaaS Products, use omnistrate-ctl instance debug <instance-id> to open the Operator resource and work through the following:

1. Review app logs from the operator-managed workload.
2. Confirm deployment API parameters resolved to the expected custom resource inputs.
3. Inspect Operator CRD outputs and exported deployment output parameters.
4. Check workflow events to separate Omnistrate orchestration errors from operator reconciliation errors.
5. Use the Metrics tab or omnistrate-ctl instance dashboard <instance-id> to verify dashboard access when metrics are enabled.

Terraform Troubleshooting Checklist¶

For Terraform-based SaaS Products, use omnistrate-ctl instance debug <instance-id> to inspect rendered artifacts, terraform plan output, apply logs, provider configuration, and exported outputs. Work through the following:

1. Confirm rendered Terraform files contain the expected system parameters, API parameters, secrets, and dependency outputs.
2. Confirm the captured terraform plan matches the resources you expected to create, update, or delete.
3. Review apply logs for IAM permissions, quotas, unavailable regions or SKUs, networking inputs, and resource name conflicts.
4. Verify provider configuration and credentials, especially for BYOC, control-plane-targeted Terraform, and Nebius authentication.
5. Confirm Terraform outputs are available to downstream Helm, Operator, Kustomize, or Terraform resources.

This visibility allows you to diagnose issues without needing direct access to the Terraform state or the execution environment. If a Terraform operation fails, the plan output helps you understand what Terraform attempted, and the apply logs show where it failed.

For the full Terraform-specific workflow, see Terraform Troubleshooting.