kafka-connector-review

Kafka Connect の構成レビュー

Kafka Connect コネクターの構成をレビューし、よくある設定ミスを確認します。コネクターは JSON/YAML で定義され、言語に依存しません。

対象環境：$ARGUMENTS

ワークフロー

このチェックリストをコピーして、進捗を記録してください。

Connector Review Progress:
- [ ] Step 1: List all connectors
- [ ] Step 2: Inspect each connector's configuration
- [ ] Step 3: Validate configurations against plugin schemas
- [ ] Step 4: Audit for common misconfigurations
- [ ] Step 5: Generate report

1. すべてのコネクターを一覧表示する（ステータスとタスク状態を含む）
2. 各コネクターの構成を詳細に確認する
3. プラグインのスキーマに照らして構成を検証する
4. よくある設定ミスを監査する
5. 現在の構成と推奨構成を添えて、調査結果を報告する

ステップ 1：すべてのコネクターを一覧表示する

Lenses MCP の list_kafka_connectors ツールを使用して、以下の情報を含むすべてのコネクターを取得します。

• コネクター名、クラス、タイプ（ソース／シンク）
• ステータス（RUNNING、PAUSED、FAILED、UNASSIGNED）
• タスクの状態と数
• クラスター情報

以下をただちに指摘します。

• 重大：FAILED 状態のコネクター
• 重大：FAILED 状態のタスク
• 警告：明確な理由がないのに PAUSED 状態のコネクター

期待される出力：すべてのコネクターの名前、クラス、ステータス、タスク状態の一覧。

検証：コネクターが返されない場合は、Connect クラスターが構成されていないことを報告して終了します。

ステップ 2：構成を確認する

Lenses MCP の get_kafka_connector_target_definition ツールを使用して、各コネクターの完全な構成 YAML を取得します。

ステップ 3：構成を検証する

Lenses MCP の validate_connector_configuration ツールを使用して、各コネクターの構成を対応するプラグインのスキーマに照らして検証します。これにより、以下を検出できます。

• 必須構成フィールドの不足
• 無効な構成値
• 型の不一致

ステップ 4：よくある設定ミスを監査する

エラー処理

• 重大：errors.tolerance=all が設定されているのに errors.deadletterqueue.topic.name がない（メッセージが通知なく破棄されます）
• 警告：errors.tolerance がない（デフォルトは none で、エラーが発生するとコネクターが停止します）
• 警告：errors.log.enable=true がない（エラーがログに記録されません）
• 提案：DLQ メタデータを充実させるため、errors.deadletterqueue.context.headers.enable=true を追加します

コンバーター

• 警告：key.converter または value.converter がトピックのシリアライズ形式と一致しない
• 警告：構造化データに org.apache.kafka.connect.storage.StringConverter を使用している（Avro/JSON/Protobuf コンバーターを使用してください）
• 警告：スキーマが想定される場合に schemas.enable の設定がない

変換（SMT）

• 警告：デバッグが困難になる可能性がある、複雑な変換チェーン（SMT が 3 個を超える）
• 提案：複雑な変換には Kafka Streams または ksqlDB の利用を検討します
• 変換クラス名が有効で、正しい順序になっていることを確認します

タスク数

• 警告：スループットの高いコネクターで tasks.max=1 を設定している（並列処理が制限されます）
• 提案：ソースコネクターでは、tasks.max をソースのパーティション構成に合わせます
• 提案：シンクコネクターでは、tasks.max をトピックのパーティション数に合わせます

接続と再試行

• 警告：外部システムと連携するコネクターに再試行の構成がない
• 警告：接続タイムアウトの設定がない
• 提案：パフォーマンス調整のため、consumer.override.* または producer.override.* を明示的に設定します

命名規則

• 提案：コネクター名に一貫したパターンを使用します（例：{source/sink}-{system}-{entity}）

成功基準

定量的

• コネクター関連のクエリの 90% で起動する（表現を変えた 10～20 個の例でテスト）
• MCP ツールの呼び出し 10 回未満でレビューを完了する
• プラグインのスキーマで報告された検証エラーを 100% 検出する

定性的

• 失敗したコネクターがステータス概要でただちに指摘される
• エラー処理の不備（DLQ の欠如、通知のない破棄）が必ず特定される
• コネクターの運用担当者と開発者のどちらにとっても役立つレポートになる

例

例 1：定期的なコネクターレビュー

ユーザーの発言：「ステージング環境のすべてのコネクターをレビューしてください」

アクション：

1. ステータスとともにすべてのコネクターを一覧表示します
2. 各コネクターの設定を確認して検証します
3. よくある設定ミスを監査します 結果：すべてのコネクターを対象に、優先度を付けた指摘事項を含む完全なレポート

例 2：失敗したコネクターの調査

ユーザーの発言：「シンクコネクターが失敗しています。原因を確認してもらえますか？」

アクション：

1. コネクターを一覧表示し、FAILED 状態のものを特定します
2. 失敗したコネクターの完全な設定を取得します
3. プラグインのスキーマに照らして設定を検証します
4. よくある問題（DLQ、コンバーター、エラー処理）を確認します 結果：具体的な失敗原因の診断と修正手順

例 3：単一コネクターの詳細調査

ユーザーの発言：「elasticsearch-sink コネクターの設定をレビューしてください」

アクション：

1. 指定されたコネクターのターゲット定義を取得します
2. プラグインのスキーマに照らして検証します
3. エラー処理、コンバーター、タスク数を監査します 結果：単一のコネクターに焦点を当てたレポート

トラブルシューティング

コネクターが返されない

原因：環境に Kafka Connect クラスターが設定されていないか、コネクターがデプロイされていません。 解決策：Lenses UI で Connect クラスターが存在することを確認します。get_deployment_targets で利用可能な Connect クラスターを確認します。

不明なプラグインとして検証に失敗する

原因：コネクタープラグインのクラスが Connect クラスターにインストールされていません。 解決策：不足しているプラグインを報告します。これはデプロイ上の問題であり、設定の問題ではありません。

コネクターが RUNNING と表示されるが、タスクが FAILED になっている

原因：コネクターフレームワークは実行中ですが、個々のタスクでエラーが発生しています。 解決策：各タスクのステータスを確認します。よくある原因として、認証の失敗、ネットワークの問題、外部システムとのスキーマの不一致があります。

出力形式

## Connector Review Report

### Environment: {name}

### Connector Status Overview
| Connector | Class | Status | Tasks | Failed Tasks |
|-----------|-------|--------|-------|-------------|
| name | class | RUNNING | 3/3 | 0 |

### Critical (must fix)
- [connector-name] Description of the issue
  Current: {current config} | Recommended: {recommended config}

### Warning (should fix)
- [connector-name] Description of the issue
  Current: {current config} | Recommended: {recommended config}

### Validation Errors
- [connector-name] {field}: {validation error message}

### Suggestion (consider improving)
- [connector-name] Description of the suggestion
  Recommendation: {how to improve}

### Summary
- X connectors reviewed
- Y critical issues found
- Z warnings found
- Failed connectors: N
- Failed tasks: M