デバッグとトラブルシューティング

オンラインで編集する

Standard Edition の問題のトラブルシューティングを行うために、クラスタ情報とデバッグログを収集します。

重要:

セルフホスト型 Standard Edition1.10.3 and earlier versions：

  • オンライン（エアギャップなし）の環境では、`[コマンド名]` などのライフサイクル関連の stanctl コマンド stanctl up のほとんどが実行に失敗します。
  • エアギャップ環境においても、これらの stanctl コマンドは引き続き動作します。

必要な操作：ライフサイクル操作を実行する前に、 1.10.4 以降のバージョンに stanctl アップグレードしてください。

例： 1.10.3 またはそれ以前 stanctl のバージョンを実行しているオンライン展開環境では、バックアップの前に `stop` stanctl down コマンドなど、サービスを停止させるワークフローを実行すると、その後の stanctl up `start` コマンドが失敗するため、そのワークフローは完了しません。 これらの手順を実行する前に、 1.10.4 またはそれ以降のバージョンに stanctl アップグレードしてください。

トラブルシューティングのための診断情報を収集する

オンラインで編集する

( k3s ) 環境における Standard Edition のトラブルシューティングを行うために、diagnostics コマンドを使用して、 Kubernetes、プラットフォーム、ノード、およびデータストアの診断情報を収集します。

コマンドを実行するには、次の構文を使用してください：

stanctl diagnostics [flags]
stanctl debug [flags]    # Alias (identical behavior)
重要： このコマンドを実行するには、クラスタへの接続が確立されている必要があります。

収集が完了すると、このコマンドは生成された診断パッケージの保存先を表示します。

Done!
Diagnostics package ->
<output-dir>
<output-dir>/diagnostics_<YYYYMMDDHHmmss>.tar.gz

出力ディレクトリの動作

--output-dirこのコマンドは、``で指定したディレクトリ内に、``という diagnostics_<YYYYMMDDHHmmss> 名前のタイムスタンプ付きディレクトリを常に作成します。 --output-dirを省略した場合、コマンドは現在の作業ディレクトリを使用します。

コマンドフラグ

以下のフラグは、診断情報の収集動作を制御します。

フラグ 短 タイプ Default 説明
--output-dir -o ディレクトリー 現在の作業ディレクトリー コマンドが、タイムスタンプ付きの診断フォルダと圧縮アーカイブを作成するルートディレクトリ。 ファイルパスではなく、ディレクトリパスを指定してください。
--deep-debug — ブール いいえ 標準的な診断情報の収集後に、追加のディープデバッグスクリプトを実行します。 標準コレクションは常に実行され、追加のスクリプトレイヤーのみを有効にします。
--max-log-lines -l 整数 20000 コンテナごとに収集されるログ行の最大数。 完全なログを収集するには、を に 0 設定してください。
--log-collection-days — 整数 7 収集する過去のログの日数。
--node-collector-image — ストリング 実行時に解決される DaemonSet の node-collector 用コンテナイメージ。 エアギャップ環境やプライベートレジストリ環境では、この値を上書きしてください。
--node-collector-namespace — ストリング デフォルトの名前空間 コマンドが一時的なノードコレクター「 DaemonSet 」を作成および削除する名前空間。
--external-script — 文字列のスライス なし 収集中に、ユーザーが指定した1つ以上のシェルスクリプトを実行します。 複数のスクリプトを、カンマ区切りのリストとして指定します。 たとえば、(--external-script a.sh,b.sh) や、フラグ (--external-script a.sh --external-script b.sh) を繰り返すことで。

継承されたグローバルフラグ

フラグ 説明
--env-file ファイル .env へのパス。 このコマンドは、データストアの認証情報の解決のために、このファイル内の値を診断エンジンに渡します。

収集される情報

診断エンジンは、以下のコレクターを順次実行します。 各コレクターは、その出力をdiagnosticsパッケージ内の専用ディレクトリに書き込みます。

