AppFolio 디버그 번들
개요
이 디버그 번들은 AppFolio 부동산 관리 API 통합에서 진단 증거를 수집하여 지원 에스컬레이션 및 근본 원인 분석에 사용합니다. 속성, 세입자, 작업 지시 엔드포인트에 대한 API 연결성, 클라이언트 자격 증명 쌍을 사용한 인증 상태, 통합 파이프라인의 최근 오류 로그, SDK 버전 정보를 캡처합니다. 결과 tarball은 지원 엔지니어가 라이브 환경에 접근하지 않고도 연결 실패, 인증 거부, 데이터 동기화 문제를 진단하는 데 필요한 모든 정보를 제공합니다.
필수 조건
curl,jq,tar설치APPFOLIO_CLIENT_ID및APPFOLIO_CLIENT_SECRET구성 (기본 인증 쌍)APPFOLIO_BASE_URL을 스택 API 베이스로 설정 (예:https://yourcompany.appfolio.com/api/v1)
지침
- 인시던트 승인을 받고 영향을 받은 시간 범위, 포트폴리오, 안전한 읽기 프로브를 정의합니다. 단순히 사용 가능하다는 이유로 세입자, 임대, 지불, 또는 원시 로그 본문을 수집하지 마십시오.
- 구성 상태, 공급자 상태/지연 시간, 속도 제한 헤더, 패키지 버전만 포함된 번들을 생성하고 인증 정보는 argv에 남기지 마십시오.
- 공유하기 전에 모든 파일을 검토하고, 아카이브를 암호화하거나 승인된 지원 채널을 사용하며, 인시던트 정책에 따라 로컬 복사본을 삭제합니다.
- 증거에 민감한 레코드가 필요한 경우 중단하고, 이 범용 디버그 번들을 확장하는 대신 별도 승인된 최소 내보내기를 요청합니다.
디버그 수집 스크립트
#!/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'
}
# 환경 확인
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"
# API 연결 메타데이터만 — 이 번들에 API 본문을 절대 기록하지 않습니다.
echo "=== API Health ===" > "$BUNDLE/api-health.txt"
probe properties >> "$BUNDLE/api-health.txt"
# 작업 지시 엔드포인트 프로브
echo "=== Work Orders ===" > "$BUNDLE/work-orders.txt"
probe work_orders >> "$BUNDLE/work-orders.txt"
# 세입자 엔드포인트 프로브
echo "=== Tenants ===" > "$BUNDLE/tenants.txt"
probe tenants >> "$BUNDLE/tenants.txt"
# 로그 인벤토리만; 원시 로그에는 세입자 및 재무 데이터가 포함될 수 있습니다.
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"
# 속도 제한 헤더
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"
# 패키지 버전
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"
번들 분석
tar -xzf debug-appfolio-*.tar.gz
cat debug-appfolio-*/environment.txt # 자격 증명이 설정되었는지 확인
cat debug-appfolio-*/api-health.txt # HTTP 상태 및 지연 시간 확인
cat debug-appfolio-*/rate-limits.txt # 제한되지 않았는지 확인
jq '.errors' debug-appfolio-*/work-orders.txt 2>/dev/null # 오류 페이로드 파싱
일반적인 문제
| 증상 | 번들에서 확인할 항목 | 해결 방법 |
|---|---|---|
| 모든 엔드포인트에서 401 | environment.txt에 client ID/secret이 NOT SET으로 표시 | 환경 변수에 APPFOLIO_CLIENT_ID 및 APPFOLIO_CLIENT_SECRET 설정 |
| 세입자에서 403 Forbidden | tenants.txt에 HTTP 403 | 스택 API 범위 누락; AppFolio 파트너 포털에서 세입자 읽기 권한 요청 |
| 429 Too Many Requests | rate-limits.txt에 retry-after 헤더 표시 | 백오프하고 지수 재시도 구현; AppFolio는 분당 120회 요청 허용 |
| 작업 지시 시간 초과 | api-health.txt에 30초 이상 시간 표시 | per_page 매개변수 축소; updated_since로 필터링하여 결과 집합 좁힘 |
| 빈 속성 목록 | api-health.txt가 [] 반환 | APPFOLIO_BASE_URL이 올바른 포트폴리오를 가리키는지 확인; 속성 그룹 필터 확인 |
| SSL 인증서 오류 | api-health.txt에 curl SSL 오류 표시 | CA 번들 업데이트: sudo update-ca-certificates; 프록시 설정 확인 |
출력
- 검토 가능하고 수정된 구성 존재 여부, 엔드포인트 상태 및 지연 시간, 속도 제한 헤더, 로그 인벤토리, 종속성 메타데이터 번들
- 세입자, 지불, 원시 애플리케이션 레코드 대신 인시던트 범위와 민감한 데이터 제외 사항을 명시하는 지원 핸드오프 영수증
- 필수 증거를 안전하게 수집할 수 없는 경우 실패-폐쇄 결정
오류 처리
프로브 실패는 실패한 프로브의 증거로 처리하고, 더 큰 응답을 캡처하거나 자격 증명 제어를 우회하는 권한으로 간주하지 않습니다. 401/403의 경우 관리되는 클라이언트 구성을 자격 증명 소유자와 확인하고, 429의 경우 속도 헤더를 보존하고 추가 프로브를 중단하며, 5xx 또는 시간 초과의 경우 수정된 타이밍/상태 증거만 수집하고 공급자 상태 페이지를 확인합니다. 지원팀에 특정 세입자 또는 지불 레코드가 필요한 경우, 자체 보존 및 접근 제어가 있는 별도 승인된 최소 내보내기를 사용합니다.
예제
프로덕션 동기화 시간 초과의 경우 영향을 받은 시간 범위와 하나의 속성 안전 읽기 프로브를 포함하는 번들을 생성합니다. 상태/지연 시간, 속도 헤더, 종속성 버전, 로그 파일 메타데이터가 포함되어 있지만 응답 본문, 자격 증명, 세입자, 또는 재무 데이터가 없는지 확인합니다. 아카이브를 승인된 암호화된 지원 채널에 업로드하기 전에 검토합니다. 검토에서 원시 페이로드 또는 비밀이 발견되면 아카이브를 삭제하고, 적절히 순환시키며, 에스컬레이션 전에 최소화된 번들을 재생성합니다.
자동화된 상태 확인
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,
};
}
리소스
다음 단계
appfolio-rate-limits를 참조하세요.