デバッグガイド

このガイドでは、ローカル環境とAWS環境の両方でのMBC CQRS Serverlessアプリケーションのデバッグテクニックを説明します。

ローカル開発環境でのデバッグ

NestJS REPLの使用

REPL（Read-Eval-Print Loop）を使用してインタラクティブにデバッグできます：

npm run repl

REPLでは以下のことができます：

// Get a service instance
const todoService = await get(TodoService);

// Call methods directly
await todoService.findAll();

// Inspect module dependencies
debug(TodoModule);

VS Codeでのデバッグ

.vscode/launch.json 設定を作成します：

{
  "version": "0.2.0",
  "configurations": [
    {
      "type": "node",
      "request": "launch",
      "name": "Debug Serverless Offline",
      "program": "${workspaceFolder}/node_modules/.bin/serverless",
      "args": ["offline", "start"],
      "cwd": "${workspaceFolder}/infra-local",
      "env": {
        "NODE_ENV": "development"
      },
      "console": "integratedTerminal"
    },
    {
      "type": "node",
      "request": "launch",
      "name": "Debug Tests",
      "program": "${workspaceFolder}/node_modules/.bin/jest",
      "args": ["--runInBand", "--watchAll=false"],
      "console": "integratedTerminal"
    }
  ]
}

Serverless Offlineでのデバッグ

Serverless Offlineで詳細なログを有効にします：

SLS_DEBUG=* npm run offline:sls

またはserverless.ymlに追加：

custom:
  serverless-offline:
    httpPort: 3000
    lambdaPort: 3002
    printOutput: true

コンソールロギング

デバッグを容易にするために構造化ログを使用します：

import { Logger } from '@nestjs/common';

@Injectable()
export class TodoService {
  private readonly logger = new Logger(TodoService.name);

  async create(dto: CreateTodoDto): Promise<Todo> {
    this.logger.debug(`Creating todo: ${JSON.stringify(dto)}`);

    try {
      const result = await this.commandService.publish(/* ... */);
      this.logger.log(`Todo created: ${result.id}`);
      return result;
    } catch (error) {
      this.logger.error(`Failed to create todo: ${error.message}`, error.stack);
      throw error;
    }
  }
}

DynamoDBのデバッグ

テーブル内容の表示

DynamoDB LocalでAWS CLIを使用：

# List tables
aws dynamodb list-tables --endpoint-url http://localhost:8000

# Scan table
aws dynamodb scan \
  --table-name your-table-name \
  --endpoint-url http://localhost:8000

# Query by partition key
aws dynamodb query \
  --table-name your-table-name \
  --key-condition-expression "pk = :pk" \
  --expression-attribute-values '{":pk":{"S":"TODO#123"}}' \
  --endpoint-url http://localhost:8000

DynamoDB Streams

ストリームレコードをデバッグ：

@EventHandler(DataSyncEvent)
export class DebugHandler implements IEventHandler<DataSyncEvent> {
  async execute(event: DataSyncEvent): Promise<void> {
    console.log('Stream record:', JSON.stringify(event.record, null, 2));
    console.log('Event name:', event.eventName);
    console.log('New image:', event.newImage);
    console.log('Old image:', event.oldImage);
  }
}

CloudWatch Logs

ログの表示

AWS CLIを使用してログをテール：

# Find log group
aws logs describe-log-groups --log-group-name-prefix /aws/lambda/your-app

# Tail logs
aws logs tail /aws/lambda/your-app-dev-handler --follow

# Filter logs
aws logs filter-log-events \
  --log-group-name /aws/lambda/your-app-dev-handler \
  --filter-pattern "ERROR"

Log Insightsクエリ

高度なクエリにはCloudWatch Logs Insightsを使用：

# Find errors
fields @timestamp, @message
| filter @message like /ERROR/
| sort @timestamp desc
| limit 100

# Analyze cold starts
fields @timestamp, @message, @duration
| filter @type = "REPORT"
| stats avg(@duration), max(@duration), count(*) by bin(1h)

# Find slow requests
fields @timestamp, @message, @duration
| filter @duration > 3000
| sort @duration desc
| limit 20

構造化ログ分析

構造化ログを使用している場合：

fields @timestamp, level, message, context
| filter level = "error"
| sort @timestamp desc

Step Functionsのデバッグ

実行履歴

AWSコンソールで実行を表示：

Step Functions → ステートマシンに移動
ステートマシンを選択
実行をクリック
ステップステータス付きのビジュアルワークフローを表示

イベント履歴

AWS CLIを使用：

# List executions
aws stepfunctions list-executions \
  --state-machine-arn arn:aws:states:REGION:ACCOUNT:stateMachine:YourMachine

