コンテンツにスキップ

Adderトラブルシューティングガイド

Adderトラブルシューティングガイド

Section titled “Adderトラブルシューティングガイド”

このガイドでは、Adderの運用中に発生する一般的な問題を、診断コマンド、原因、解決手順とともに説明します。


chainsync入力プラグインがCardanoノードに接続できない、またはハンドシェイクを完了できない場合は、次の手順で確認します。

  • 症状: ローカルのNode-to-Client(NtC)ソケットへの接続時に、Adderのログに接続拒否またはno such file or directoryが現れます。
  • 原因: 指定したパスにUNIXソケットファイルがないか、Adderを実行するユーザーにソケットの読み取りまたは書き込み権限がありません。
  • 解決:
    1. Cardanoノードが完全に起動し、ソケットファイルを作成したことを確認します。

    2. 設定ファイルの--input-chainsync-socket-pathまたはplugins.input.chainsync.socket-pathに指定したパスを確認します。

    3. ファイルの権限を確認します。

      ターミナルウィンドウ
      ls -la /path/to/cardano-node.socket
  • 症状: 接続は確立しますが、handshake failed: network magic mismatchなどのエラーですぐにプロトコルのハンドシェイクが失敗します。
  • 原因: Adderに設定したネットワークマジックが、実行中のCardanoノードのネットワークマジックと一致していません。たとえば、mainnet用に設定したAdderをpreviewのノードに接続しています。
  • 解決: ネットワーク設定を一致させます。
    • 環境変数で正しいネットワークを設定します。

      ターミナルウィンドウ
      export INPUT_CHAINSYNC_NETWORK=preview
    • または、config.yamlのinput-chainsync-network設定を確認します。

ネットワーク名に対応する値を使わず、ネットワークマジックを直接指定する場合は、--input-chainsync-network-magicまたは対応する入力設定を使用します。ネットワークマジックはネットワーク名より優先されます。

  • 症状: 接続に失敗するか、アドレス解決エラーが発生します。
  • 原因: Node-to-Client(ローカルソケット)とNode-to-Node(リモートTCP/IP)を取り違えています。
  • 解決:
    • ローカルノード接続(NtC)では、ノードのUNIXソケットを--input-chainsync-socket-pathで指定します。TCPでソケットを公開する構成では、--input-chainsync-ntc-tcpとhost:port形式のアドレスを使用します。

    • リモートノード接続(NtN)では、ホストとポート(例: relays-new.cardano-mainnet.iohk.io:3001)を指定し、TCPポート3001に到達できることを確認します。

      ターミナルウィンドウ
      nc -zv relays-new.cardano-mainnet.iohk.io 3001

Adderは設定を、CLIフラグ、環境変数、YAML設定ファイル、デフォルト値の順に評価します。同じ設定を複数の方法で指定した場合は、CLIフラグが最も優先されます。

  • 症状: 環境変数を設定してもAdderの動作が変わりません。
  • 原因: 環境変数名の接頭辞または接尾辞の誤り、あるいは優先順位の高いCLIフラグによる上書きです。
  • 解決:
    • アプリケーション設定にはINPUT_、OUTPUT_、API_、DEBUG_など、登録された環境変数名を使用します。たとえば、--input-chainsync-networkにはINPUT_CHAINSYNC_NETWORKを使用します。環境変数名に製品名の接頭辞は付けません。

    • フィルター設定には、フラグ名ではなくプラグインの種類と名前から生成された環境変数名を使用します。たとえば、--filter-addressにはFILTER_CARDANO_ADDRESSを使用します。

    • シェルで有効な環境変数を確認します。

      ターミナルウィンドウ
      env | grep -E "^(INPUT|OUTPUT|API|DEBUG|SHELLEY_|BYRON_|KUPO_URL)"

--config、--version、--helpなどのコマンド制御用フラグには、対応する環境変数はありません。CLIフラグ、環境変数、YAMLの値が競合していないことも確認します。

