Claude Media
OTEL_ATTRIBUTE_VALUE_LENGTH_LIMITとは — 属性値の文字数上限を調整する環境変数
Claude CodeTips

OTEL_ATTRIBUTE_VALUE_LENGTH_LIMITとは — 属性値の文字数上限を調整する環境変数

OpenTelemetry標準の属性値長さ上限をClaude Codeで使う設定と、CLAUDE_CODE_OTEL_CONTENT_MAX_LENGTHとの優先関係を扱います。

読了目安 約9分

Claude CodeはOpenTelemetryによる利用量・コストの可視化に対応しており、テレメトリの出力先やコンテンツ量を細かく調整できます。OTEL_ATTRIBUTE_VALUE_LENGTH_LIMITはその中でも、属性値1個あたりの長さそのものを制限する変数です。

OTEL_ATTRIBUTE_VALUE_LENGTH_LIMITでできること

OTEL_ATTRIBUTE_VALUE_LENGTH_LIMITは、OpenTelemetry SDKが標準で持つ属性値の長さ上限を指定する環境変数です。Claude Code独自の変数ではなく、OpenTelemetryの一般的な仕組みをそのまま利用しています。

Claude Codeはこの値とCLAUDE_CODE_OTEL_CONTENT_MAX_LENGTH(コンテンツ系属性の上限、デフォルト61440 UTF-16コード単位 = 60KB)を比較し、小さい方をモデル応答・ツール出力・システムプロンプト・生APIボディなど「コンテンツを含む属性」の実際の切り詰め基準として採用します。[TRUNCATED ...]という切り詰めマーカー自体もこの上限に収まるように出力されます。

この変数を設定する主な動機は1つです。テレメトリバックエンド側の属性値サイズ上限が、Claude Codeの既定値(60KB)より小さい場合、そのバックエンドの制約に合わせて先に切り詰めておく必要があります。

いつ設定する必要があるか

Claude CodeのOpenTelemetry出力を受け取るバックエンド(自前のOTLPコレクターや監視SaaSなど)によっては、属性値のサイズに独自の上限を設けています。デフォルトの60KBを超える属性値を送信すると、バックエンド側で拒否されたりログが欠落したりすることがあります。

OTEL_ATTRIBUTE_VALUE_LENGTH_LIMITをバックエンドの上限より小さい値に設定すれば、Claude Code側で先に切り詰めてから送信できます。逆にバックエンドが64KBを超える大きな属性値を受け付けるなら、CLAUDE_CODE_OTEL_CONTENT_MAX_LENGTHを引き上げる側で対応します(こちらはClaude Code独自の変数で、コンテンツ系属性専用の上限です)。

亜種の変数も同じ扱いになる

標準のOpenTelemetry SDKには、シグナルの種類ごとに個別の上限を指定する亜種の環境変数があります。Claude Codeはこれらも読み取ります。

  • OTEL_LOGRECORD_ATTRIBUTE_VALUE_LENGTH_LIMIT(ログレコード用)
  • OTEL_SPAN_ATTRIBUTE_VALUE_LENGTH_LIMIT(スパン用)

複数の変数を同時に設定した場合、設定された値のうち最小のものがすべてのシグナル(ログ・スパン・メトリクス)に対して一律に適用されます。たとえばOTEL_ATTRIBUTE_VALUE_LENGTH_LIMIT=32768とOTEL_SPAN_ATTRIBUTE_VALUE_LENGTH_LIMIT=16384を両方設定すると、ログもスパンも16384の上限で切り詰められます。

CLAUDE_CODE_OTEL_CONTENT_MAX_LENGTHとの優先関係

コンテンツ系属性(モデル応答・ツール出力・システムプロンプト・生APIボディ)は、次の2つの上限のうち小さい方が実際に適用されます。

変数役割デフォルト
CLAUDE_CODE_OTEL_CONTENT_MAX_LENGTH役割Claude Code独自。コンテンツ系属性専用の上限デフォルト61440(60KB)
OTEL_ATTRIBUTE_VALUE_LENGTH_LIMIT(および亜種)役割OpenTelemetry SDK標準。全属性に及ぶ上限デフォルト未設定時は無制限

CLAUDE_CODE_OTEL_CONTENT_MAX_LENGTHはコンテンツ系属性だけを対象にした専用チューニング用の変数で、OTEL_ATTRIBUTE_VALUE_LENGTH_LIMITはOpenTelemetry SDKレベルでより広く効く汎用の上限です。両方を設定した場合、コンテンツ系属性については両者を比較して小さい方が使われます。バックエンドの受け入れ上限を先に確認し、それより小さい値をどちらか一方(または両方)に設定します。

OTEL_ATTRIBUTE_VALUE_LENGTH_LIMITの利用にはClaude Code v2.1.214以降が必要です。CLAUDE_CODE_OTEL_CONTENT_MAX_LENGTHも同じくv2.1.214以降が要件になっています。

対象になるコンテンツ系属性

