🔧 Troubleshooting - CSA in-a-Box¶

Comprehensive troubleshooting guides for Cloud Scale Analytics in-a-box, covering diagnostic procedures, error resolution, and Azure support escalation paths.

📋 Table of Contents¶

• Overview
• Troubleshooting Framework
• Service-Specific Guides
• Common Issues
• Diagnostic Tools
• Support Escalation
• Related Resources

🎯 Overview¶

This section provides systematic troubleshooting guidance for all Cloud Scale Analytics components, including Azure Synapse Analytics, Azure Data Lake Storage, Azure Data Factory, and related services.

Quick Navigation¶

🔍 Troubleshooting Framework¶

Systematic Approach¶

Follow this standardized troubleshooting workflow for all issues:

graph TD
    A[Issue Detected] --> B{Issue Category?}

    B -->|Service Failure| C[Service Troubleshooting]
    B -->|Performance| D[Performance Analysis]
    B -->|Security/Access| E[Security Troubleshooting]
    B -->|Data Quality| F[Data Validation]

    C --> G[Collect Diagnostics]
    D --> G
    E --> G
    F --> G

    G --> H[Analyze Logs & Metrics]
    H --> I{Root Cause Found?}

    I -->|Yes| J[Apply Resolution]
    I -->|No| K[Escalate to Support]

    J --> L{Issue Resolved?}
    L -->|Yes| M[Document Solution]
    L -->|No| K

    K --> N[Create Support Ticket]
    N --> O[Provide Diagnostics]

    style A fill:#ff6b6b
    style M fill:#51cf66
    style K fill:#ffd43b
    style N fill:#ff8787

Troubleshooting Phases¶

🔥 Service-Specific Guides¶

Azure Synapse Analytics¶

Comprehensive troubleshooting for Synapse workspace components:

Cross-Service Issues¶

⚠️ Common Issues¶

Quick Reference Guide¶

Access common error patterns and solutions:

Error Code Categories¶

graph LR
    A[Error Codes] --> B[4xx: Client Errors]
    A --> C[5xx: Server Errors]
    A --> D[Custom: Service-Specific]

    B --> E[401: Authentication]
    B --> F[403: Authorization]
    B --> G[404: Not Found]

    C --> H[500: Internal Error]
    C --> I[503: Service Unavailable]
    C --> J[504: Timeout]

    D --> K[Synapse Errors]
    D --> L[Storage Errors]
    D --> M[Pipeline Errors]

    style A fill:#339af0
    style B fill:#ffd43b
    style C fill:#ff6b6b
    style D fill:#a78bfa

🛠️ Diagnostic Tools¶

Azure Native Tools¶

Common Diagnostic Commands¶

Azure CLI¶

# Check resource health
az synapse workspace show --name <workspace-name> --resource-group <rg-name>

# View activity logs
az monitor activity-log list --resource-group <rg-name> --offset 1h

# Check service health
az rest --method get --url "https://management.azure.com/subscriptions/{subscription-id}/providers/Microsoft.ResourceHealth/events?api-version=2022-10-01"

PowerShell¶

# Get workspace status
Get-AzSynapseWorkspace -Name <workspace-name> -ResourceGroupName <rg-name>

# Check diagnostic settings
Get-AzDiagnosticSetting -ResourceId <resource-id>

# View recent errors
Get-AzActivityLog -ResourceGroupName <rg-name> -StartTime (Get-Date).AddHours(-1) | Where-Object {$_.Level -eq "Error"}

KQL Queries¶

// Recent errors across all services
AzureDiagnostics
| where TimeGenerated > ago(1h)
| where Level == "Error"
| summarize Count=count() by Resource, Category, OperationName
| order by Count desc

// Failed Synapse operations
SynapseIntegrationPipelineRuns
| where Status == "Failed"
| where TimeGenerated > ago(24h)
| project TimeGenerated, PipelineName, RunId, ErrorMessage
| order by TimeGenerated desc

📊 Diagnostic Data Collection¶

Essential Information Checklist¶

