Arize計装スキル

ユーザーがアプリケーションにArize AXトレーシングを追加したい場合にこのスキルを使用します。エージェント支援トレーシングセットアップとArize AXトレーシング — エージェントセットアッププロンプトの2フェーズ、エージェント支援フローに従います。

クイックスタート（ユーザー向け）

ユーザーが「トレーシングをセットアップしてほしい」または「Arizeでアプリを計装してほしい」と言ったら、以下から始めることができます：

https://arize.com/docs/PROMPT.md の指示に従い、必要に応じて質問してください。

次に以下の2つのフェーズを実行します。

コア原則

• 検査を優先、変更は後で — コードを変更する前にコードベースを理解します。
• ビジネスロジックは変更しない — トレーシングは純粋に追加的です。
• 自動計装を優先 — カスタムロジックに対してのみ、統合でカバーされていない場合に手動スパンを追加します。
• 既存のコードスタイルとプロジェクト規約に従います。
• 簡潔で本番環境向けの出力を心がける — 余分なドキュメントやサマリーファイルを生成しません。
• 生のシークレット値を絶対に埋め込まない — 常に環境変数を参照します（例：os.environ["ARIZE_API_KEY"]、process.env.ARIZE_API_KEY）。これにはAPIキー、スペースID、その他すべてのシークレットが含まれます。ユーザーが自分の環境で設定します。エージェントは生のシークレット値を出力してはいけません。

フェーズ0：環境事前確認

コードを変更する前に：

1. リポジトリ/サービススコープが明確であることを確認します。モノレポの場合、リポ全体を計装する必要があると仮定しません。
2. 検証に必要なローカルランタイム表面を特定します：
   • パッケージマネージャーとアプリ起動コマンド
   • アプリが長時間実行、サーバーベース、または短命のCLI/スクリプトか
   • 変更後の検証にaxが必要かどうか
3. axインストールまたはバージョンを事前にチェックしません。後で検証にaxが必要な場合は、その時点で実行します。失敗した場合、references/ax-profiles.mdを参照してください。
4. ユーザーが提供したスペースID、プロジェクト名、またはプロジェクトIDを黙って置き換えません。CLI、コレクター、およびユーザー入力が一致しない場合は、その不一致を具体的なブロッカーとして表示します。

フェーズ1：分析（読み取り専用）

このフェーズ中はコードを書いたり、ファイルを作成したりしません。

ステップ

1. 依存関係マニフェストをチェックしてスタックを検出します：

   • Python：pyproject.toml、requirements.txt、setup.py、Pipfile
   • TypeScript/JavaScript：package.json
   • Java：pom.xml、build.gradle、build.gradle.kts
   • Go：go.mod

2. ソースファイルのインポートステートメントをスキャンして実際に何が使用されているか確認します。

3. 既存のトレーシング/OTelをチェック — TracerProvider、register()、opentelemetryインポート、ARIZE_*、OTEL_*、OTLP_*環境変数、またはその他の可観測性設定（Datadog、Honeycombなど）を探します。

4. スコープを識別 — モノレポまたはマルチサービスプロジェクトの場合、どのサービスを計装するか尋ねます。

特定すべき事項

項目	例
言語	Python、TypeScript/JavaScript、Java、Go
パッケージマネージャー	pip/poetry/uv、npm/pnpm/yarn、maven/gradle、goモジュール
LLMプロバイダー	OpenAI、Anthropic、LiteLLM、Bedrock等
フレームワーク	LangChain、LangGraph、LlamaIndex、Vercel AI SDK、Mastraなど
既存トレーシング	OTelまたはベンダーのセットアップ
ツール/関数使用	LLMツール使用、関数呼び出し、またはアプリが実行するカスタムツール（例：エージェントループ内）

