Pacote de Depuração AppFolio
Visão Geral
Este pacote de depuração coleta evidências de diagnóstico de integrações com a API de gerenciamento de propriedades AppFolio para escalonamento de suporte e análise de causa raiz. Ele captura a conectividade da API nos endpoints de propriedades, inquilinos e ordens de serviço, o status de autenticação usando pares de credenciais do cliente, logs de erro recentes de pipelines de integração e informações de versão do SDK. O tarball resultante fornece aos engenheiros de suporte tudo o que precisam para diagnosticar falhas de conectividade, rejeições de autenticação e problemas de sincronização de dados sem exigir acesso direto ao seu ambiente.
Pré-requisitos
curl,jq,tarinstaladosAPPFOLIO_CLIENT_IDeAPPFOLIO_CLIENT_SECRETconfigurados (par de autenticação básica)APPFOLIO_BASE_URLdefinido para a base da sua API Stack (ex.:https://yourcompany.appfolio.com/api/v1)
Instruções
- Obtenha aprovação do incidente e defina a janela de tempo afetada, o portfólio e as sondas de leitura segura; não colete corpos de inquilinos, contratos de locação, pagamentos ou logs brutos meramente porque estão disponíveis.
- Crie o pacote com estado de configuração redigido, status/latência do provedor, cabeçalhos de limite de taxa e versões de pacotes apenas; mantenha as credenciais fora de argv.
- Revise cada arquivo antes de compartilhar, criptografe ou use o canal de suporte aprovado para o arquivo e exclua a cópia local de acordo com a política de incidentes.
- Se as evidências exigirem registros sensíveis, pare e obtenha uma exportação mínima aprovada separadamente, em vez de expandir este pacote de depuração de uso geral.
Script de Coleta de Depuração
#!/bin/bash
set -euo pipefail
BUNDLE="debug-appfolio-$(date +%Y%m%d-%H%M%S)"
mkdir -p "$BUNDLE"
NETRC_FILE="$(mktemp)"
trap 'rm -f "$NETRC_FILE"' EXIT
chmod 600 "$NETRC_FILE"
APPFOLIO_HOST="${APPFOLIO_BASE_URL#https://}"
APPFOLIO_HOST="${APPFOLIO_HOST%%/*}"
printf 'machine %s login %s password %s\n' "$APPFOLIO_HOST" \
"$APPFOLIO_CLIENT_ID" "$APPFOLIO_CLIENT_SECRET" > "$NETRC_FILE"
probe() {
endpoint="$1"
curl -s -o /dev/null -w 'HTTP %{http_code} in %{time_total}s\n' \
--netrc-file "$NETRC_FILE" "${APPFOLIO_BASE_URL}/${endpoint}?per_page=1" \
|| printf 'UNREACHABLE\n'
}
# Verificação de ambiente
echo "=== Environment ===" > "$BUNDLE/environment.txt"
echo "Base URL: ${APPFOLIO_BASE_URL:-NOT SET}" >> "$BUNDLE/environment.txt"
echo "Client ID: ${APPFOLIO_CLIENT_ID:+SET (redacted)}" >> "$BUNDLE/environment.txt"
echo "Client Secret: ${APPFOLIO_CLIENT_SECRET:+SET (redacted)}" >> "$BUNDLE/environment.txt"
echo "Node: $(node -v 2>/dev/null || echo 'not installed')" >> "$BUNDLE/environment.txt"
echo "Timestamp: $(date -u)" >> "$BUNDLE/environment.txt"
# Metadados de conectividade da API apenas — nunca escreva corpos de API neste pacote.
echo "=== API Health ===" > "$BUNDLE/api-health.txt"
probe properties >> "$BUNDLE/api-health.txt"
# Sonda do endpoint de ordens de serviço
echo "=== Work Orders ===" > "$BUNDLE/work-orders.txt"
probe work_orders >> "$BUNDLE/work-orders.txt"
# Sonda do endpoint de inquilinos
echo "=== Tenants ===" > "$BUNDLE/tenants.txt"
probe tenants >> "$BUNDLE/tenants.txt"
# Inventário de logs apenas; logs brutos podem conter dados de inquilinos e financeiros.
echo "=== Log Inventory ===" > "$BUNDLE/app-logs.txt"
find /var/log/appfolio-sync -maxdepth 1 -type f -printf '%f %s bytes\n' 2>/dev/null \
|| echo "No sync logs found" >> "$BUNDLE/app-logs.txt"
# Cabeçalhos de limite de taxa
echo "=== Rate Limits ===" > "$BUNDLE/rate-limits.txt"
curl -sI --netrc-file "$NETRC_FILE" \
"${APPFOLIO_BASE_URL}/properties?per_page=1" 2>/dev/null | grep -i "x-rate\|retry-after\|x-ratelimit" >> "$BUNDLE/rate-limits.txt" || echo "No rate limit headers" >> "$BUNDLE/rate-limits.txt"
# Versões de pacotes
echo "=== Dependencies ===" > "$BUNDLE/deps.txt"
npm ls 2>/dev/null | grep -i appfolio >> "$BUNDLE/deps.txt" || echo "No AppFolio npm packages found" >> "$BUNDLE/deps.txt"
tar -czf "$BUNDLE.tar.gz" "$BUNDLE" && rm -rf "$BUNDLE"
echo "Bundle: $BUNDLE.tar.gz"
Analisando o Pacote
tar -xzf debug-appfolio-*.tar.gz
cat debug-appfolio-*/environment.txt # Verifica se as credenciais estão definidas
cat debug-appfolio-*/api-health.txt # Verifica status HTTP e latência
cat debug-appfolio-*/rate-limits.txt # Confirma que não está com limitação
jq '.errors' debug-appfolio-*/work-orders.txt 2>/dev/null # Analisa payloads de erro
Problemas Comuns
| Sintoma | Verificar no Pacote | Correção |
|---|---|---|
| 401 em todos os endpoints | environment.txt mostra client ID/secret NOT SET | Defina APPFOLIO_CLIENT_ID e APPFOLIO_CLIENT_SECRET no ambiente |
| 403 Forbidden em inquilinos | tenants.txt HTTP 403 | Escopo da API Stack ausente; solicite permissão de leitura de inquilinos no portal de parceiros AppFolio |
| 429 Muitas Requisições | rate-limits.txt mostra cabeçalho retry-after | Recue e implemente retry exponencial; AppFolio permite 120 req/min |
| Timeout em ordens de serviço | api-health.txt mostra tempo > 30s | Reduza o parâmetro per_page; filtre por updated_since para restringir o conjunto de resultados |
| Lista de propriedades vazia | api-health.txt retorna [] | Verifique se APPFOLIO_BASE_URL aponta para o portfólio correto; verifique filtros de grupo de propriedades |
| Erro de certificado SSL | api-health.txt mostra erro SSL do curl | Atualize o pacote CA: sudo update-ca-certificates; verifique configurações de proxy |
Saída
- Um pacote revisável e redigido de presença de configuração, status e latência de endpoint, cabeçalhos de limite de taxa, inventário de logs e metadados de dependências
- Um recibo de transferência de suporte que nomeia o escopo do incidente e as exclusões de dados sensíveis, em vez de empacotar registros de inquilinos, pagamentos ou aplicativos brutos
- Uma decisão de falha fechada quando as evidências necessárias não podem ser coletadas com segurança
Tratamento de Erros
Trate uma falha de sonda como evidência de uma sonda falha, não como permissão para capturar respostas maiores ou ignorar controles de credenciais. Para 401/403, verifique a configuração do cliente gerenciado com o proprietário da credencial; para 429, preserve os cabeçalhos de taxa e pause as sondas adicionais; para 5xx ou timeout, colete apenas as evidências redigidas de tempo/status e verifique a página de status do provedor. Se o suporte precisar de um registro específico de inquilino ou pagamento, use uma exportação mínima aprovada separadamente com seus próprios controles de retenção e acesso.
Exemplos
Para um timeout de sincronização de produção, crie um pacote cobrindo a janela de tempo afetada e uma sonda de leitura segura de propriedades. Confirme que contém status/latência, cabeçalhos de taxa, versões de dependências e metadados de arquivos de log — mas nenhum corpo de resposta, credencial, inquilino ou dado financeiro. Revise o arquivo antes de enviá-lo para o canal de suporte criptografado aprovado. Se a revisão encontrar um payload bruto ou segredo, exclua o arquivo, rotacione conforme apropriado e regenere um pacote minimizado antes do escalonamento.
Verificação Automática de Saúde
async function checkAppFolioHealth(): Promise<{
status: string;
latencyMs: number;
endpoints: Record<string, number>;
}> {
const baseUrl = process.env.APPFOLIO_BASE_URL;
const creds = Buffer.from(
`${process.env.APPFOLIO_CLIENT_ID}:${process.env.APPFOLIO_CLIENT_SECRET}`
).toString("base64");
const headers = { Authorization: `Basic ${creds}` };
const endpoints = ["properties", "tenants", "work_orders"];
const results: Record<string, number> = {};
const start = Date.now();
for (const ep of endpoints) {
const res = await fetch(`${baseUrl}/${ep}?per_page=1`, { headers });
results[ep] = res.status;
}
return {
status: Object.values(results).every((s) => s === 200) ? "healthy" : "degraded",
latencyMs: Date.now() - start,
endpoints: results,
};
}
Recursos
Próximos Passos
Consulte appfolio-rate-limits.