CLAUDE_CODE_OTEL_CONTENT_MAX_LENGTHとOTEL_ATTRIBUTE_VALUE_LENGTH_LIMITの小さい方で切り詰められるのは、次のようなコンテンツを運ぶ属性です。

  • tool.outputスパンイベントのツール実行結果(OTEL_LOG_TOOL_CONTENT=1で有効化)
  • api_request_body / api_response_bodyログイベントの生APIボディ(OTEL_LOG_RAW_API_BODIES=1のインラインモード時)
  • assistant_responseイベントのモデル応答テキスト(OTEL_LOG_ASSISTANT_RESPONSES=1。未設定時はOTEL_LOG_USER_PROMPTS側の設定が併せて出力可否を制御します)
  • user_system_prompt属性のシステムプロンプト全文(--system-prompt / --append-system-promptで渡した内容。出力にはOTEL_LOG_USER_PROMPTS=1も別途必要です)

これらはいずれも既定で60KBまでで、上限を超えた分は[TRUNCATED ...]マーカー付きで切り詰められます。切り詰めが発生した属性には<attribute>_truncatedと<attribute>_original_lengthという付随属性が付き、元の長さを後から確認できます。

一方、tool_input(ツールの入力引数、OTEL_LOG_TOOL_DETAILS=1で有効化)は個々の値が512文字を超えると切り詰められ、ペイロード全体もおよそ4,000文字までに収まる別ルールで管理されています。こちらはCLAUDE_CODE_OTEL_CONTENT_MAX_LENGTHやOTEL_ATTRIBUTE_VALUE_LENGTH_LIMITの対象ではないので、切り詰め挙動を混同しないよう注意が必要です。

よくあるつまずき

  • 亜種を1つだけ設定して安心する: OTEL_SPAN_ATTRIBUTE_VALUE_LENGTH_LIMITのような亜種を1つ設定すると、最小値ルールによってログ・スパン・メトリクスすべてに同じ値が一律で効きます。ログだけ別の緩い値にする、といった信号ごとの個別設定はできません
  • 極端に小さい値にする: 上限を数百バイト程度まで下げると、[TRUNCATED ...]マーカー自体が上限を圧迫し、実質的な本文がほとんど残らないケースがあります。バックエンドの実際の受け入れ上限に合わせます
  • プロジェクト設定・ローカル設定に書いて反映されない: 設定場所の注意点は次節「設定方法」にまとめています
  • 設定変更後にセッションを再起動していない: 反映のタイミングも次節「設定方法」で扱います

設定方法

シェルで直接設定するか、settings.jsonのenvキーに追加します。

export CLAUDE_CODE_ENABLE_TELEMETRY=1
export OTEL_ATTRIBUTE_VALUE_LENGTH_LIMIT=16384
claude

settings.jsonに書く場合は次のような形になります(公式の例に沿った形)。

{
  "env": {
    "CLAUDE_CODE_ENABLE_TELEMETRY": "1",
    "OTEL_ATTRIBUTE_VALUE_LENGTH_LIMIT": "16384"
  }
}

ユーザー設定または管理設定で設定するのが基本です。プロジェクト設定・ローカル設定に書いた場合、OTEL_ATTRIBUTE_VALUE_LENGTH_LIMITやCLAUDE_CODE_ENABLE_TELEMETRYを含むOpenTelemetry関連の変数はClaude Codeが無視するため反映されません。ただし全滅するわけではなく、OTEL_RESOURCE_ATTRIBUTESやエクスポート間隔・タイムアウト・圧縮設定(OTEL_METRIC_EXPORT_INTERVAL等)はプロジェクト設定・ローカル設定からでも通常どおり適用される例外です。設定ファイルの変更は起動中のセッションには反映されず、次回claude起動時から有効になります。

使い分けの早見表

状況おすすめの対応
バックエンドの属性値上限がClaude Codeの60KBより小さいおすすめの対応OTEL_ATTRIBUTE_VALUE_LENGTH_LIMIT(または亜種)をその上限以下に設定
バックエンドが64KB超の大きな属性値を受け付けるおすすめの対応CLAUDE_CODE_OTEL_CONTENT_MAX_LENGTHを引き上げる
テレメトリの転送量そのものを減らしたいおすすめの対応CLAUDE_CODE_OTEL_CONTENT_MAX_LENGTHを下げる
ログ・スパン・メトリクスで別々の上限にしたいおすすめの対応できません。亜種を含めどれか1つを設定すると、その最小値が全シグナルに一律で適用されます

動作確認の方法

設定が効いているかどうかは、切り詰めが実際に発生した属性に付く<attribute>_truncatedフラグで確認できます。たとえばOTEL_LOG_RAW_API_BODIES=1を有効にしていれば、api_request_bodyイベントにbody_truncatedが"true"で付き、body_length属性で切り詰め前の実際の長さも分かります。

まずはOTEL_LOGS_EXPORTER=consoleのようにコンソールエクスポーターへ出力先を切り替え、ターミナル上でイベントのJSONを直接確認する方法が手早く試せます。バックエンドへ送る前に属性値の長さが想定どおり収まっているかをローカルで確かめてから、本番のOTLPエンドポイントへ切り替える流れが安全です。

