トラブルシューティング

オンラインで編集

生成AIの可観測性に関して、以下の問題が発生する可能性があります。

接続エラー

問題: アプリケーションログに Instana への接続エラーが表示される。

解決策：

エージェントモードの場合：

  • Instana エージェントが実行されていることを確認してください。
  • エージェントのログでエラーを確認してください。
  • エージェントのホストとポートが正しいことを確認してください。
  • アプリケーションとエージェント間のネットワーク接続を確認してください。

エージェントレスモードの場合：

  • バックエンドエンドポイント URL が正しいことを確認してください。
  • ポート4317がアクセス可能であることを確認してください。
  • ファイアウォールルールがアウトバウンド接続を許可していることを確認してください。
  • Ensure x-instana-key が正しいことを確認してください。

TLS の設定を確認してください：

  • エージェントモードの場合：通常 OTEL_EXPORTER_OTLP_INSECURE=true
  • エージェントレスモードの場合：通常 OTEL_EXPORTER_OTLP_INSECURE=false
  • これらが Instana の設定と一致することを確認してください

コスト指標は表示されません

問題: トレースやその他のメトリクスは表示されるが、コストメトリクスが表示されない。

解決策：

  1. ダッシュボードで価格設定が構成されていることを確認してください：

    • Go GenAI の可観測性 > 料金設定構成
    • 使用しているモデルに対して価格設定が行われていることを確認してください。
    • モデルIDは完全に一致する必要があります（大文字小文字を区別します）。

  2. モデルIDの形式を確認してください：

    • アプリケーションが正しいモデルIDを報告していることを確認してください。
    • モデルIDは価格設定構成の形式と一致する必要があります。例：「 gpt-4 」であり、「 GPT-4 」や「 gpt4 」ではありません。

  3. プラットフォーム固有の価格設定を設定している場合は、プラットフォームが一致しているかどうかを確認してください。

    • 価格設定が、いずれのプラットフォームにも適用されるか、特定のプラットフォームに適用されるかを確認してください。

  4. データの伝播を待機:

    • 価格設定を構成した後、コスト指標が表示されるまで数分かかる場合があります。
    • 更新されたメトリクスを確認するために、いくつかの新しいリクエストを生成してください。
注記： その他の指標（レイテンシ、トークン数、エラー率）は、価格設定構成がなくても表示されます。

トレースとメトリクスは表示されません

問題: GenAI の可観測性ダッシュボードにトレースまたはメトリクスが表示されません。

解決策:

  1. が正しく設定されている OTEL_RESOURCE_ATTRIBUTES="INSTANA_PLUGIN=genai" か確認してください。

    • これが最も一般的な問題です。この属性がなければ、 Instana はあなたのデータを生成AIテレメトリとして認識しません。
    • 環境変数または設定ファイルを確認してください。
    • この変数を追加した後、アプリケーションを再起動してください。

  2. Instana エンドポイントの設定を確認してください

    • が正しい Instana エージェントまたはバックエンドを指している TRACELOOP_BASE_URL かどうかを確認してください。
    • エージェントモードでは、エージェントが実行中でありアクセス可能であることを確認してください。
    • エージェントレスモードの場合、バックエンドエンドポイント URL が正しいことを確認してください。

  3. 認証を確認する

    • in TRACELOOP_HEADERS が正しい x-instana-key かどうかを確認してください。
    • キーがあなたの環境に対する権限を持っていることを確認してください。

  4. アプリケーションログを確認する：

    • OpenTelemetry 接続エラーを確認してください。
    • 認証の失敗を確認してください。
    • ネットワーク接続に問題がないことを確認してください。

Instana との競合 Python センサー

問題: Instana Python のセンサーと Traceloop を同時に使用すると、以下のエラーが発生する可能性があります。

AttributeError: 'SimpleSpanProcessor' object has no attribute 'record_span'

考えられる原因： Instana、 Python センサー、およびTraceloopは互いに競合する異なる計測手法を採用しています。 両方の項目を同時に実行すると、計測の競合が発生します。

生成AIアプリケーションでは、Traceloopのみを使用し、 Instana Python センサーを有効にしないでください。

この問題を解決するには、次の手順を試してください：

  1. Instana のインポートを削除するか、コメントアウトしてください。
    # import instana # Remove this line
  2. Traceloopの初期化のみを保持する。
    from traceloop.sdk import Traceloop
Traceloop.init(
    disable_batch=True
)
  3. アプリケーションを再始動します。
注： 生成AIアプリケーションの計測には、Traceloopのみを使用してください。 これらのアプリケーションに対して、 Instana センサー経由で Python トレースを有効にしないでください。

Python バージョンが互換性ありません

問題: IBM watsonx パッケージ（例: ibm-watsonx-ai または ibm-watson-machine-learning）をインストールすると、pandas でコンパイルエラーが発生する可能性があります:
error: too few arguments to function '_PyLong_AsByteArray'