データストアコレクター（ Kafka、 Cassandra、 Elasticsearch、および BeeInstana ）については、 stanctl 設定から認証情報を自動的に読み込みます。

  • クラスタスコープの Kubernetes リソース

    このエンジンは、クラスタスコープの Kubernetes リソースを収集します。これには以下が含まれます：

    • ノード
    • 名前空間
    • ClusterRoles
    • ClusterRoleBindings
    • StorageClasses
    • PersistentVolumes
    • CustomResourceDefinitions (CRD)
    • その他の名前空間を持たないリソース

  • ノードのネットワーク情報

    エンジンは、次のようなノードのネットワーク情報を収集します

    • iptables のルール
    • ルーティング・テーブル
    • ネットワーク・インターフェース
    • sysctl のネットワーク関連パラメータ
    • 接続情報

  • Envoy 診断

    このエンジンは、 Instana ネーム instana-core スペース内の Core ロードバランサー ポッドから、 Envoy の診断情報を収集します。これには以下が含まれます：

    • クラスター統計
    • リスナーの設定
    • 経路
    • 正常性情報

  • 名前空間付き Kubernetes リソース

    このエンジンは、以下のものを含め、すべての Instana ネームスペースにわたる、ネームスペース付きの Kubernetes リソースを収集します

    • ポッド数
    • デプロイメント数
    • StatefulSets
    • サービス
    • ConfigMaps
    • 秘密（機密情報は伏せられています）
    • イベント
    • ReplicaSets
    • DaemonSets
    • PersistentVolumeClaims
    • HorizontalPodAutoscalers
    • カスタムリソース（Core、Unit、 ClickHouseInstallation,、 Kafka、 Elasticsearch など）

  • ノードの診断

    このエンジンは、一時的な DaemonSet を展開して、以下のようなノードレベルの診断情報を収集します

    • CPU
    • メモリー
    • ディスクのトポロジー
    • カーネルおよびOSのバージョン
    • ハードウェア情報
    • マウント・ポイント
    • ディスク使用率
    • sysctl の値
    • dmesg

  • systemdのジャーナルログ

    このエンジンは、以下の項目についてホストレベルの systemd ジャーナルログを収集します：

    • k3s.service
    • 関連するシステムサービス

  • stanctl の設定と保存

    このエンジンは、設定ファイルとストレージの使用状況データを収集 stanctl します。

    設定ファイル：

    • instana.yaml
    • instana-values.yaml
    • dependencies.yaml
    • 状態ファイル
    • stanctl のログ

    Storage Usage:

    • アナリティクス
    • データ
    • メトリック
    • オブジェクト

  • Instana バックエンドの診断

    このエンジンは、および ネーム instana-coreinstana-unit スペースから、 Instana のバックエンド診断情報を収集します。これには以下が含まれます：

    • 健康に関するエンドポイント
    • 内部指標
    • Podのリソース使用状況

  • Kafka 診断

    このエンジンは、 Kafka の診断情報を収集します。これには以下が含まれます：

    • トピック一覧
    • コンシューマー・グループのラグ
    • ブローカー構成
    • Kafka CRステータス
    注： 認証情報は、stanctl の設定から自動的に取得されます。

  • Cassandra 診断

    このエンジンは、 Cassandra の診断情報を収集します。これには以下が含まれます：

    • nodetool status
    • nodetool info
    • 表統計
    • CQLの検証
    注： 認証情報は、stanctl の設定から自動的に取得されます。

  • Elasticsearch 診断

    このエンジンは、 Elasticsearch の診断情報を収集します。これには以下が含まれます：

    • クラスターの正常性
    • インデックスの統計
    • シャードの割り当て
    • Elasticsearch CRステータス
    注： 認証情報は、stanctl の設定から自動的に取得されます。

  • BeeInstana 診断

    このエンジンは、 BeeInstana の診断情報を収集します。これには以下が含まれます：

    • アグリゲーターのログ
    • インジェスターのログ
    • Monconfigのログ
    • BeeInstana CRステータス
    • 内部指標
    注： 認証情報は、stanctl の設定から自動的に取得されます。

  • Helm リリース情報

    このエンジンは、以下のものを含め、すべてのネームスペースにわたる Helm のリリース情報を収集します

    • リリース名
    • チャートのバージョン
    • デプロイメント状況
    • 値（機密情報は伏せられています）

  • 詳細デバッグ用スクリプト

    --deep-debug注： このコレクタは、を指定した場合にのみエンジンによって実行されます。

    エンジンは、より詳細なトラブルシューティングを行うために、厳選されたクラスタ内診断スクリプトセットを実行します。これには通常、拡張データストア診断が含まれます。