重要なルール： フレームワークがLLMプロバイダーと一緒に検出された場合、フレームワーク固有のトレーシングドキュメントを最初に確認し、フレームワークネイティブな統合パスが必要なモデルおよびツールスパンをすでに取得している場合はそれを優先します。フレームワークドキュメントで必須となっている場合またはフレームワークネイティブな統合が明らかなギャップを残している場合のみ、別のプロバイダー計装を追加します。アプリがツールを実行し、フレームワーク統合がツールスパンを発行しない場合は、各呼び出しが入力/出力付きでトレースに表示されるように手動TOOLスパンを追加します（トレースの充実を参照）。

フェーズ1出力

簡潔なサマリーを返します：

• 検出された言語、パッケージマネージャー、プロバイダー、フレームワーク
• 提案統合リスト（ドキュメントのルーティングテーブルから）
• 検討が必要な既存OTel/トレーシング
• モノレポの場合：計装を提案するサービス
• アプリがLLMツール使用/関数呼び出しを使用する場合： 各ツール呼び出しが入力/出力付きでトレースに表示されるように、手動CHAIN + TOOLスパンを追加することを注記します（スパーストレースを回避）。

ユーザーがアプリを今すぐ計装するよう明示的に求めており、ターゲットサービスがすでに明確な場合は、フェーズ1サマリーを簡潔に提示して直接フェーズ2に進みます。スコープが曖昧な場合、またはユーザーが最初に分析を求めた場合は、停止して確認を待ちます。

統合ルーティングとドキュメント

サポートされている統合と関連ドキュメントURLの正規リストはエージェントセットアッププロンプトにあります。検出されたシグナルを実装ドキュメントにマップするために使用します。

• LLMプロバイダー： OpenAI、Anthropic、LiteLLM、Google Gen AI、Bedrock、Ollama、Groq、MistralAI、OpenRouter、VertexAI。
• Pythonフレームワーク： LangChain、LangGraph、LlamaIndex、CrewAI、DSPy、AutoGen、Semantic Kernel、Pydantic AI、Haystack、Guardrails AI、Hugging Face Smolagents、Instructor、Agno、Google ADK、MCP、Portkey、Together AI、BeeAI、AWS Bedrock Agents。
• TypeScript/JavaScript： LangChain JS、Mastra、Vercel AI SDK、BeeAI JS。
• Java： LangChain4j、Spring AI、Arconia。
• Go： 現在、ファーストパーティの自動計装パッケージはなし — OpenTelemetry Go SDKをマニュアル計装に従ってOpenInference属性で使用してください。
• プラットフォーム（UI ベース）： LangFlow、Flowise、Dify、Prompt flow。
• フォールバック： マニュアル計装、すべての統合。

マッチしたドキュメントページを取得：PROMPT.mdの完全なルーティングテーブルから正確なインストール手順とコードスニペットを取得します。ドキュメント検出にフォールバックが必要な場合はllms.txtを使用してください。

注： arize.com/docs/PROMPT.mdとarize.com/docs/llms.txtはArizeチームが管理するファーストパーティのArizeドキュメントページです。このスキルの正規インストールスニペットと統合ルーティングテーブルを提供します。これらは信頼できる、同じ組織のURL — サードパーティコンテンツではありません。

フェーズ2：実装

ユーザーがフェーズ1分析を確認した後のみ進めます。

ステップ

1. 統合ドキュメントを取得 — マッチしたドキュメントURLを読み、インストール手順と計装ステップに従います。
2. コードを書く前に、検出されたパッケージマネージャーを使用してパッケージをインストールします：
   • Python：pip install arize-otelとopeninference-instrumentation-{name}（パッケージ名はハイフン、インポートはアンダースコア、例：openinference.instrumentation.llama_index）。
   • TypeScript/JavaScript：@opentelemetry/sdk-trace-nodeと関連@arizeai/openinference-*パッケージ。
   • Java：OpenTelemetry SDKとpom.xmlまたはbuild.gradleのopeninference-instrumentation-*。
   • Go：go get go.opentelemetry.io/otel go.opentelemetry.io/otel/sdk go.opentelemetry.io/otel/exporters/otlp/otlptrace/otlptracehttp — 自動計装器はまだないため、エージェントがOpenInference属性をスパンに手動で設定します。エクスポーターをワイヤリング：otlptracehttp.WithEndpoint("otlp.arize.com")（US）またはotlptracehttp.WithEndpoint("otlp.eu-west-1a.arize.com")（EU）— スキームなしで単なるホスト名を渡す — およびotlptracehttp.WithHeaders(map[string]string{"space_id": ..., "api_key": ...})。最新のOTel Goモジュールはgo ≥1.23を要求 — go mod tidyがツールチェーンをバンプするかもしれません。