考えられる理由: Python 3.13 は、 C API に互換性のない変更を導入しました。この変更は、 IBM watsonx パッケージで使用されている pandas および関連する依存関係とまだ互換性がありません。 これらのパッケージの一部はpandasへの内部依存関係を持ち、このpandasバージョンが正常に動作するには Python、 3.11、または 3.12 が必要です。

この問題を解決するには、次の手順を試してください：

  • Python をインストールしてください 3.11 または 3.12
    • Ubuntu / Debian :
      sudo apt update
sudo apt install software-properties-common -y
sudo add-apt-repository ppa:deadsnakes/ppa -y
sudo apt update
sudo apt install python3.11 python3.11-venv python3.11-dev -y
    • Fedora/RHEL/CentOS （dnfを使用）の場合：
      sudo dnf install python3.11 python3.11-devel -y
    • 古いシステム（yumを使用している場合）:
      sudo yum install epel-release -y
sudo yum install https://repo.ius.io/ius-release-el7.rpm -y
sudo yum install python311 python311-devel -y
    • Python 3.11 で仮想環境を作成する Python （ 3.11 または 3.12 ）をインストールした後、仮想環境を作成します。
      # Create virtual environment with Python 3.11
python3.11 -m venv venv

# Activate the virtual environment
source venv/bin/activate

# Upgrade pip
pip install --upgrade pip

# Install IBM Watson packages
pip install ibm-watsonx-ai ibm-watson-machine-learning langchain-ibm traceloop-sdk
    • Python のバージョンを確認してください。 正しい Python バージョンを使用していることを確認するには：
      python --version

      Python のバージョンは、 3.11.x または 3.12.x でなければなりません。

OTel データコレクターは現在も使用中です

生成AI向け OTel データコレクター（ODCG）は廃止されました。 ODCGはもはや必要ありません。 ODCGを削除するには、次の手順を完了してください：

  1. アプリケーション設定を更新してください

    主な変更点は、` INSTANA_PLUGIN=genai resource`属性の追加と、独立したメトリクスエンドポイントの削除です。

    • エージェントモード（ Instana エージェント経由でのデータ送信）
      古い構成は次の例に示されています。
      export TRACELOOP_BASE_URL=<instana-agent-host>:4317
export TRACELOOP_HEADERS="x-instana-key=<agent-key>,x-instana-host=<host>"
export TRACELOOP_METRICS_ENDPOINT=<odcg-host>:8000
export TRACELOOP_METRICS_ENABLED=trueexport TRACELOOP_LOGGING_ENABLED=true
export OTEL_EXPORTER_OTLP_INSECURE=true
      新しい構成は次の例に示されています。
      export OTEL_RESOURCE_ATTRIBUTES="INSTANA_PLUGIN=genai"
export TRACELOOP_BASE_URL=<instana-agent-host>:4317
export TRACELOOP_HEADERS="x-instana-key=<agent-key>,x-instana-host=<host>"
export TRACELOOP_METRICS_ENABLED=trueexport TRACELOOP_LOGGING_ENABLED=true
export OTEL_EXPORTER_OTLP_INSECURE=true
      以下の項目が変更されました。

      • OTEL_RESOURCE_ATTRIBUTES="INSTANA_PLUGIN=genai" 生成AIテレメトリとしてデータを処理するために追加されます

      • TRACELOOP_METRICS_ENDPOINT メトリクスがトレースと同じエンドポイントを通るように削除されます

    • エージェントレスモード（データを直接 Instana バックエンドに送信する場合）

      古い構成は次の例に示されています。
      export TRACELOOP_BASE_URL=<instana-otlp-endpoint>:4317 
export TRACELOOP_HEADERS="x-instana-key=<agent-key>,x-instana-host=<host>" 
export TRACELOOP_METRICS_ENDPOINT=<odcg-host>:8000 
export TRACELOOP_METRICS_ENABLED=true export TRACELOOP_LOGGING_ENABLED=true 
export OTEL_EXPORTER_OTLP_INSECURE=false
      新しい構成は次の例に示されています。
      export OTEL_RESOURCE_ATTRIBUTES="INSTANA_PLUGIN=genai" 
export TRACELOOP_BASE_URL=<instana-otlp-endpoint>:4317 
export TRACELOOP_HEADERS="x-instana-key=<agent-key>,x-instana-host=<host>" 
export TRACELOOP_METRICS_ENABLED=true export TRACELOOP_LOGGING_ENABLED=true 
export OTEL_EXPORTER_OTLP_INSECURE=false
      以下の項目が変更されました。

      • OTEL_RESOURCE_ATTRIBUTES="INSTANA_PLUGIN=genai" 生成AIテレメトリとしてデータを処理するために追加されます。

      • TRACELOOP_METRICS_ENDPOINT メトリクスがトレースと同じエンドポイントを通るように削除されます

  2. 価格設定構成を移行してください。 モデルの価格設定は、設定ファイルではなく Instana のUIを通じて管理されます。

    1. 現在の価格設定構成を確認してください。

      OTel データコレクターを使用する場合、以下の例に類似したファイル prices.properties が表示されます。

      openai.gpt-4.input=0.03 
