HTTP の 4xx ステータスコードをエラーとして設定する

EXIT（クライアント）スパンにおいて、リストされている HTTP4xx のステータスコードをエラーとしてマークします。 この変数が設定されている場合、 は無視 INSTANA_TRACING_HTTP_EXIT_CLASSIFY_ALL_4XX_AS_ERRORS されます。

# Linux / macOS
export INSTANA_TRACING_HTTP_EXIT_CLASSIFY_AS_ERRORS=401,403,429

# Windows (PowerShell)
$env:INSTANA_TRACING_HTTP_EXIT_CLASSIFY_AS_ERRORS="401,403,429"

# Docker
ENV INSTANA_TRACING_HTTP_EXIT_CLASSIFY_AS_ERRORS=401,403,429

# Kubernetes (env section of a container spec)
- name: INSTANA_TRACING_HTTP_EXIT_CLASSIFY_AS_ERRORS
  value: "401,403,429"

に設定すると true、EXITスパンにおけるすべての HTTP 4xx レスポンス（400～499）がエラーとしてマークされます。 も設定 INSTANA_TRACING_HTTP_EXIT_CLASSIFY_AS_ERRORS されている場合、この設定は無視されます。

# Mark all 4xx responses on exit spans as errors
export INSTANA_TRACING_HTTP_EXIT_CLASSIFY_ALL_4XX_AS_ERRORS=true

com.instana.tracing:
  http:
    exit:
      classify-as-errors:
        - 401
        - 403
        - 429

com.instana.tracing:
  http:
    exit:
      classify-all-4xx-as-errors: true

両方のキーが存在する場合、が優先 classify-as-errors されます。

com.instana.tracing:
  http:
    exit:
      classify-all-4xx-as-errors: true   # ignored — classify-as-errors is non-empty
      classify-as-errors:
        - 401
        - 403

アプリケーションにおいて、404は正常な状態とみなされるが、401は常にクライアントの設定ミスを示すものと想定される場合は、この設定を使用してください：

export INSTANA_TRACING_HTTP_EXIT_CLASSIFY_AS_ERRORS=401

export INSTANA_TRACING_HTTP_EXIT_CLASSIFY_AS_ERRORS=401,403,429

export INSTANA_TRACING_HTTP_EXIT_CLASSIFY_ALL_4XX_AS_ERRORS=true

com.instana.tracing:
  http:
    exit:
      classify-as-errors:
        - 401
        - 403

env:
  - name: INSTANA_TRACING_HTTP_EXIT_CLASSIFY_AS_ERRORS
    value: "401,403,429"

この設定を行う classify-all-4xx-as-errors: true と、 4xx のすべてのレスポンスがエラーとして扱われます。これには、通常は想定内であり、問題のないコード 409 Conflict である や 404 Not Found なども含まれます。 この設定により、エラー件数が過大に計上されたり、誤ったアラートが発生したりする可能性があります。 アプリケーションのコンテキストにおいて、真に予期せぬ障害を示している特定のコードのみをリストアップするようにしてください。

まずは、エラーと最も明確に関連しているコード（通常は 401、 403、 429）のみにマークを付け、ダッシュボードへの影響を確認してから、他のコードを追加するようにしてください。 エラー率が急激に上昇すると、真の回帰を特定することが難しくなることがあります。

環境変数は、コンテナ化された環境において最も信頼性の高い設定方法です。 これらは起動時に適用され、Podの仕様で確認でき、エージェントの接続問題によって上書きされることはありません。 YAML またはエージェント設定は、多数のサービスにわたる一元管理が必要な場合にのみ使用してください。

両方が指定されている場合、環境変数が優先され、 YAML の値は黙って無視されます。 混乱を避けるため、各デプロイメントごとに1つの設定方法を採用し、それを文書化してください。

複数のチームやクライアントが利用するサービスにおいて、一部の 4xx コードは、特定の呼び出し元に対して有効となる場合があります。 特定のコードリストを使用することで、それらのコードの使用が想定されている呼び出し元には影響を与えることなく、予測可能で一貫性のあるエラー報告が可能になります。

1. 起動時（環境変数および YAML ）またはエージェントが最初に接続した際に、設定が一度読み込まれることを確認してください。 プロセスが開始される前に、環境変数が設定されていることを確認してください。
2. 環境変数が正しく設定されていることを確認してください。 プロセス環境内で ( Linuxprintenv | grep INSTANA_TRACING ) または Get-ChildItem Env: | Where-Object Name -like "INSTANA_TRACING*" ( PowerShell ) を実行してください。
3. ステータスコードの範囲を確認してください。 400～499の範囲の整数のみが有効です。 、や 500、といった値 200、あるいは数値ではない文字列は、警告がログに記録されるものの、何も表示されずに無視されます。
4. 「ENTRY」スパンではなく、「EXIT」スパンを確認してください。

この設定を行う INSTANA_TRACING_HTTP_EXIT_CLASSIFY_ALL_4XX_AS_ERRORS=true と、 4xx からのすべてのレスポンスがエラーとして扱われます。これには、アプリケーションでは想定される可能性 409 のある や 404 といったコードも含まれます。 ノイズを低減するために、特定のコードリストを使用して INSTANA_TRACING_HTTP_EXIT_CLASSIFY_AS_ERRORS に切り替えてください。

1. が、存在し、かつプロセス所有者が読み取り可能なファイルを指 INSTANA_CONFIG_PATH していることを確認してください。
2. 環境 INSTANA_TRACING_HTTP_EXIT_CLASSIFY_AS_ERRORS 変数 および INSTANA_TRACING_HTTP_EXIT_CLASSIFY_ALL_4XX_AS_ERRORS が設定されていないことを確認してください。 これらは、 YAML を黙って上書きします。
3. YAML のキー名には、アンダースコア（.）ではなくハイフン（--）が使用されていることを確認してください classify-as-errorsclassify_as_errors。
4. インデントを確認してください。 YAML インデントに依存します。 http は（ com.instana.tracing または tracing）の子でなければならず、また、はの子で exit なければならない http。

エージェントの設定は、トレーサーがエージェントに接続した後にのみ適用されます。 起動時にエージェントが利用できない場合、エージェントの設定が反映されない可能性があります。 起動時の設定を確実に反映させるには、環境変数を使用してください。

エージェントの設定を上書きするような環境変数が設定されていないことを確認してください：

printenv | grep INSTANA_TRACING

一部の環境では、シェルセッションで設定された環境変数は、子プロセスに引き継がれません。 再起動後も設定が維持されるように、システムサービス定義、 Docker Compose ファイル、 Kubernetes のPod仕様、またはアプリケーションの起動スクリプトでこれらの設定を行ってください。

• の値は、400～499の範囲の整数でなければ classify-as-errors なりません。
• この範囲外の値は無視され、トレーサーログに警告が記録されます。
• 整数以外の値は無視され、トレーサーログに警告が記録されます。
• 同じ設定レベルに両方のキーが存在する場合、が優先 classify-as-errors されます。
• 5xx ステータスコード（500～599）は常にエラーとして扱われ、無効にすることはできません。
• ENTRY（サーバー）のスパンは、設定にかかわらず、決して影響を受けません。