パッケージに埋め込まれたメタデータ

SUMMARY.logすべての診断パッケージには、. 内に以下のメタデータが含まれています。

フィールド 説明
Stanctl のバージョン stanctl バイナリ版の実行
エディション 標準（ k3s ）
クラスタモード 単一ノードまたは複数ノード（インストールタイプおよびノード数を含む）
ネットワーク・モード エアギャップ方式（該当する場合のみ記載）

マルチノードの挙動

マルチノード環境では、このコマンドにより、すべてのノードから情報を収集するために、追加の許容値が設定された一時的なノードコレクター（ DaemonSet ）が自動的にデプロイされます。 追加のフラグは必要ありません。

Instana コンポーネントのログレベルを調整する

オンラインで編集する

Instana コンポーネントの音量を調整するには、以下の手順に従ってください：

  1. Core Config ファイルを編集します。例えば、 $HOME/.stanctl/values/instana-core/custom-values.yaml.

  2. CoreまたはUnit CRでコンポーネントのログレベルを設定します。 次の例では、 butler コンポーネントの DEBUG ログレベルが に変更されています：

    componentConfigs:
  - name: butler
    env:
      - name: COMPONENT_LOGLEVEL
        # Possible values are DEBUG, INFO, WARN, ERROR (not case-sensitive)
        value: DEBUG

  3. 次のコマンドを実行して、カスタム値を適用します：

    stanctl backend apply

  4. 次のコマンドを実行してログを表示してください：

    kubectl logs <component name> -n instana-core

    <コンポーネント名> は、トラブルシューティングを行うコンポーネントの名前です。

Secure Sockets Layer（ SSL ）証明書

オンラインで編集する

SSL 証明書に関するサポート対象の構成、制限事項、およびトラブルシューティングの手順について理解する。

ワイルドカード SSL 証明書

ワイルドカード SSL 証明書は、 Instana Standard Edition で使用できます。 一部のワイルドカード設定はサポートされておらず、特定の導入パターンについてはより慎重な検討が必要です。

サンプル・シナリオ

次のような DNS 構造があると仮定します：

  • ワイルドカード証明書： *.company.com

  • Instana バックエンド： instana.company.com

  • エージェント受容体のエンドポイント： agent-acceptor.instana.company.com

  • Instana UI： unit-tenant.instana.company.com

単一レベルのワイルドカードの制限

このシナリオでは、 *.company.com ワイルドカード証明書を使用することはできません。

理由： 仕様上、アスタリスク（**）は DNS の名前において、1つのラベルのみを置き換えることができます。 複数のサブドメインレベルにまたがることはできません。

証明書照合ルール

証明書 *.company.com の一致：

  • www.company.com
  • api.company.com
  • mail.company.com

証明書 *.company.com が一致しません：

  • a.b.company.com
  • dev.api.company.com
  • company.com
注： 各ドット（.）は、 DNS のラベルを区切っています。 ワイルドカードは、ラベルを1つだけ置き換えます。

Instana の導入をサポートするには、以下のいずれかの方法を使用してください：

  • Instana という完全修飾ドメイン名（FQDN）のベースドメインに対して、ワイルドカード証明書を作成します：
    *.instana.company.com
  • 必要なホスト名をすべて記載したSAN証明書を使用してください。
    DNS: api.example.com
DNS: dev.api.example.com
DNS: prod.api.example.com
  • SAN証明書内で複数のワイルドカードエントリを組み合わせる：
    DNS: *.example.com
DNS: *.api.example.com

自己署名証明書を復元する

以前に削除した自己署名型の TLS 証明書を復元することができます。

  1. 既存の TLS シークレットを削除します：
    kubectl delete secret instana-tls -n instana-core
  2. 新しい自己署名証明書を作成する：
    stanctl be apply --core-tls-generate-cert
    結果:
    • 新しい自己署名型 SSL 証明書が生成され、適用されます。
    • TLS Instana エンドポイントでは、暗号化が有効になっています。
    • Chromeや Firefox などの最新のブラウザでは、信頼できる認証局が発行した証明書ではないため、セキュリティ警告が表示されます。
    重要： ブラウザではこの接続が「信頼できない」と表示されますが、すべての通信は暗号化されたままです。