openai.gpt-4.output=0.06 
openai.gpt-3.5-turbo.input=0.0015 
openai.gpt-3.5-turbo.output=0.002 
anthropic.claude-2.input=0.008 
anthropic.claude-2.output=0.024

    2. Instana UI で価格設定を構成する。

      1. Instana UI にログインしてください。
      2. GenAI の可観測性ダッシュボードに移動します。
      3. 「構成」 タブをクリックをします。 事前定義された一般的なLLMモデルのリストとデフォルト価格が表示されます。
      4. 既存モデルの価格を更新する：
        1. リストからモデルを見つけてください。
        2. モデル名をクリックし、 編集をクリックしてください
        3. 入力トークンと出力トークンの価格を更新する。
        4. 保存 をクリックします。
      5. 新しいモデルを追加する：
        1. モデル価格を追加をクリック
        2. プロバイダーを入力してください（例：「openai」、「anthropic」）。
        3. モデルIDを入力してください（例：「 gpt-4 」、「 claude-2 」）。
        4. プラットフォーム固有の価格設定を行うには、プラットフォームにアクセスしてください。
        5. 入力トークンと出力トークンの価格を入力してください（例：「bedrock」、「langchain」）。
        6. 追加 をクリックします。
        図 1. LLM価格設定構成

        ダッシュボードベースの価格設定の利点：

        • 変更は即時有効となります - 再デプロイは不要です
        • 価格変更時に更新が容易
        • すべての生成AIアプリケーションにわたる一元管理
        • 価格変更の監査証跡
        注:

        コスト指標は、価格設定を構成した後にのみダッシュボードに表示されます。 その他の指標（レイテンシ、トークン数、エラー率）は、価格設定構成に関係なく表示されます。

  3. 設定を更新した後、変更を適用するために生成AIアプリケーションを再起動してください。

    • Kubernetes 展開の場合：
      kubectl rollout restart deployment/<your-app-deployment> -n <your-namespace>
    • Red Hat OpenShift 展開の場合：
      oc rollout restart deployment/<your-app-deployment> -n <your-namespace>

    • スタンドアロンアプリケーションの場合：

      データが正しく流れていることを確認してください。 アプリケーションを再起動した後、 Instana がデータを受信していることを確認してください:

      1. トレースを確認する：
        1. Go GenAI の可観測性ダッシュボード（ Instana ）へ
        2. アプリケーションに対して新しいトレースが表示されていることを確認してください。
        3. トレースにLLM呼び出し、トークン数、およびレイテンシ情報が表示されていることを確認してください。
      2. メトリクスを確認する：

        1. GenAI の可観測性ダッシュボードで、メトリクスビューを確認してください。

          トークン使用量（入力と出力）、レイテンシ、およびコストメトリクス（課金設定が構成されている場合）が表示されるかどうかを確認してください。

      3. ログを確認する：

        • ログ記録が有効になっている場合、ログが取り込まれていることを確認してください。
        • OpenTelemetry または Traceloop に関連するエラーメッセージがないか確認してください。

      4. アプリケーションログを確認する：

        • アプリケーションログで OpenTelemetry エラーがないか確認してください。
        • Instana エンドポイントへの接続成功メッセージを確認してください。

      5. オプション: OTel データコレクターを削除します。

新しい構成でデータが正しく流れていることを確認した後、 OTel データコレクターのデプロイメントを安全に削除できます。

OTel データコレクター for generative AI (ODCG) の削除時に問題が発生した場合は、次の手順を試してください:

設定を確認してください：

  • すべての環境変数が正しく設定されていることを確認してください
  • Instana エンドポイントがアクセス可能であることを確認してください
  • ダッシュボードで価格設定が設定されていることを確認してください

サポート問い合わせ先:

  • アプリケーションログを提供してください
  • 設定内容を含めてください（機密データは伏せてください）
  • 試した内容とその結果を説明してください

Instana 非推奨のメトリクスエンドポイントを使用しています

問題点: 生成AI向け OTel データコレクター（ODCG）は廃止されました。 アプリケーションは、まだ OTel データコレクターへの接続を試み続けています。

解決策：

  1. 設定から TRACELOOP_METRICS_ENDPOINT 削除したことを確認してください
  2. 異なるレベルで設定された環境変数を確認する:
    • コンテナまたはポッドレベル
    • Deployment/StatefulSet レベル
    • ConfigMap または秘密の参照
    • システム全体の環境変数
  3. 変数を削除した後、アプリケーションを再起動してください
  4. アプリケーションログを確認し、ポート8000への接続を試みていないことを確認してください