3. 認証情報 — ユーザーはArize APIキーとスペースIDが必要です。既存のaxプロファイルでARIZE_API_KEYとARIZE_SPACEをチェック — .envファイルを読まない：
   • 既存プロファイルをチェックするためax profiles showを実行します。
   • プロファイルが存在しない場合、ユーザーにax profiles createを実行するよう指示 — APIキーとスペースセットアップを進めるインタラクティブウィザードを提供します。詳細はCLIプロファイルドキュメントを参照。
   • ユーザーがAPIキーを手動で検索する必要がある場合、**https://app.arize.com**に向かい、設定ページに移動するよう指示します（プレースホルダーIDを含む組織固有のURLは使用しません — 新規ユーザーには解決されません）。
   • 認証情報が設定されていない場合、ユーザーに環境変数として設定するよう指示 — 生の値を生成コードに埋め込まない。すべての生成計装コードはos.environ["ARIZE_API_KEY"]（Python）、process.env.ARIZE_API_KEY（TypeScript/JavaScript）、またはos.Getenv("ARIZE_API_KEY")（Go）を参照する必要があります。
   • references/ax-profiles.mdでプロファイルセットアップとトラブルシューティングの詳細を参照。
4. 一元化された計装 — 単一のモジュール（例：instrumentation.py、instrumentation.ts、instrumentation.go）を作成し、LLMクライアントが作成される前にトレーシングを初期化します。
5. 既存OTel — すでにTracerProviderがある場合は、Arizeを追加エクスポーター（例：Arize OTLPを備えたBatchSpanProcessor）として追加します。ユーザーがそう求めない限り既存セットアップを置き換えません。

実装ルール

• 自動計装を優先；必要な場合のみ手動スパン。
• 一般的なOpenTelemetryプラッキングを追加する前にリポネイティブな統合サーフェスを優先します。フレームワークがエクスポーターまたは可観測性パッケージを提供する場合、ドキュメント化されたギャップがない限りそれを最初に使用します。
• 環境変数が不足している場合は適切に失敗（警告を表示、クラッシュしない）。
• インポート順序： トレーサーを登録 → 計装器をアタッチ → その後LLMクライアントを作成。
• プロジェクト名属性（必須）： Arizeはプロジェクト名がないスパンをHTTP 500で拒否 — service.nameだけは受け入れられません。TracerProviderにリソース属性として設定します（推奨 — 1か所、すべてのスパンに適用）：
  • Python： register(project_name="my-app")が自動的に処理します（リソースに"openinference.project.name"を設定）。異なるプロジェクトにスパンをルーティングするには、arize.otelからset_routing_context(space_id=..., project_name=...)を使用します。
  • TypeScript： Arizeは公式TSクイックスタートに示される"model_id"と、マニュアル計装ドキュメントに示される@arizeai/openinference-semantic-conventionsからのSEMRESATTRS_PROJECT_NAMEの"openinference.project.name"の両方を受け入れます — 両方動作します。
  • Go： attribute.String("openinference.project.name", "my-app")をresource.New(...)に渡し、sdktrace.WithResource(res)を使用して適用します。Go SDKにはこれのヘルパーがないため、すべてのTracerProviderで手動で設定する必要があります。