B. YAMLファイルが見つからない、または値が不正

Section titled “B. YAMLファイルが見つからない、または値が不正”
  • 症状: Adderがfailed to read configuration fileまたはyaml: unmarshal errorsを出力します。

  • 原因: ファイルパスの誤り、不正なインデント、または整数を要求する項目に文字列を指定するなどの型の不一致です。

  • 解決: YAMLの構文と値の型を確認します。次のコマンドでYAMLファイルの構文を確認できます。

    ターミナルウィンドウ
    python3 -c "import yaml; yaml.safe_load(open('config.yaml'))"

不明なYAMLキーもエラーになります。キー名はコマンドリファレンスに記載されたプラグインの種類、名前、オプションに合わせます。


異なる種類のフィルター(typeとaddressなど)はANDで結合します。同じフィルターに複数の値を指定した場合(address1またはaddress2など)はORで結合します。--filter-poolと--filter-drepを同時に指定した場合だけ、両者はORで結合します。

A. イベントがフィルターを通過しない

Section titled “A. イベントがフィルターを通過しない”
  • 症状: Adderは動作していますが、イベントを出力せず、パイプラインが停止しているように見えます。
  • 原因: 過剰なフィルター、または不正なフィルター入力です。たとえば、ブロックイベントに適用されないアセットポリシーIDでフィルタリングしています。
  • 解決:
    • --filter-policyと--filter-assetはinput.transactionにだけ適用されます。input.blockとinput.governanceはこれらのフィルターを通過します。

    • まずイベントタイプだけでフィルタリングし、イベントが生成されることを確認します。

      ターミナルウィンドウ
      ./adder --filter-type input.transaction
    • 異なる種類のフィルターはすべて同時に満たす必要があります。--filter-poolと--filter-drepの組み合わせだけは、どちらか一方に一致すれば通過します。

  • アドレス: 有効なBech32の支払いアドレスまたはステークアドレスを指定します(例: addr1...、stake1...)。

  • ポリシーID: 28バイトの16進数を文字列で指定します。長さは56文字でなければなりません。

  • DRep ID: Bech32(drep1...またはdrep_script1...)または生の16進ハッシュを指定します。29バイトのBech32ペイロードでは先頭のヘッダーバイトを除去して台帳ハッシュと照合します。

  • 診断: ポリシーIDの長さを確認します。

    ターミナルウィンドウ
    echo -n "2dd15e0efd5c07b6bfbc0cf7fb2f767a50e189d7bfa50e1ef0b87abc" | wc -c

フィルター値をカンマ区切りで指定すると、各値のいずれかに一致したイベントを出力します。Adderは各項目の前後の空白を除去し、空の項目を無視します。


  • 症状: Pushプラグインがfailed to get tokenまたはfailed to read credential fileをログに出力します。

  • 原因: サービスアカウントJSONファイルが存在しない、読み取れない、または有効なGoogleサービスアカウント認証情報ではありません。project_idが空または存在しない場合も起動または設定に失敗します。

  • 解決: サービスアカウントファイルが存在し、読み取り可能で、project_idを含むことを確認します。

    ターミナルウィンドウ
    cat /path/to/service-account.json | grep "project_id"
  • 症状: failed to send message to token...がERRORとして出力されます。

  • 原因: FCM tokenの期限切れ、登録解除、またはFirebaseサービスへの到達不能です。

  • 解決: FCMが返すエラーペイロードを確認します。UNREGISTEREDを示す場合は、クライアントのレジストリから無効なtokenを削除します。

    ターミナルウィンドウ
    curl -X DELETE http://localhost:8080/v1/fcm/<token>

このエンドポイントは/v1のAPIルートグループに属します。<token>は削除する実際のFCM tokenに置き換えます。


A. Webhookの再試行とタイムアウト

