トレーシング

Solo Enterprise for agentregistry を通じてデプロイされた AI アーティファクトに分散トレーシングを構成します。

トレーシングについて

Solo Enterprise for agentregistry は、接続されたランタイムにデプロイされたエージェントおよび MCP サーバーから分散トレースを収集します。トレースを使用すると、エージェントの呼び出し、LLM の呼び出し、MCP ツールの呼び出しにまたがってリクエストをエンドツーエンドで追跡できるため、レイテンシーの診断、障害のデバッグ、本番環境におけるエージェントの動作の理解が可能になります。

デフォルトでは、Solo Enterprise for agentregistry はレジストリサーバーと並行して組み込みの OpenTelemetry (OTel) Collector パイプラインをデプロイします。コレクターは、デプロイされた AI アーティファクトから OTLP トレースを受信し、組み込みの ClickHouse インスタンスに保存します。ClickHouse インスタンスは、レジストリ UI の Tracing ビューにデータを提供します。Jaeger や Grafana Tempo など、外部の OTEL 互換バックエンドにトレースを転送して、より詳細な分析や長期的な保持を行うこともできます。トレース収集を有効にするには、各 Runtime リソースの telemetryEndpoint フィールドに、エージェントがトレースをエクスポートする OTLP エンドポイントを設定する必要があります。

次の図は、Solo Enterprise for agentregistry でトレースがどのように発行および収集されるかを示しています。

    graph LR
    subgraph k8s["Kubernetes クラスター"]
        subgraph ar_ns["agentregistry-system ネームスペース"]
            OC["OTel Collector\n(telemetry-collector-pod)"] --> CH["ClickHouse"]
            AR["Solo Enterprise for agentregistry"] -->|"トレースをクエリ"| CH
        end
        subgraph runtime_ns["Runtime ネームスペース (例: kagent)"]
            AG["デプロイされたエージェント"] -->|"OTLP/HTTP (ポート 4318)"| OC
        end
    end
    OC -.->|"オプション: トレースを転送"| EXT["外部 OTEL バックエンド\n(Jaeger、Tempo など)"]
    User(["ユーザー"]) -->|"トレースを表示"| AR

始める前に

ユーザーがレジストリで認証できるように、OIDC プロバイダーを設定します。
Solo Enterprise for agentregistry をインストールします。あわせて arctl CLI もインストールします。
まだ実行していない場合は、Solo Enterprise for agentregistry サーバーをポート 12121 でポートフォワードします。レジストリはデフォルトでは外部に公開されないため、ローカルマシンから接続するにはポートフォワードが必要です。
```
kubectl -n agentregistry-system port-forward svc/agentregistry-enterprise-server 12121:12121
```

AI アーティファクトのカタログを構築します

`Runtime` に OTEL ホストを構成する

各 Runtime リソースには、デプロイされたエージェントが OTLP トレースを送信する先を制御する telemetryEndpoint フィールドがあります。エージェントまたは MCP サーバーをデプロイすると、レジストリはこのエンドポイントをエージェントの環境にインジェクトするため、エージェント SDK はスパンをエクスポートする場所を認識します。フィールドが設定されていない場合、エージェントはトレースを発行しません。

デフォルトでは、Runtime はレジストリサーバーと並行してデプロイされる組み込みの OTel Collector を指すように設定します。

Note

telemetryEndpoint は、エージェントが実行されるネームスペースから到達可能である必要があります。外部バックエンドがクラスターの外部にある場合は、エンドポイントがエージェントまたは MCP サーバーからアクセス可能であること、および必要なファイアウォールルールやサービスエントリが設定されていることを確認してください。

組み込みの OTel Collector のアドレスを取得します。
kagent ランタイムはレジストリサーバーと同じクラスター内で動作するため、内部の Kubernetes サービス DNS 名を使用して OTel Collector に到達できます。外部への公開は不要です。
```
kubectl get svc -n agentregistry-system | grep telemetry
```
出力例:
```
agentregistry-enterprise-telemetry-collector   ClusterIP   10.96.0.1   <none>   4317/TCP,4318/TCP   5m
```

コレクターの OTLP/HTTP ポート (4318) に telemetryEndpoint を設定して、Runtime リソースを作成または更新します。

arctl apply -f- <<EOF
apiVersion: ar.dev/v1alpha1
kind: Runtime
metadata:
  name: kagent
spec:
  type: Kagent
  telemetryEndpoint: http://agentregistry-enterprise-telemetry-collector.agentregistry-system.svc.cluster.local:4318
  config:
    kagentUrl: http://kagent-controller.kagent:8083
    namespace: kagent
EOF

設定	説明
`telemetryEndpoint`	デプロイされたエージェントと MCP サーバーがトレースをエクスポートする OTLP/HTTP エンドポイント。組み込みのコレクターに設定すると、トレースは ClickHouse に保存され、レジストリ UI で表示されます。外部エンドポイントに設定すると、独自の OTEL バックエンドにトレースを転送します。

Runtime が登録されていることを確認します。

arctl get runtimes

出力例:

NAME        TYPE
agentcore   BedrockAgentCore
kagent      Kagent

Note

Bedrock AgentCore ランタイムは EKS クラスターの外部で実行されるため、OTel Collector は LoadBalancer 経由で公開する必要があります。AWS Bedrock AgentCore クイックスタートガイドに記載されているように、--set telemetry.service.type=LoadBalancer を指定して Solo Enterprise for agentregistry をインストールしていることを確認してください。

ロードバランサーのホスト名を取得し、環境変数として保存します。

export OTEL_HOST=$(kubectl -n agentregistry-system get svc \
  agentregistry-enterprise-telemetry-collector \
  -o jsonpath='{.status.loadBalancer.ingress[0].hostname}')
echo "OTel endpoint: http://${OTEL_HOST}:4318"

コレクターの OTLP/HTTP ポート (4318) に telemetryEndpoint を設定して、Runtime リソースを作成または更新します。

arctl apply -f- <<EOF
apiVersion: ar.dev/v1alpha1
kind: Runtime
metadata:
  name: agentcore
spec:
  type: BedrockAgentCore
  telemetryEndpoint: http://${OTEL_HOST}:4318
  config:
    roleArn: $AWS_ROLE_ARN
    externalId: $AWS_EXTERNAL_ID
    region: $AWS_REGION
EOF

Runtime が登録されていることを確認します。

arctl get runtimes

出力例:

NAME        TYPE
agentcore   BedrockAgentCore
kagent      Kagent

UI でトレースを表示する

デプロイされたエージェントにリクエストが送信されるたびに、トレースは自動的に収集されます。デフォルトのインストールを使用する場合、追加の構成は必要ありません。

デプロイされたエージェントにリクエストを送信します。Instances ビューを開き、エージェントを選択して Open Chat をクリックします。
Tracing ビューを開きます。デプロイされたエージェントからの最近のトレースのリストが表示されます。
トレースを選択して、LLM の呼び出し、ツールの呼び出し、エージェントのステップごとの個別のスパンを含む詳細を表示します。

監査ログ

トレーシング