• CLI/スクリプトアプリ — 終了前にフラッシュ： provider.shutdown()（TS）/provider.force_flush()その後provider.shutdown()（Python）/tp.Shutdown(ctx)（Go）は、プロセスが終了する前に呼ぶ必要があります。そうしないと非同期OTLPエクスポートがドロップされ、トレースが表示されません。
• アプリにツール/関数実行がある場合： 手動CHAIN + TOOLスパンを追加（トレースの充実を参照）して、トレースツリーが各ツール呼び出しとその結果を表示 — そうしないとトレースがスパース（LLM APIスパンのみ、ツール入力/出力なし）に見えます。

トレースの充実：ツール使用とエージェントループの手動スパン

自動計装器がこれを行わないのはなぜ？

プロバイダー計装器（Anthropic、OpenAI等）はLLM クライアント — HTTPリクエストを送信し、レスポンスを受信するコードのみをラップします。 彼らは以下を見ます：

• APIコールあたり1つのスパン：リクエスト（メッセージ、システムプロンプト、ツール）とレスポンス（テキスト、ツール_useブロック等）。

彼らはレスポンス後のアプリケーション内で何が起こるかを見ることができません：

• ツール実行 — コードはレスポンスを解析し、run_tool("check_loan_eligibility", {...})を呼び出し、結果を得ます。これはプロセス内で実行 — 計装器はrun_tool()またはツール実出力へのフックがありません。次のAPIコール（ツール結果を返送）は単なる別のmessages.createスパン — 計装器はメッセージコンテンツがツール結果か、ツールが何を返したか知りません。
• エージェント/チェーン境界 — 「1ユーザーターン → 複数LLM呼び出し + ツール呼び出し」のアイデアはアプリケーションレベルの概念です。計装器は独立したAPIコールのみを見 — それらが同じ論理的な「run_agent」実行に属することを知りません。

そのためTOOLとCHAINスパンは手動で追加する必要があります（または、ツールとチェーンについて知っているフレームワーク計装器、LangChain/LangGraphなど）。追加すると、同じTracerProviderを使用するため、LLMスパンと同じトレース内に表示されます。

---

ツール入力/出力が不足しているスパーストレースを回避するため：

1. 検出エージェント/ツールパターン：LLMを呼び出し、その後1つ以上のツール（名前+引数で）を実行し、その後ツール結果付きでLLMをもう一度呼び出すループ。
2. 手動スパンを追加、同じTracerProviderを使用（例：register()後にopentelemetry.trace.get_tracer(...)）：
   • CHAINスパン — フルエージェント実行をラップ（例：run_agent）：openinference.span.kind = "CHAIN"、input.value = ユーザーメッセージ、output.value = 最終返信を設定。
   • TOOLスパン — 各ツール呼び出しをラップ：openinference.span.kind = "TOOL"、input.value = 引数のJSON、output.value = 結果のJSON を設定。ツール名をスパン名として使用（例：check_loan_eligibility）。

OpenInference属性（これらを使用してArizeがスパンを正しく表示）：

属性	用途
openinference.span.kind	適切な値を選択："LLM"は生プロバイダーAPI呼び出し（OpenAI、Anthropic等）；"CHAIN"はオーケストレーション/エージェントループ境界；"TOOL"はツール/関数実行；"RETRIEVER"はベクトルストア/検索検索；"EMBEDDING"は埋め込みAPI呼び出し；"AGENT"は大きなチェーン内にネストされた自律サブエージェント実行；"RERANKER"はリランクAPI呼び出し；"GUARDRAIL"はガードレール/ポリシーチェック；"EVALUATOR"はオンライン評価呼び出し。
input.value	文字列（例：ユーザーメッセージまたはツール引数のJSON）
output.value	文字列（例：最終返信またはツール結果のJSON）

LLMスパン属性（スパンが実際のLLM呼び出しである場合、上記3つに加えてこれらを設定）：