エクスポーターの共通設定との関係

OTEL_ATTRIBUTE_VALUE_LENGTH_LIMITは属性値の長さだけを扱う変数で、OTEL_EXPORTER_OTLP_ENDPOINTやOTEL_EXPORTER_OTLP_PROTOCOLのようなエクスポーター自体の接続設定とは独立しています。エンドポイントやプロトコルを変えても属性長の上限は変わらず、逆に属性長を変えても接続先は変わりません。設定場所の制約(プロジェクト設定・ローカル設定では無視される)はどちらの変数にも同じく及びます。

バックエンド別の目安値

バックエンドの属性値上限設定する値の目安
64KB(Claude Codeの既定と同程度)設定する値の目安未設定のままでよい(CLAUDE_CODE_OTEL_CONTENT_MAX_LENGTHの既定61440が収まる)
32KB程度の中規模上限設定する値の目安OTEL_ATTRIBUTE_VALUE_LENGTH_LIMIT=32768目安で設定
数KB程度の小さい上限設定する値の目安OTEL_ATTRIBUTE_VALUE_LENGTH_LIMITをその上限以下に設定し、[TRUNCATED ...]マーカー分の余白も見込む
上限が特に無い/大きい設定する値の目安CLAUDE_CODE_OTEL_CONTENT_MAX_LENGTHを引き上げてコンテンツをより多く残す

具体的な上限値はバックエンドのドキュメントで公称値を確認し、そこから[TRUNCATED ...]マーカー分の余白を引いた値にします。

組織の管理設定との関係

組織が管理設定でOTLPのエンドポイント・プロトコル・認証情報を固定している場合、Claude Codeは開発者側が別途設定したそれらの変数を起動時に取り除きます。これはテレメトリの送信先を管理設定側に固定するための仕組みですが、OTEL_ATTRIBUTE_VALUE_LENGTH_LIMITやCLAUDE_CODE_OTEL_CONTENT_MAX_LENGTHはエンドポイント固定の対象になる変数の一覧には含まれていません。属性値の長さ調整は、送信先の固定とは別に、開発者側のユーザー設定や管理設定のいずれからでも通常どおり反映されます。

組織全体で一律の上限を敷きたい場合は、管理設定側でOTEL_ATTRIBUTE_VALUE_LENGTH_LIMITを設定します。開発者側のユーザー設定やシェルの環境変数と重なったときの優先順位は明示されていないため、一律の値を確実に効かせたいなら、開発者側で同じ変数を設定しない運用にしておきます。

テレメトリを止めたい場合との違い

OTEL_ATTRIBUTE_VALUE_LENGTH_LIMITはテレメトリの内容量を調整する変数であり、テレメトリの送信そのものを止める変数ではありません。収集自体を止めたい場合はDO_NOT_TRACK環境変数を使います。すでにCLAUDE_CODE_ENABLE_TELEMETRY=1で収集を有効にしていて、属性のサイズだけを調整したい場合に本記事の変数が対象になります。

メトリクスとログ・スパンの違い

OTEL_ATTRIBUTE_VALUE_LENGTH_LIMITが対象にするのは属性値の長さで、これはログ・スパン・メトリクスのいずれの信号にも及びます。OpenTelemetry SDKにはOTEL_LOGRECORD_ATTRIBUTE_VALUE_LENGTH_LIMITやOTEL_SPAN_ATTRIBUTE_VALUE_LENGTH_LIMITという信号別の亜種もありますが、Claude Codeでは複数設定時に最小値が一律に適用される点は変わりません。

同様に上限値を環境変数で調整するタイプの設定としては、Bash・PowerShellのメモリ使用量を制限するCLAUDE_CODE_TOOL_MEMORY_LIMITもあります。テレメトリの属性長とツールのメモリ使用量は別の仕組みですが、どちらも「既定値のままでは環境に合わないときに個別調整する」という点は共通しています。

まとめ

OTEL_ATTRIBUTE_VALUE_LENGTH_LIMITはOpenTelemetry SDK標準の属性値上限をClaude Codeに適用する変数で、CLAUDE_CODE_OTEL_CONTENT_MAX_LENGTHとの小さい方がコンテンツ系属性の実際の切り詰め基準になります。テレメトリバックエンドの受け入れ上限がClaude Codeの既定60KBと合わないときに設定します。ログ・スパン用の亜種を含め、複数設定時は最小値が全シグナルに一律適用される点を踏まえて値を決めるのが実務のポイントです。v2.1.214以降が必要な点も、既存環境をアップグレードする前に確認しておくとよいでしょう。設定を変えたら、まずコンソールエクスポーターで属性値の実際の長さを確認してから本番のバックエンドへつなぐと、想定外の切り詰めや欠落を避けやすくなります。

この記事を共有:XはてブLinkedIn

関連する記事

Claude Code をもっと見る →