FireCrawl 高度なトラブルシューティング

概要

標準的なトラブルシューティングでは解決できない複雑な FireCrawl の問題に対する深いデバッグ技法です。

前提条件

• 本番環境のログとメトリクスへのアクセス
• クラスターへの kubectl アクセス
• ネットワークキャプチャツールが利用可能
• 分散トレーシングの理解

エビデンス収集フレームワーク

包括的なデバッグバンドル

#!/bin/bash
# advanced-firecrawl-debug.sh

BUNDLE="firecrawl-advanced-debug-$(date +%Y%m%d-%H%M%S)"
mkdir -p "$BUNDLE"/{logs,metrics,network,config,traces}

# 1. Extended logs (1 hour window)
kubectl logs -l app=firecrawl-integration --since=1h > "$BUNDLE/logs/pods.log"
journalctl -u firecrawl-service --since "1 hour ago" > "$BUNDLE/logs/system.log"

# 2. Metrics dump
curl -s localhost:9090/api/v1/query?query=firecrawl_requests_total > "$BUNDLE/metrics/requests.json"
curl -s localhost:9090/api/v1/query?query=firecrawl_errors_total > "$BUNDLE/metrics/errors.json"

# 3. Network capture (30 seconds)
timeout 30 tcpdump -i any port 443 -w "$BUNDLE/network/capture.pcap" &

# 4. Distributed traces
curl -s localhost:16686/api/traces?service=firecrawl > "$BUNDLE/traces/jaeger.json"

# 5. Configuration state
kubectl get cm firecrawl-config -o yaml > "$BUNDLE/config/configmap.yaml"
kubectl get secret firecrawl-secrets -o yaml > "$BUNDLE/config/secrets-redacted.yaml"

tar -czf "$BUNDLE.tar.gz" "$BUNDLE"
echo "Advanced debug bundle: $BUNDLE.tar.gz"

体系的な分離

レイヤー別テスト

// 各レイヤーを独立してテスト
async function diagnoseFireCrawlIssue(): Promise<DiagnosisReport> {
  const results: DiagnosisResult[] = [];

  // Layer 1: Network connectivity
  results.push(await testNetworkConnectivity());

  // Layer 2: DNS resolution
  results.push(await testDNSResolution('api.firecrawl.com'));

  // Layer 3: TLS handshake
  results.push(await testTLSHandshake('api.firecrawl.com'));

  // Layer 4: Authentication
  results.push(await testAuthentication());

  // Layer 5: API response
  results.push(await testAPIResponse());

  // Layer 6: Response parsing
  results.push(await testResponseParsing());

  return { results, firstFailure: results.find(r => !r.success) };
}

最小限の再現

// 絶対必要な最小限まで削り詰める
async function minimalRepro(): Promise<void> {
  // 1. Fresh client, no customization
  const client = new FireCrawlClient({
    apiKey: process.env.FIRECRAWL_API_KEY!,
  });

  // 2. Simplest possible call
  try {
    const result = await client.ping();
    console.log('Ping successful:', result);
  } catch (error) {
    console.error('Ping failed:', {
      message: error.message,
      code: error.code,
      stack: error.stack,
    });
  }
}

タイミング分析

class TimingAnalyzer {
  private timings: Map<string, number[]> = new Map();

  async measure<T>(label: string, fn: () => Promise<T>): Promise<T> {
    const start = performance.now();
    try {
      return await fn();
    } finally {
      const duration = performance.now() - start;
      const existing = this.timings.get(label) || [];
      existing.push(duration);
      this.timings.set(label, existing);
    }
  }

  report(): TimingReport {
    const report: TimingReport = {};
    for (const [label, times] of this.timings) {
      report[label] = {
        count: times.length,
        min: Math.min(...times),
        max: Math.max(...times),
        avg: times.reduce((a, b) => a + b, 0) / times.length,
        p95: this.percentile(times, 95),
      };
    }
    return report;
  }
}

メモリとリソース分析

// FireCrawl クライアント使用時のメモリリークを検出
const heapUsed: number[] = [];

setInterval(() => {
  const usage = process.memoryUsage();
  heapUsed.push(usage.heapUsed);

  // Alert on sustained growth
  if (heapUsed.length > 60) { // 1 hour at 1/min
    const trend = heapUsed[59] - heapUsed[0];
    if (trend > 100 * 1024 * 1024) { // 100MB growth
      console.warn('Potential memory leak in firecrawl integration');
    }
  }
}, 60000);

競合状態の検出

// 並行アクセスの問題を検出
class FireCrawlConcurrencyChecker {
  private inProgress: Set<string> = new Set();

  async execute<T>(key: string, fn: () => Promise<T>): Promise<T> {
    if (this.inProgress.has(key)) {
      console.warn(`Concurrent access detected for ${key}`);
    }

    this.inProgress.add(key);
    try {
      return await fn();
    } finally {
      this.inProgress.delete(key);
    }
  }
}

サポートエスカレーションテンプレート

## FireCrawl サポートエスカレーション

**重大度:** P[1-4]
**リクエスト ID:** [エラーレスポンスから取得]
**タイムスタンプ:** [ISO 8601]

### 問題の概要
[1段落の説明]

### 再現手順
1. [ステップ 1]
2. [ステップ 2]

### 予期される動作と実際の動作
- 予期される: [動作]
- 実際: [動作]

### 添付されたエビデンス
- [ ] デバッグバンドル (firecrawl-advanced-debug-*.tar.gz)
- [ ] 最小限の再現コード
- [ ] タイミング分析
- [ ] ネットワークキャプチャ (関連する場合)

### 試行した回避策
1. [回避策 1] - 結果: [成果]
2. [回避策 2] - 結果: [成果]

手順

ステップ 1: エビデンスバンドルの収集

包括的なデバッグスクリプトを実行してすべての関連データを収集します。

ステップ 2: 体系的な分離

各レイヤーを独立してテストして、障害ポイントを特定します。

ステップ 3: 最小限の再現を作成

最も単純な失敗ケースまで削り詰めます。

ステップ 4: エビデンスを添付してエスカレーション

収集したすべてのエビデンスとともにサポートテンプレートを使用します。

出力

• 包括的なデバッグバンドルを収集
• 障害レイヤーを特定
• 最小限の再現を作成
• サポートエスカレーションを送信

エラーハンドリング

問題	原因	解決策
再現できない	競合状態	タイミング分析を追加
間欠的な障害	タイミング依存	サンプルサイズを増加
有用なログがない	計測不足	デバッグログを追加
メモリ増加	リソースリーク	ヒーププロファイリングを使用

例

クイックレイヤーテスト

# 各レイヤーを順に テスト
curl -v https://api.firecrawl.com/health 2>&1 | grep -E "(Connected|TLS|HTTP)"

リソース

• FireCrawl サポートポータル
• FireCrawl ステータスページ

次のステップ

ロードテストについては、firecrawl-load-scale を参照してください。