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

概要

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

前提条件

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

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

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

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

BUNDLE="perplexity-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=perplexity-integration --since=1h > "$BUNDLE/logs/pods.log"
journalctl -u perplexity-service --since "1 hour ago" > "$BUNDLE/logs/system.log"

# 2. Metrics dump
curl -s localhost:9090/api/v1/query?query=perplexity_requests_total > "$BUNDLE/metrics/requests.json"
curl -s localhost:9090/api/v1/query?query=perplexity_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=perplexity > "$BUNDLE/traces/jaeger.json"

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

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

システマティックな分離

レイヤー別テスト

// Test each layer independently
async function diagnosePerplexityIssue(): Promise<DiagnosisReport> {
  const results: DiagnosisResult[] = [];

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

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

  // Layer 3: TLS handshake
  results.push(await testTLSHandshake('api.perplexity.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) };
}

最小限の再現

// Strip down to absolute minimum
async function minimalRepro(): Promise<void> {
  // 1. Fresh client, no customization
  const client = new PerplexityClient({
    apiKey: process.env.PERPLEXITY_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;
  }
}

メモリとリソース分析

// Detect memory leaks in Perplexity client usage
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 perplexity integration');
    }
  }
}, 60000);

レースコンディション検出

// Detect concurrent access issues
class PerplexityConcurrencyChecker {
  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);
    }
  }
}

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

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

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

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

### 再現手順
1. [手順1]
2. [手順2]

### 期待動作vs実際の動作
- 期待動作: [動作]
- 実際の動作: [動作]

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

### 試行済みの回避策
1. [回避策1] - 結果: [結果]
2. [回避策2] - 結果: [結果]

手順

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

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

ステップ2: システマティックな分離

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

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

最もシンプルな失敗ケースまで削減します。

ステップ4: エビデンス付きでエスカレーション

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

出力

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

エラーハンドリング

問題	原因	解決策
再現できない	レースコンディション	タイミング分析を追加
断続的な障害	タイミング依存	サンプルサイズを増加
有用なログがない	インストルメンテーション不足	デバッグログを追加
メモリ増加	リソースリーク	ヒーププロファイリングを使用

例

クイックレイヤーテスト

# Test each layer in sequence
curl -v https://api.perplexity.com/health 2>&1 | grep -E "(Connected|TLS|HTTP)"

リソース

• Perplexity Support Portal
• Perplexity Status Page

次のステップ

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