runbooks

Runbook Development Standards

PURPOSE: Standards for writing and maintaining troubleshooting runbooks with clear procedures and reproducibility.

📋 Runbook Structure

Every runbook must include these sections:

1. Purpose and Scope

# {Feature/Component} Troubleshooting Runbook

## Purpose
Clear statement of what this runbook helps troubleshoot

## Scope
- What issues this covers
- What issues this does NOT cover
- When to use this runbook

2. Preconditions

## Preconditions

### Required Access
- Role: SUPPORT_ENGINEER (or specific role)
- Warehouse: SUPPORT_ENG_POWER
- Database: SNOWHOUSE_IMPORT

### Required Tools
- Snow CLI installed and configured
- Snowhouse connection configured
- GitHub MCP access (optional, for source code review)

### Required Information
- Account locator and deployment
- Time window of the issue
- Error message or symptom
- Request ID, query ID, or session ID (if available)

3. Step-by-Step Procedure

## Investigation Procedure

### Step 1: Identify Account and Deployment
**Purpose**: Determine which deployment to query

**Command**:
```bash
snow sql --query "
SELECT account_name, account_locator, deployment, region, cloud
FROM temp.support_sp_dev.accounts
WHERE name ILIKE '%{ACCOUNT}%' OR locator ILIKE '%{ACCOUNT}%'
" --format=JSON --connection snowhouse

Expected Output:

[{
  "account_name": "CUSTOMER_ACCOUNT",
  "account_locator": "AB12345",
  "deployment": "prod3",
  "region": "us-west-2",
  "cloud": "aws"
}]

Next Steps:

• If found: Note deployment and account_id, proceed to Step 2
• If not found: Verify account locator spelling, check alternate deployments

### 4. Verification
```markdown
## Verification

### Success Indicators
- [ ] Root cause identified
- [ ] Error reproduced or explained
- [ ] Solution tested and confirmed
- [ ] Customer can implement fix

### Validation Queries
```bash
# Verify fix was applied
snow sql --query "SHOW PARAMETERS LIKE 'CLIENT_SESSION_KEEP_ALIVE' IN ACCOUNT" --format=JSON --connection snowhouse

Expected: Parameter value matches recommended setting