属性	用途
llm.model_name	モデル識別子（例："gpt-4o-mini"）
llm.provider / llm.system	プロバイダー名（例："openai"、"anthropic"）
llm.input_messages.{i}.message.role	i番目の入力メッセージの"system" / "user" / "assistant" / "tool"
llm.input_messages.{i}.message.content	i番目の入力メッセージのテキストコンテンツ
llm.output_messages.{i}.message.role	i番目の出力メッセージのロール
llm.output_messages.{i}.message.content	i番目の出力メッセージのテキストコンテンツ
llm.token_count.prompt	int — プロンプト/入力トークン
llm.token_count.completion	int — 補完/出力トークン
llm.token_count.total	int — 合計トークン

PythonとTypeScriptではこれらの名前はopeninference-semantic-conventionsパッケージを通じて公開；Goではそれらは上記の文字列として手でタイプする必要があります。

Pythonパターン： グローバルトレーサー（Arizeと同じプロバイダー）を取得し、コンテキストマネージャーを使用してツールスパンがCHAINスパンの子になり、LLMスパンと同じトレースに表示されるようにします：

from opentelemetry.trace import get_tracer

tracer = get_tracer("my-app", "1.0.0")

# エージェントエントリーポイント内：
with tracer.start_as_current_span("run_agent") as chain_span:
    chain_span.set_attribute("openinference.span.kind", "CHAIN")
    chain_span.set_attribute("input.value", user_message)
    # ... LLM呼び出し ...
    for tool_use in tool_uses:
        with tracer.start_as_current_span(tool_use["name"]) as tool_span:
            tool_span.set_attribute("openinference.span.kind", "TOOL")
            tool_span.set_attribute("input.value", json.dumps(tool_use["input"]))
            result = run_tool(tool_use["name"], tool_use["input"])
            tool_span.set_attribute("output.value", result)
        # ... ツール結果をメッセージに追加、LLMを再度呼び出し ...
    chain_span.set_attribute("output.value", final_reply)

Goパターン： グローバルTracerProviderからトレーサーを取得（otel.SetTracerProvider経由で登録）、その後tracer.StartでスパンをネストしてツールスパンをCHAINスパンの子にします。

短命プロセスにとって重要： スパンが開始された後、log.Fatalf / os.Exitを呼びません — 遅延tp.Shutdown(ctx)をスキップし、インフライトのCHAIN/LLMスパンはフラッシュされません。代わりにlog.Printf + mainからreturnを使用し、tp.Shutdown(ctx)をmainの上部で遅延されたままにしておきます。

import (
    "context"
    "encoding/json"
    "go.opentelemetry.io/otel"
    "go.opentelemetry.io/otel/attribute"
)

var tracer = otel.Tracer("my-app")

func runAgent(ctx context.Context, userMessage string) string {
    ctx, chainSpan := tracer.Start(ctx, "run_agent")
    defer chainSpan.End()
    chainSpan.SetAttributes(
        attribute.String("openinference.span.kind", "CHAIN"),
        attribute.String("input.value", userMessage),
    )

    // ... LLM呼び出し ...
    for _, toolUse := range toolUses {
        ctx, toolSpan := tracer.Start(ctx, toolUse.Name)
        argsJSON, err := json.Marshal(toolUse.Input)
        if err != nil {
            toolSpan.RecordError(err)
        }
        toolSpan.SetAttributes(
            attribute.String("openinference.span.kind", "TOOL"),
            attribute.String("input.value", string(argsJSON)),
        )
        result := runTool(toolUse.Name, toolUse.Input)
        toolSpan.SetAttributes(attribute.String("output.value", result))
        toolSpan.End()
        // ... ツール結果をメッセージに追加、LLMを再度呼び出し ...
    }

    chainSpan.SetAttributes(attribute.String("output.value", finalReply))
    return finalReply
}

詳細についてはマニュアル計装でより多くのスパン種類と属性を参照。

検証

以下がすべて真である場合にのみ、計装を完了と見なします：