Section titled “A. Webhookの再試行とタイムアウト”
  • 症状: Webhookメッセージが遅延するか、配信失敗のエラーが出力されます。
  • 原因: 対象のWebサーバーが遅い、停止している、または成功以外のHTTPステータスコードを返しています。
  • 解決:
    • curlで対象エンドポイントを手動テストし、応答してPOSTペイロードを受け付けることを確認します。

      ターミナルウィンドウ
      curl -H "Content-Type: application/json" -X POST -d '{"type":"test"}' https://your-webhook-url.com
    • 実際に使用するWebhook URLと認証設定を指定します。

      ターミナルウィンドウ
      ./adder --output webhook --output-webhook-url="https://your-webhook-url.com"

Webhookは初回送信を1回行い、デフォルトで最大3回再試行します。一時的な通信障害、HTTP 408、429、5xxでは、デフォルトで1s、2s、4sの指数バックオフを使用します。バックオフの上限は30sです。これらの再試行回数とバックオフは内部動作であり、登録済みのCLIフラグではありません。

有効なRetry-After値は設定済みの最大バックオフまで使用します。最大値を超える待機時間を要求するRetry-Afterはterminal failureとして扱います。再試行対象ではない失敗は直ちにterminal failureになり、再試行回数を使い切ったイベントはexhaustedとして破棄されます。

301、302、303リダイレクトではHTTPクライアントがPOSTをGETに変更し、イベント本文を破棄します。本文を維持するWebhook POSTのリダイレクトには307または308を使用します。リダイレクトは最大10回までです。

  • 症状: Webhook配信がx509: certificate signed by unknown authorityで失敗します。
  • 原因: 対象のWebhookサーバーが自己署名証明書または無効なTLS証明書を使用しています。
  • 解決: ローカルマシンに認証局(CA)証明書をインストールするか、Webhookホストに有効な証明書を設定します。自己署名証明書を使うローカルテストだけでは、--output-webhook-tls-skip-verifyを使用できます。本番環境ではTLS検証を無効にしません。

Webhookのメトリクスと、設定済みAPIリスナーでの確認方法は、ヘルスチェックとAPI診断を参照してください。


設定済みAPIリスナーはGET /healthcheckとGET /metricsを/v1の外側で提供します。デフォルトのリスナーはAPI_ADDRESS=0.0.0.0とAPI_PORT=8080で、環境変数または対応するCLIフラグで変更できます。監視システムだけに公開する場合は、ネットワーク境界でアクセスを制限します。

次のメトリクスで、Webhook配信の試行、最終結果、試行ごとの所要時間を確認します。

ターミナルウィンドウ
curl http://localhost:8080/metrics
メトリクス説明
adder_webhook_http_attempts_total{status_class}Webhookの論理HTTP試行数。status_classは1xx、2xx、3xx、4xx、5xx、network、otherのいずれかです。リダイレクトは最終レスポンスのクラスで1回として数えます。
adder_webhook_delivery_outcomes_total{outcome}Webhookイベントの最終結果。outcomeはsuccess、terminal、exhaustedのいずれかです。
adder_webhook_http_attempt_duration_secondsレスポンス本文の読み取り完了またはリクエスト失敗までの、HTTP試行ごとの所要時間です。

これらのメトリクスには、URL、イベントタイプ、アドレス、ハッシュ、クライアント、その他のユーザーデータをラベルとして使用しません。Adderはメトリクスをプロセス内で集計し、再起動時にリセットします。

ターミナルウィンドウ
curl -i http://localhost:8080/healthcheck

Adderはレスポンスにfailedフィールドを常に含めます。登録済みのヘルスチェッカーがすべて稼働している場合、AdderはHTTP 200を返し、いずれかのチェッカーが稼働していない場合はHTTP 503を返します。Adderは診断情報の有無にかかわらず、このHTTPステータスのプローブ動作を維持します。