# Get execution details
aws stepfunctions describe-execution \
  --execution-arn arn:aws:states:REGION:ACCOUNT:execution:YourMachine:execution-id

# Get execution history
aws stepfunctions get-execution-history \
  --execution-arn arn:aws:states:REGION:ACCOUNT:execution:YourMachine:execution-id

CloudWatchでのデバッグ

Step Functionsでログを有効化：

const stateMachine = new sfn.StateMachine(this, 'StateMachine', {
  definition: definition,
  logs: {
    destination: new logs.LogGroup(this, 'StateMachineLogGroup'),
    level: sfn.LogLevel.ALL,
  },
  tracingEnabled: true, // Enable X-Ray
});

API Gatewayのデバッグ

アクセスログの有効化

const api = new apigateway.HttpApi(this, 'Api');

const stage = api.defaultStage?.node.defaultChild as apigateway.CfnStage;
stage.accessLogSettings = {
  destinationArn: logGroup.logGroupArn,
  format: JSON.stringify({
    requestId: '$context.requestId',
    ip: '$context.identity.sourceIp',
    method: '$context.httpMethod',
    path: '$context.path',
    status: '$context.status',
    latency: '$context.responseLatency',
    error: '$context.error.message',
  }),
};

エンドポイントのテスト

詳細出力付きでcurlを使用：

curl -v -X POST https://your-api.execute-api.region.amazonaws.com/todos \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"title": "Test Todo"}'

X-Rayトレーシング

X-Rayの有効化

// In your main Lambda handler
import * as AWSXRay from 'aws-xray-sdk';

// Instrument AWS SDK
const AWS = AWSXRay.captureAWS(require('aws-sdk'));

カスタムセグメントの追加

import * as AWSXRay from 'aws-xray-sdk';

async function processOrder(orderId: string): Promise<void> {
  const segment = AWSXRay.getSegment();
  const subsegment = segment?.addNewSubsegment('ProcessOrder');

  try {
    subsegment?.addAnnotation('orderId', orderId);
    // Process order
    subsegment?.addMetadata('result', { status: 'success' });
  } catch (error) {
    subsegment?.addError(error);
    throw error;
  } finally {
    subsegment?.close();
  }
}

一般的なデバッグパターン

リクエスト相関

リクエストを追跡するために相関IDを追加：

@Injectable()
export class CorrelationMiddleware implements NestMiddleware {
  use(req: Request, res: Response, next: NextFunction) {
    const correlationId = req.headers['x-correlation-id'] || uuidv4();
    req['correlationId'] = correlationId;
    res.setHeader('x-correlation-id', correlationId);
    next();
  }
}

環境変数のデバッグ

// Log environment on startup (development only)
if (process.env.NODE_ENV === 'development') {
  console.log('Environment:', {
    NODE_ENV: process.env.NODE_ENV,
    AWS_REGION: process.env.AWS_REGION,
    DATABASE_URL: process.env.DATABASE_URL ? '[SET]' : '[NOT SET]',
  });
}

条件付きデバッグ

const DEBUG = process.env.DEBUG === 'true';

function debugLog(message: string, data?: any): void {
  if (DEBUG) {
    console.log(`[DEBUG] ${message}`, data ? JSON.stringify(data, null, 2) : '');
  }
}

トラブルシューティングチェックリスト

問題をデバッグする際：

ローカルで再現: ローカル環境で再現できますか？
ログを確認: CloudWatch Logsでエラーを確認
設定を確認: 環境変数と設定を確認
分離テスト: コンポーネントを個別にテスト
権限を確認: IAMロールとポリシーを確認
最近の変更を確認: 最後に動作した時から何が変わりましたか？
依存関係を確認: すべてのサービスは正常ですか？

次のステップ

よくある問題 - 既知の問題と解決策
モニタリングとロギング - 包括的なモニタリングをセットアップ

ローカル開発環境でのデバッグ​

NestJS REPLの使用​

VS Codeでのデバッグ​

Serverless Offlineでのデバッグ​

コンソールロギング​

DynamoDBのデバッグ​

テーブル内容の表示​

DynamoDB Streams​

CloudWatch Logs​

ログの表示​

Log Insightsクエリ​

構造化ログ分析​

Step Functionsのデバッグ​

実行履歴​

イベント履歴​

CloudWatchでのデバッグ​

API Gatewayのデバッグ​

アクセスログの有効化​

エンドポイントのテスト​

X-Rayトレーシング​

X-Rayの有効化​

カスタムセグメントの追加​

一般的なデバッグパターン​

リクエスト相関​

環境変数のデバッグ​

条件付きデバッグ​

トラブルシューティングチェックリスト​

次のステップ​