Release Debugger Agent

Overview

Release Debugging is a capability of Praxis, the Facets AI assistant, that automatically diagnoses and resolves deployment failures. When you encounter a failed deployment, Praxis systematically analyzes logs, configurations, and infrastructure state to identify the root cause and provide actionable solutions.

Key Benefits

Rapid Failure Diagnosis: Identifies root causes in minutes instead of hours
Evidence-Based Analysis: All conclusions based on actual logs and configurations
Multi-Layer Investigation: Checks configuration, permissions, state management, and runtime issues
Clear Action Plans: Provides specific solutions with exact UI navigation steps

How to Access and Use

Click the AI debug icon next to a failed release in the Facets UI Releases tab. This automatically launches Praxis with the deployment context loaded.

You can also ask Praxis directly:

"Why did my deployment fail?"
"Debug this release"
"Investigate deployment ID XYZ"

How Release Debugging Works

When you click the debug icon or ask about a deployment failure, Praxis:

Loads Deployment Context: Automatically receives deployment ID and cluster ID from the UI
Fetches and Analyzes Logs: Downloads complete deployment logs and delegates complex parsing to specialized log-analyzer subagent
Examines Configuration: Checks resource JSON configurations and validates against schemas
Inspects Module Code: Downloads Terraform modules when needed to understand implementation
Checks Runtime State: Uses kubectl to inspect Kubernetes pods, events, and resources
Classifies Error Type: Determines if issue is configuration, permission, state, or operational
Provides Solution: Delivers specific fix with UI navigation or commands

Praxis never guesses - every conclusion is backed by evidence from tools and logs.

Common Error Types

Configuration Errors: Invalid JSON values, schema mismatches, type errors. Praxis validates against schemas and shows exact fixes.

Permission Errors: Missing IAM or RBAC permissions. Praxis identifies exact permissions needed.

State Lock Errors: Terraform state locks from concurrent operations. Praxis provides unlock instructions with UI navigation.

Helm Conflicts: Existing Helm releases blocking deployment. Praxis suggests resolution options.

Kubernetes Timeouts: Pods stuck in Pending, CrashLoopBackOff, or ImagePullBackOff states. Praxis uses kubectl to diagnose.

Module Errors: Bugs in Terraform module code. Praxis downloads modules to analyze and distinguishes between fixable custom modules and standard Facets modules.

Attribute Reference Errors: Invalid resource output references. Praxis discovers valid attributes and provides correct syntax.

Example Interactions

Scenario: Configuration Error Praxis finds a type mismatch in your JSON, validates against the schema, and shows the exact field that needs changing with UI navigation to Resource Center.

Scenario: Permission Issue Praxis identifies a missing IAM permission from logs, specifies the exact permission needed (e.g., rds:CreateDBInstance), and directs you to update it in Secrets and Variables.

Scenario: Pod Crash Praxis uses kubectl to check pod status, reads container logs, identifies the crash reason (e.g., missing environment variable), and provides the fix.

Scenario: State Lock Praxis extracts the Lock ID from error logs and provides step-by-step instructions to unlock via Releases → Ellipsis menu → Unlock State.

Log Analyzer Sub-Agent

For complex log parsing, Praxis delegates to a specialized log-analyzer subagent that understands:

Terraform deployment logs
Kubernetes pod and event logs
Cloud provider API responses
CI/CD pipeline outputs

The subagent extracts structured error summaries with line numbers and evidence trails, making diagnosis faster and more accurate.

Safety and Security

Read-Only Access: Praxis uses read-only tools for investigation. It cannot modify infrastructure directly.

Evidence-Based: All conclusions supported by actual tool outputs - no speculation.

Schema Validation: Before suggesting configuration changes, Praxis validates against Facets schemas.

User-Scoped Permissions: Operates within your Facets and Kubernetes RBAC permissions.

Troubleshooting

Praxis says deployment status is UNKNOWN: Praxis analyzes logs directly to determine actual status when API doesn't provide it.

Suggested fix doesn't work: Share the new error with Praxis. Deployment failures can have multiple layers.

Module analysis fails: Some standard Facets modules cannot be downloaded. Praxis re-examines these as configuration issues.

Can't find the deployment: Provide the deployment ID and cluster ID from the Releases tab.

FAQ

Is this a separate agent from Praxis? No, release debugging is a built-in capability of Praxis that activates when you investigate deployment failures.

Can Praxis fix issues automatically? No. Praxis diagnoses problems and provides step-by-step solutions, but you execute the fixes through the Facets UI or by triggering new releases.

What tools does Praxis use? Praxis uses Facets APIs to fetch logs and configurations, kubectl for Kubernetes inspection, and specialized subagents for log parsing.

Does Praxis have access to my cluster? Praxis uses kubectl with read-only commands (get, describe, logs) for investigation. It cannot make changes.

How do I prevent similar errors? Ask Praxis: "How can I prevent this?" It provides recommendations based on the root cause.