サマリー

  • *.company.com単一レベルのワイルドカード証明書（例：）は、多階層のサブドメインに対応していません。
  • Instana 通常、SAN証明書またはベースドメインのワイルドカード証明書が必要とされます。
  • 必要に応じて、自己署名証明書を安全に再生成できます。その際、ブラウザから警告が表示されることが予想されます。

トラブルシューティング

オンラインで編集する

これらの問題を解決してください。

Instana エージェントがUIに表示されない

オンラインで編集する

リモート監視用に設定されていた Instana エージェントを削除し、セルフ監視用の Instana エージェントをインストールした後、 Instana のUIにエージェントが表示されない場合があります。

エージェントは、ローカルの Instana バックエンドではなく、リモートの Instana バックエンドに接続しようとしている可能性があります。

この問題を解決するには、エージェントをインストールし、バックエンド・エンドポイント・ホストとエージェント・キーを指定します。

stanctl agent apply --agent-cluster-name <cluster-name> --agent-endpoint-host acceptor.instana-core --agent-endpoint-port 8600 --agent-zone-name <zone-name> --agent-key <agent-key-of-local-backend>

Instana Elasticsearch のデータディスクの使用率が85%を超えると、バックエンドが機能しなくなります

オンラインで編集する

Elasticsearch 使用中のディスクの使用率が85%を超えると、データストアは自動的に読み取り専用モードに切り替わります。 これにより、 Instana バックエンドが動作しなくなります。 Elasticsearch のデータディスクの空き容量を確保するか、容量を増やして、正常な動作を回復させてください。 注：他の Instana ディスクでは、同程度の使用率（95%を超えていても）では読み取り専用モードには移行しないため、この問題の理解を難しくしている可能性があります。

この問題を解決するには、次のいずれかの対処を行ってください：
  • Elasticsearch のデータディスクの空き容量を増やす
  • Elasticsearch に割り当てられているディスク容量を増やす
十分な空き容量が確保されると、 Elasticsearch は通常の書き込み処理を再開し、バックエンドは再び正常に動作するようになります。
注： 他の Instana ディスクは、同程度の使用率（95%を超えていても）では読み取り専用モードには移行しないため、トラブルシューティングの際に混乱を招く可能性があります。

Instana Helm のチャートインストールが破損しているため、バックエンドのアップグレードに失敗しました

オンラインで編集する

Instana のバックエンドのアップグレードは、コマンド stanctl backend apply を実行した後に失敗します。 以下のエラーが表示される場合があります。

Error: another operation (install/upgrade/rollback) is in progress

ファイル console.log には、次のようなエントリに似た情報が表示される場合があります：

ts=2025-05-26T12:26:09Z level=INFO msg="upgrading Helm chart" name=instana-core release=instana-core version=1.8.1 namespace=instana-core
ts=2025-05-26T12:26:09Z level=DEBUG msg="preparing upgrade for instana-core"

この問題は、現在のコアチャートの Helm チャートが破損していることを示しています。以下のコマンドを使用してリセットできます：

  1. namespace instana-core から古い Helm チャートシークレットを削除します。
    kubectl delete secret -n instana-core -l owner=helm
  2. バックエンドをアップグレードする。
stanctl up

ホストエージェントがSLESホスト上の Instana バックエンドに接続できない

オンラインで編集する

SUSE Linux Enterprise Server （SLES）15 SP5 のローカルホストに、自己監視用のホストエージェントをインストールした後、エージェントは Instana のバックエンドに自動的に接続しません。

バックエンドにリモートホストとして接続するには、外部エージェント URL を使用する必要があります。

以下のコマンドを使用します。

stanctl agent apply --agent-endpoint-host agent-acceptor.<base_domain> --agent-endpoint-port 8443

Kafka pods show CrashLoopBackOff のステータス

オンラインで編集する

Kafka Instana のバックエンドホストがシャットダウンした後、podが再起動しません。 KafkaCrashLoopBackOff ポッドのステータスが表示される場合があります。

この問題を解決するには、 Instana のバックエンドを再起動してください。

  1. バックエンドをシャットダウンします。
    stanctl down
  2. バックエンドを開始します。
    stanctl up