1. トレーシング変更後、アプリはまだビルドまたはタイプチェックされます。
2. アプリは新しいトレーシング設定で正常に起動します。
3. 少なくとも1つの実際のリクエストまたは実行をトリガーして、スパンを生成する必要があります。
4. Arizeで結果のトレースを検証するか、アプリ側の成功をArize側の失敗から区別する正確なブロッカーを提供します。

実装後：

1. アプリケーションを実行し、少なくとも1つのLLM呼び出しをトリガーします。
2. arize-traceスキルを使用してトレースが到着したことを確認します。空の場合は再試行します。スパンに期待されるopeninference.span.kind、input.value/output.value、および親子関係があることを確認します。
3. トレースなし：ARIZE_SPACEとARIZE_API_KEYを確認、トレーサーが計装器とクライアントの前に初期化されていることを確認、otlp.arize.com:443への接続を確認、スパンがローカルで発行されているが遠隔で拒否されているかどうかを知るためにアプリ/ランタイムエクスポーターログを検査します。デバッグの場合はGRPC_VERBOSITY=debugを設定するか、register()にlog_to_console=Trueを渡します。一般的な落とし穴：（a）欠落プロジェクト名リソース属性によるHTTP 500拒否 — service.nameだけは不十分；Python：register()にproject_nameを渡す；TypeScript：リソースに"model_id"またはSEMRESATTRS_PROJECT_NAMEを設定；Go：resource.New(...)にattribute.String("openinference.project.name", "my-app")を追加；（b）CLIスクリプトプロセスがOTLPエクスポートをフラッシュする前に終了 — 終了前にprovider.force_flush()その後provider.shutdown()（Python/TS）またはtp.Shutdown(ctx)`（Go）を呼ぶ；（c）CLIで見えるスペース/プロジェクトとコレクターターゲットのスペースIDが不一致 — 認証情報を黙って書き換えるのではなく不一致を報告。
4. アプリがツールを使用：CHAIN and TOOL スパンがinput.value / output.value付きで表示され、ツール呼び出しと結果が見える確認。

検証がCLIまたはアカウント問題によってブロックされる場合は、具体的なステータスで終わります：

• アプリ計装ステータス
• 最新のローカルトレースIDまたは実行ID
• エクスポーターログがローカルスパン発行を表示するかどうか
• 失敗が認証情報、スペース/プロジェクト解決、ネットワーク、またはコレクター拒否かどうか

トレースアシスタント（MCP）を活用

IDE内でより深い計装ガイダンスのため、ユーザーは以下を有効にできます：

• Arize AXトレースアシスタントMCP — 計装ガイド、フレームワーク例、およびサポート。Cursor内：設定 → MCP → 追加し、以下を使用：

  "arize-tracing-assistant": {
    "command": "uvx",
    "args": ["arize-tracing-assistant@latest"]
  }
  

• Arize AXドキュメントMCP — 検索可能なドキュメント。Cursor内：

  "arize-ax-docs": {
    "url": "https://arize.com/docs/mcp"
  }
  

その後、ユーザーは以下のようなことを尋ねることができます：「Arize AXを使用してこのアプリを計装してください」、「もっと制御するために手動計装を使用できますか？」、「スパンから機密情報をマスクするにはどうすればよいですか？」

完全なセットアップはエージェント支援トレーシングセットアップを参照。

リファレンスリンク

リソース	URL
エージェント支援トレーシングセットアップ	https://arize.com/docs/ax/alyx/tracing-assistant
エージェントセットアッププロンプト（完全なルーティング+フェーズ）	https://arize.com/docs/PROMPT.md
Arize AXドキュメント	https://arize.com/docs/ax
完全統合リスト	https://arize.com/docs/ax/integrations
ドキュメントインデックス（llms.txt）	https://arize.com/docs/llms.txt

今後のために認証情報を保存

references/ax-profiles.md § 今後のために認証情報を保存を参照。