Before opening a support ticket, collect the following:

Automated Collection Script¶

# Comprehensive diagnostics collection script
param(
    [Parameter(Mandatory=$true)]
    [string]$WorkspaceName,

    [Parameter(Mandatory=$true)]
    [string]$ResourceGroupName,

    [Parameter(Mandatory=$false)]
    [int]$HoursBack = 24
)

$outputPath = ".\diagnostics_$(Get-Date -Format 'yyyyMMdd_HHmmss')"
New-Item -ItemType Directory -Path $outputPath -Force

# Workspace details
Get-AzSynapseWorkspace -Name $WorkspaceName -ResourceGroupName $ResourceGroupName |
    ConvertTo-Json -Depth 10 | Out-File "$outputPath\workspace.json"

# Activity logs
$startTime = (Get-Date).AddHours(-$HoursBack)
Get-AzActivityLog -ResourceGroupName $ResourceGroupName -StartTime $startTime |
    ConvertTo-Json -Depth 10 | Out-File "$outputPath\activity_logs.json"

# Diagnostic settings
$workspace = Get-AzSynapseWorkspace -Name $WorkspaceName -ResourceGroupName $ResourceGroupName
Get-AzDiagnosticSetting -ResourceId $workspace.Id |
    ConvertTo-Json -Depth 10 | Out-File "$outputPath\diagnostic_settings.json"

Write-Host "Diagnostics collected in: $outputPath"

🚨 Support Escalation¶

When to Escalate¶

Escalate to Azure Support when:

• ✅ Issue persists after following troubleshooting guides
• ✅ Service-level issues affecting multiple components
• ✅ Data loss or corruption suspected
• ✅ Security incident requiring immediate attention
• ✅ Performance degradation without clear cause

Escalation Path¶

graph TD
    A[Issue Identified] --> B{Can Self-Resolve?}

    B -->|Yes| C[Follow Troubleshooting Guide]
    B -->|No| D{Severity?}

    D -->|Sev A: Critical| E[Immediate Support Ticket]
    D -->|Sev B: High| F[High Priority Ticket]
    D -->|Sev C: Medium| G[Standard Ticket]

    C --> H{Resolved?}
    H -->|Yes| I[Document Solution]
    H -->|No| D

    E --> J[24/7 Support Response]
    F --> K[Business Hours Response]
    G --> K

    J --> L[Azure Engineer Assigned]
    K --> L

    L --> M[Collaborative Troubleshooting]
    M --> N{Resolved?}

    N -->|Yes| I
    N -->|No| O[Escalate to Product Team]

    style E fill:#ff6b6b
    style I fill:#51cf66
    style O fill:#ffd43b

Support Ticket Guidelines¶

Severity Definitions¶

Creating Effective Support Tickets¶

Include the following information:

1. Problem Summary
2. Clear, concise description
3. Business impact statement

4. Affected users/services

5. Timeline

6. When did issue start?
7. When was it first detected?

8. Any related changes?

9. Diagnostic Data

10. Error messages (full text)
11. Resource IDs
12. Activity logs

13. Screenshots

14. Troubleshooting Performed

15. Steps already taken
16. Results of each step

17. Current workarounds

18. Expected vs Actual

19. What should happen
20. What actually happens
21. Reproduction steps

Support Resources¶

📚 Related Resources¶

Internal Documentation¶

External Resources¶

💡 Best Practices¶

Proactive Troubleshooting¶

1. Monitoring
2. Configure comprehensive monitoring
3. Set up meaningful alerts

4. Review dashboards regularly

5. Documentation

6. Document all configurations
7. Maintain runbooks

8. Record known issues and solutions

9. Testing

10. Validate changes in non-production
11. Perform regular DR testing

12. Test monitoring and alerting

13. Maintenance

14. Keep systems updated
15. Review and optimize regularly
16. Clean up unused resources

💡 Tip: Bookmark this page and the service-specific guides for quick access during troubleshooting scenarios.

Last Updated: 2025-12-09 Version: 1.0.0