バックエンドが再始動した後、 Kafka ポッドの状況を確認します。

kubectl get pods --all-namespaces | grep kafka

Kafka ポッドの状況が Runningと表示されるはずです。

Instana のバックアップおよび復元後、スケジュールされた合成テストが実行されない

オンラインで編集する

Instana のバックエンドおよびエージェントのデータが復元された後、スケジュールされたSyntheticテストが実行されません。

この問題を解決するには、インストールされているクラスターで synthetic-pop-controller ポッドを再始動します。

Standard Edition RHEL へのインストール 9.3 が失敗する

オンラインで編集する

Red Hat® Enterprise Linux® 9.3 iptables を使用します 1.8.8.

RHEL 9.3 に Standard Edition をインストールする場合、iptables 1.8.8 の影響でインストールに失敗する可能性があります。

この問題を回避するには、ホストを RHEl 9.4 にアップグレードし、iptables もバージョン 1.8.10 にアップグレードしてください。

Standard Edition でのアップグレードに失敗しました 1.9.x

オンラインで編集する

Standard Edition 1.9.x を新しいバージョンにアップグレードすると、次のエラーが発生する場合があります：

Error: installation failed for prerequisite app coredns: Unable to continue with install: ConfigMap "coredns" in namespace "kube-system" exists and cannot be imported into the current release: invalid ownership metadata; label validation error: missing key "app.kubernetes.io/managed-by": must be set to "Helm"; annotation validation error: missing key "meta.helm.sh/release-name": must be set to "coredns"; annotation validation error: missing key "meta.helm.sh/release-namespace": must be set to "kube-system"

この問題を解決するには、コマンド stanctl up を再度実行してください。

アップグレード中に「CPUが不足しています」または「メモリが不足しています」というエラーが発生する

オンラインで編集する

リソースが限られているシングルノードの K3s 環境、または一時的な容量の追加が不可能な環境において、アップグレード中に以下のいずれかの問題が発生する可能性があります：

  • 次のようなエラーなど"Insufficient CPU"または"Insufficient memory"
  • ポッドがPending状態

デフォルトの RollingUpdate 戦略では、アップグレード中に新旧両方のPodを同時に実行するために、一時的な追加リソースが必要となります。 リソースが限られているシステムでは、全体的な使用率が低く見えても、この要件によって利用可能なCPUやメモリ容量を上回ってしまうことがあります。

この問題を解決するには、アップグレード中に追加の容量を必要としない「更新戦略の再作成」を使用してください：
stanctl up --core-update-strategy=Recreate

更新戦略の詳細については、 「アップグレードのための更新戦略の設定」 を参照してください

注:

「Recreate」戦略では、アップグレード処理中に数分間の短いダウンタイムが発生します。 このトレードオフは、通常、本番環境以外や、ハードウェアの容量を増強することが困難なシステムにおいては許容できるものです。

Systemd はデフォルトの作業ディレクトリを設定しません

オンラインで編集する

systemd サービスによって起動された stanctl 場合、systemd はそれ自体では作業ディレクトリを設定しません。 作業ディレクトリを指定しない場合、systemd は. /からサービスを実行します。 この操作 stanctl により、サービスがroot以外のユーザーを使用している場合でも、クラスタデータや Kubernetes の設定 .stanctlファイルなどのファイルが誤った場所（多くの場合 / 、または /root/）に作成される可能性があります。

この問題を軽減するには、ユーザーの正しいホームディレクトリにファイルを作成するように、systemd サービスに次の WorkingDirectory= 行を追加する必要があります。 例えば、 WorkingDirectory=/home/instana。

ライセンスを更新できません

オンラインで編集する

この stanctl license update コマンドを実行すると、次のエラーメッセージが表示され、コマンドが失敗する場合があります：

...
no dependency found: 'instana-core'
...

ライセンスを更新するには、以下のコマンドを実行してください：

stanctl license download --sales-key=<your-key>
stanctl backend apply

Instana Node.jsのディスク容量不足により、バックエンドのアップグレードに失敗しました

オンラインで編集する

ノードでディスク容量が逼迫している場合、 Instana のバックエンドのインストールまたはアップグレードが失敗する可能性があります。