ヘルスチェッカーが詳細情報を提供すると、Adderはレスポンスのchecks[]にサニタイズされた情報を追加します。Adderは各チェックにrunningを含め、パイプラインのチェックには次の情報も追加します。

  • uptimeSeconds: パイプラインの稼働時間(秒)。
  • terminalFailure: 回復不能な失敗が発生したかどうか。
  • components[]: パイプラインのコンポーネント一覧。
    • role: input、filter、outputのいずれか。
    • index: コンポーネントのインデックス。
    • state: unknown、starting、running、stopped、failedのいずれか。

Adderはchecks[]にエラー文字列、秘密情報、URL、イベント内容、設定値を含めません。Adderはコンポーネントの診断情報を最大128件に制限します。Adderはchecks[]の詳細状態ではなく、登録済みチェッカーの稼働状態に基づいてfailedとHTTPステータスを決定します。


エラー文字列発生元コンポーネント原因解決
failed to read credential file: open ...: no such file or directoryoutput/pushFCM認証情報のパスが正しくありません。設定のパスがローカルファイルシステムと一致することを確認します。
failed to get token: oauth2: cannot fetch tokenoutput/pushホストがインターネットに接続できないか、Google IAM認証情報が無効です。ネットワーク接続とサービスアカウントの状態を確認します。
invalid intersect point format: expected '<slot>.<hash>'input/chainsync--input-chainsync-intersect-pointに渡した値の形式が不正です。<slot_integer>.<block_hex_hash>形式で指定します。
server returned status: 500output/webhook対象サーバーがリクエストを受信しましたが、内部サーバーエラーになりました。Webhookサーバーのログでエラーの原因を確認します。
failed to parse credential fileoutput/push / internal/configJSON認証情報ファイルに構文エラーまたは不正なJSON形式があります。サービスアカウント認証情報の形式を検証します。
failed to process plugin configinternal/config / plugin設定キーに未認識の型または互換性のない値があります。標準設定のオプション定義に合わせて値の型を修正します。

8. Go 1.26以降でのゴルーチンリークの診断

Section titled “8. Go 1.26以降でのゴルーチンリークの診断”

Adderでメモリリークが発生する場合、到達不能なチャネルやミューテックスなどで停止した孤立ゴルーチンが原因の可能性があります。

Go 1.26以降では、ガベージコレクターを利用して、実行中のコードの他の部分から完全に到達不能になったゴルーチンを特定するリークプロファイラーを使用できます。

リークプロファイラーを有効にする

Section titled “リークプロファイラーを有効にする”

この機能にはGo 1.26以降が必要です。デフォルトでは無効で、goroutineleakprofile実験を有効にしてAdderをビルドする必要があります。

ターミナルウィンドウ
GOEXPERIMENT=goroutineleakprofile go build -o adder ./cmd/adder

注記: 古いGoバージョンでこのフラグを使用すると、コンパイラーはgo: unknown GOEXPERIMENT goroutineleakprofileで失敗します。

プロファイラーを有効にし、debugポートを有効にすると、net/http/pprofのエンドポイントからgoroutine/leakプロファイルを取得できます。

ターミナルウィンドウ
GOEXPERIMENT=goroutineleakprofile ./adder \
--debug-address 127.0.0.1 \
--debug-port 6060
ターミナルウィンドウ
go tool pprof http://localhost:6060/debug/pprof/goroutineleak

DEBUG_ADDRESSとDEBUG_PORTでdebugリスナーを設定します。DEBUG_PORTのデフォルト値は0(無効)です。

  • goroutineとgoroutine/leak: 従来のgoroutineプロファイルはすべてのアクティブなゴルーチンを一覧表示するため、手動での絞り込みが必要です。goroutine/leakプロファイルは到達不能なプリミティブで停止したゴルーチンだけを抽出します。
  • 本番環境での使用: Go 1.26のリークプロファイルは、テスト専用のtesting/synctestパッケージとは異なり、実行時のオーバーヘッドが小さく、本番環境で使用できます。

Doc Holiday logo

Docs authored by Doc Holiday