症状

次のような症状が1つ以上現れることがあります：
  • バックエンドのインストールまたはアップグレードに失敗しました。
  • ポッドは保留中です。
  • 一部のワークロードでは、次のような現象が見られます ContainerStatusUnknown。

原因

インストール、アップグレード、またはエアギャップ環境からのパッケージインポート中は、コンテナイメージやアーティファクトが処理されるため、ディスク使用量が一時的に増加します。 ノードのディスク容量が不足した場合、 Kubernetes は DiskPressure 状態を設定し、新しいPodの起動を阻止します。

検証

  1. ノードの状態を確認するには、次のコマンドを実行してください：
    kubectl describe node <node-name>

    「条件」セクションで、「 DiskPressure 」にチェックを入れます。

  2. ディスクの使用状況を確認するには、次のコマンドを実行してください：
    df -h

    ディスクの使用率が容量の限界に近い、あるいは上限に達しているかどうかを確認してください。

解決方法

この問題を解決するには、以下のいずれかの操作を行ってください：
  • 使用していないコンテナイメージや不要なファイルを削除して、ディスク容量を解放してください。
  • ノードのストレージ容量を増やす。

リカバリー

ディスク領域を解放した後もワークロードが 状態 ContainerStatusUnknown のままの場合は、ノードを再起動してください。 再起動が完了したら、インストールまたはアップグレードを再度実行してください。

ライセンスが無効か、または存在しません

オンラインで編集する

ライセンスが無効であるか、存在しない場合、バックエンドはエージェントの接続をブロックします。

このような状況が発生したとき

  • インポートされたライセンスは無効です。
  • Instana オペレーターは、Groundskeeperバックエンドにライセンスを適用できません。

トラブルシューティングの方法

  1. コア・シークレット内の「Sales Key」が、ユニット・シークレット内のライセンス文字列と一致していることを確認してください。 異なる場合は、正しい販売キーを使用してライセンスを再ダウンロードしてください。
  2. Instana のオペレーターログを確認し、ライセンスのインポートエラーがないか確認してください：
    kubectl logs -n instana-operator deployment/instana-operator --tail=100
  3. Groundskeeperのバックエンドコンポーネント、Podのステータス、およびログを確認してください：
    kubectl get pods -n instana-core | grep groundskeeper
  4. それでもライセンスの状態が「無効」と表示される場合は、 IBM サポートまでお問い合わせください。

「Fatal glibc error: CPU does not support x86‑64‑v2” 」というエラーが表示され、インストールに失敗します

オンラインで編集する

症状

を実行すると stanctl install、インストールが初期段階で失敗し、次のようなエラーが表示されます：
Fatal glibc error: CPU does not support x86-64-v2

この障害は通常、すべてのコンポーネントがインストールされる前に発生し、 Cassandra や Kafka などのサービスが起動できなくなる原因となります。

原因

このエラーは、オペレーティングシステムが x86‑64‑v2 命令セットを検出できないことを示しています。 最も一般的な原因は、仮想マシンのCPU設定で必要なCPUフラグが有効になっていないことであり、これは多くの場合、レガシー互換性の設定が原因です。

解決方法

VMware および vSphere の環境では、この問題は通常、古いバージョンの仮想 CPU アーキテクチャを選択したり、命令セットを制限する CPU 互換モードを有効にしたりすることが原因で発生します。 この問題を解決するには、次のようにします。
  • 仮想マシンを設定する際は、レガシーCPU互換性プロファイルを使用しないでください。
  • CPUのマスキングが有効になっていないことを確認してください。
  • 「拡張 vMotion 互換性（EVC）」が有効になっている場合は、 x86‑64‑v2 命令をサポートするレベルに設定されていることを確認してください。
  • 仮想マシンの電源を切り、CPUの設定を更新してください。
  • 必要に応じて、CPU設定を更新して仮想マシンを再作成してください。
変更を適用した後、インストールを再実行する前に、ゲストOS上で必要なCPUフラグが表示されていることを確認してください。

サポートに連絡してください

オンラインで編集する

問題が解決しない場合は、 IBM のサポートまでご連絡ください。 作成したアーカイブ・ファイルをサポート・チームに提供します。