Собирать и проверять трассировки в Microsoft Foundry Toolkit

Используйте Microsoft Foundry Toolkit для Visual Studio Code для сбора локальных трассировок или просмотра телеметрии для агентов, развернутых в Microsoft Foundry. Трассировка объединяет записанные операции для запроса. Каждая операция — это спан с временными метками, состоянием и любыми атрибутами или событиями, предоставленными инструментацией.

В этой статье сначала рассматривается локальный сбор данных, а затем трассировка в облаке для развернутых агентов. Выберите источник данных, соответствующий вашему расследованию:

Approach	Используйте его для	Данные и обязанности
Инспектор агента	Отправьте локальный запрос, проверьте ответ в реальном времени и события инструментов или приостанавливайте код в точке останова.	Сервер предоставляет события протокола и диагностическую информацию для разработки. Этот подход не требует сборщика OTLP и не создает историю облачной трассировки.
Локальная трассировка	Сравните записанные спаны моделей, инструментов и агентов во время разработки.	Приложение экспортирует данные телеметрии в локальный сборщик набора инструментов. Вы настраиваете средства инструментирования и управляете локальными сохранёнными данными.
Отслеживание размещенного агента	Изучите запросы, обрабатываемые агентом, развернутым в Foundry.	Трассировки находятся в ресурсе Application Insights, подключённом к проекту. Доступ, срок хранения и плата зависят от конфигурации ресурса Azure.

Размещаемый агент запускает пользовательский код в Foundry Agent Service. Foundry обеспечивает хостинг, но вы по-прежнему несете ответственность за код и зависимости. Трассировка не заменяет создание и развертывание агента.

Prerequisites

Visual Studio Code с текущим расширением Foundry Toolkit. См. раздел Install Foundry Toolkit.
Приложение, которое можно запустить локально, с настроенной моделью и подключениями инструментов.
В первом примере — приложение на Python с использованием Microsoft Agent Framework и выбранное окружение Python. Для других пакетов SDK используйте настройку Python или JavaScript и TypeScript.
Для облачной трассировки требуются развернутый агент и ресурс Application Insights, подключенный к своему проекту Foundry, или разрешение на его подключение или создание.
Для облачных запросов требуется роль читателя Log Analytics в подключенном ресурсе Application Insights. Для защищённых таблиц также назначьте роль "Читатель данных привилегированного мониторинга". См. предварительные требования для трассировки Foundry.

Для локального сбора данных не требуются разрешения для Application Insights или облачной телеметрии. Вызовы модели и выполнение инструментов по-прежнему могут использовать удалённые службы, что может повлечь дополнительные расходы.

Собрать локальные трассы

Локальный сборщик получает данные телеметрии по протоколу OpenTelemetry Protocol (OTLP). Он не инструментирует приложение автоматически. Платформа или библиотека инструментирования должны создавать спаны и экспортировать их в сборщик.

Настройка пакета SDK и языка

Пакеты SDK со встроенным инструментированием по-прежнему нуждаются в экспортере. Другие пакеты SDK используют отдельный пакет инструментирования.

SDK или фреймворк	Python	JavaScript и TypeScript (Node.js)
платформа агента Microsoft	Встроенная интеграция OpenTelemetry.	Нет рекомендаций по настройке Toolkit.
пакет SDK для инференса Azure AI (предварительная версия)	инструментирование Azure SDK.	инструментирование Azure SDK.
SDK для проектов Foundry	Инструментатор на стороне клиента (предварительная версия).	Добавьте инструментирование для базового клиента SDK OpenAI или Azure.
SDK классических агентов Foundry	средство инструментирования Azure SDK.	Нет отдельных инструкций по настройке инструментария.
Anthropic	Инструментатор OpenLLMetry.	Интеграция Traceloop.
Google GenAI (Gemini)	Инструментатор Google GenAI OpenTelemetry.	Нет отдельных инструкций по настройке инструментария.
LangChain	Инструментатор OpenLLMetry.	Инструментирование Traceloop.
Пакет SDK OpenAI, включая Azure клиенты OpenAI	Инструмент OpenLLMetry.	Инструментирование Traceloop.
Пакет SDK для агентов OpenAI	Обработчик трассировки OpenLLMetry.	Нет рекомендаций по настройке специального Toolkit.

«Отсутствие отдельного руководства по настройке Toolkit» означает, что для этого языка здесь нет отдельного сценария настройки, связанного с конкретным SDK, а не то, что сборщик отклоняет его телеметрические данные. Сборщик принимает данные OTLP. Инструментальное средство определяет, какие операции и сведения о сообщении записываются.

В этих примерах используются выбранные параметры инструментирования; это не исчерпывающий список совместимых библиотек. Инструментирование OpenLLMetry и Traceloop является не-Microsoft библиотекой.

Настройка сбора телеметрии

Используйте эту процедуру с существующим приложением Python Agent Framework. Сохраните агент и сборщик в той же локальной среде в рамках этого пошагового разбора.

Выберите Foundry Toolkit на панели действий, затем Средства разработчика>Монитор>.
Выберите Start Collector перед запуском приложения.
В Python среде приложения установите экспортер gRPC, если он еще не объявлен в зависимости:
```
python -m pip install opentelemetry-exporter-otlp-proto-grpc
```
См.: экспортеры OTLP для OpenTelemetry Python.
Настройте OpenTelemetry один раз при запуске приложения перед созданием или запуском агента:
```
import os

os.environ["OTEL_EXPORTER_OTLP_ENDPOINT"] = "http://localhost:4317"
os.environ["OTEL_EXPORTER_OTLP_PROTOCOL"] = "grpc"

from agent_framework.observability import configure_otel_providers

configure_otel_providers(enable_sensitive_data=False)
```
Справка: наблюдаемость Agent Framework.

Если приложение или библиотека хостинга уже настраивает поставщиков OpenTelemetry, настройте её существующие экспортеры вместо добавления другой настройки поставщика. Переменные, относящиеся OTEL_EXPORTER_OTLP_*_ENDPOINT к сигналу, могут переопределить базовую конечную точку. Проверьте наличие существующих настроек трассировки, журналирования или метрик, указывающих на другое расположение.
Запустите приложение с обычной точкой входа и отправьте запрос, который задействует агент. Пусть запрос завершится и дайте экспортеру время, чтобы отправить телеметрию, перед остановкой процесса.
В разделе Трассировка выберите Обновить, затем выберите новую трассировку, чтобы просмотреть её спаны.

Agent Framework обеспечивает инструментирование поддерживаемых клиентов моделей, агентов и операций рабочего процесса. Для других фреймворков может потребоваться библиотека инструментирования. Совместимость с OTLP позволяет сборщику получать данные, в то время как выдаваемые атрибуты и семантические соглашения генеративного ИИ определяют, что отображает средство просмотра.

Для другого пакета SDK или языка используйте приведённые ниже настройки вместо конфигурации Agent Framework. Сначала запустите сборщик, настройте инструментирование перед созданием клиентов, а затем запустите приложение и обновите список трассировки.

Эндпоинты сборщика

Сопоставьте протокол экспортера с конечной точкой сборщика. Toolkit ожидает подключения на localhost со следующими значениями по умолчанию:

Экспортер	Endpoint
OTLP gRPC	`http://localhost:4317`
Экспорт трассировки HTTP OTLP	`http://localhost:4318/v1/traces`
HTTP-экспортер логов OTLP	`http://localhost:4318/v1/logs`

Некоторые экспортеры HTTP принимают http://localhost:4318 и добавляют путь сигнала сами. Следуйте конфигурации экспортера, а не добавляйте путь дважды. Некоторые библиотеки инструментирования отправляют содержимое сообщения в виде записей журнала, поэтому экспорт спанов может не предоставлять входные и выходные данные.

Эти порты не связаны с HTTP-сервером агента и портами отладчика. В контейнере или в удаленной среде разработки localhost относится к этой среде. Установите соответствующее подключение к коллектору, а не предполагайте, что он относится к рабочему столу.

Настройка SDK Python

В следующих примерах предполагается, что у приложения уже есть пакет SDK для модели, учетные данные и конфигурация модели. Установите общие зависимости и дополнительный пакет для вашего SDK из следующей таблицы:

python -m pip install opentelemetry-sdk opentelemetry-exporter-otlp-proto-http

Ссылка: OpenTelemetry Python SDK, экспортеры OTLP.

Добавьте эту общую настройку сразу при запуске приложения, а затем инструментирование из одной из строк таблицы. Не сочетайте его с настройкой провайдера другой библиотеки.

import os

os.environ["TRACELOOP_TRACE_CONTENT"] = "false"
os.environ["OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT"] = "false"
os.environ["AZURE_TRACING_GEN_AI_CONTENT_RECORDING_ENABLED"] = "false"

from opentelemetry import trace
from opentelemetry.sdk.resources import Resource
from opentelemetry.sdk.trace import TracerProvider
from opentelemetry.sdk.trace.export import BatchSpanProcessor
from opentelemetry.exporter.otlp.proto.http.trace_exporter import (
    OTLPSpanExporter,
)

provider = TracerProvider(
    resource=Resource.create({"service.name": "my-agent"})
)
provider.add_span_processor(BatchSpanProcessor(
    OTLPSpanExporter(endpoint="http://localhost:4318/v1/traces")
))
trace.set_tracer_provider(provider)

Справочник: TracerProvider и обработчики спанов, OTLPSpanExporter.

Установите пакет в выбранной строке с помощью python -m pip install <package>. Примеры OpenAI, Anthropic, LangChain и отдельных агентов OpenAI используют инструментирование OpenLLMetry, не относящееся к Microsoft. Версии пакета SDK и API модели могут выдавать разные детали.

SDK	Дополнительный пакет	Инструментирование после общей конфигурации
OpenAI, включая клиентов Azure OpenAI	`opentelemetry-instrumentation-openai`	`from opentelemetry.instrumentation.openai import OpenAIInstrumentor` `OpenAIInstrumentor().instrument()`
Anthropic	`opentelemetry-instrumentation-anthropic`	`from opentelemetry.instrumentation.anthropic import AnthropicInstrumentor` `AnthropicInstrumentor().instrument()`
LangChain	`opentelemetry-instrumentation-langchain`	`from opentelemetry.instrumentation.langchain import LangchainInstrumentor` `LangchainInstrumentor().instrument()`
Google GenAI	`opentelemetry-instrumentation-google-genai`	`os.environ["OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT"] = "NO_CONTENT"` `from opentelemetry.instrumentation.google_genai import GoogleGenAiSdkInstrumentor` `GoogleGenAiSdkInstrumentor().instrument()`
Клиентская трассировка Foundry Projects (предварительная версия)	`azure-core-tracing-opentelemetry`, наряду с `azure-ai-projects`	`os.environ["AZURE_EXPERIMENTAL_ENABLE_GENAI_TRACING"] = "true"` `from azure.ai.projects.telemetry import AIProjectInstrumentor` `AIProjectInstrumentor().instrument(enable_content_recording=False)`
Foundry classic Agents SDK	`azure-core-tracing-opentelemetry`, наряду с `azure-ai-agents`	`os.environ["AZURE_SDK_TRACING_IMPLEMENTATION"] = "opentelemetry"` `from azure.ai.agents.telemetry import AIAgentsInstrumentor` `AIAgentsInstrumentor().instrument()`
Azure AI Inference SDK (предварительная версия)	`azure-core-tracing-opentelemetry`, наряду с `azure-ai-inference`	`os.environ["AZURE_SDK_TRACING_IMPLEMENTATION"] = "opentelemetry"` `from azure.ai.inference.tracing import AIInferenceInstrumentor` `AIInferenceInstrumentor().instrument()`

Для Foundry Projects следуйте инструкциям по трассировке на стороне клиента и создайте клиент OpenAI для него после инструментирования. Это руководство отличается от classic Agents SDK. Не инструментируйте одни и те же вызовы OpenAI с помощью и AIProjectInstrumentor, и отдельного инструментатора OpenAI.

Для пакета SDK для агентов OpenAI установите opentelemetry-instrumentation-openai-agents и добавьте этот код после общей установки:

from agents import set_trace_processors
from opentelemetry.instrumentation.openai_agents import OpenAIAgentsInstrumentor

set_trace_processors([])
OpenAIAgentsInstrumentor().instrument()

См.: Инструментирование агентов OpenAI, Трассировка агентов OpenAI.

Этот пример заменяет существующие процессоры трассировки перед добавлением процессора OpenTelemetry. Без этой замены пакет SDK также может экспортировать трассировки в бэкенд по умолчанию. Если вам нужны сведения о существующих процессорах, просмотрите назначения трассировки перед их изменением. Оставьте трассировку пакета SDK включенной, чтобы обработчик OpenTelemetry получал события.

После того как кратковременное приложение завершит свои запросы, вызовите provider.force_flush() перед выходом, чтобы отправить буферизованные спаны. Чтобы получить помощь по адаптации этих фрагментов, используйте инструмент Tracing Code Gen Toolkit.

Экспорт записей журнала сообщений

Некоторые инструментаторы выдают содержимое сообщения в виде записей журнала OpenTelemetry, а не атрибутов спана. Если вы решили записать это содержимое в контролируемом тесте в среде разработки, добавьте эту настройку один раз вместе с предыдущим поставщиком трассировки Python:

from opentelemetry import _logs
from opentelemetry.sdk._logs import LoggerProvider
from opentelemetry.sdk._logs.export import BatchLogRecordProcessor
from opentelemetry.exporter.otlp.proto.http._log_exporter import OTLPLogExporter

logger_provider = LoggerProvider(resource=provider.resource)
logger_provider.add_log_record_processor(BatchLogRecordProcessor(
    OTLPLogExporter(endpoint="http://localhost:4318/v1/logs")
))
_logs.set_logger_provider(logger_provider)

Справка: OpenTelemetry Python SDK для логирования, OTLPLogExporter.

Вызовите logger_provider.force_flush() перед выходом из кратковременного приложения. Экспортер журналов сам по себе не включает запись содержимого. Следуйте параметрам содержимого Instrumentor и руководству по обработке данных.

Настройка пакета SDK для JavaScript и TypeScript

Для приложений Node.js используйте один общий поставщик трассировки и зарегистрируйте инструментирование для вашего SDK. В этом примере используется CommonJS и конфигурация провайдера OpenTelemetry JavaScript 2.x. Приложения TypeScript, скомпилированные в CommonJS, могут использовать тот же порядок инициализации.

Приложение уже должно иметь свой пакет SDK для модели, учетные данные и конфигурацию модели. Установите общие зависимости и инструментатор OpenAI:

npm install @opentelemetry/api @opentelemetry/sdk-trace-node \
  @opentelemetry/sdk-trace-base @opentelemetry/exporter-trace-otlp-proto \
  @opentelemetry/instrumentation @traceloop/instrumentation-openai

Справочник: экспортеры JavaScript OpenTelemetry, инструментирование OpenAI.

Создайте tracing.cjs:

const { NodeTracerProvider } = require('@opentelemetry/sdk-trace-node');
const { BatchSpanProcessor } = require('@opentelemetry/sdk-trace-base');
const {
  OTLPTraceExporter
} = require('@opentelemetry/exporter-trace-otlp-proto');
const { registerInstrumentations } = require('@opentelemetry/instrumentation');
const { OpenAIInstrumentation } = require('@traceloop/instrumentation-openai');

const provider = new NodeTracerProvider({
  spanProcessors: [
    new BatchSpanProcessor(new OTLPTraceExporter({
      url: 'http://localhost:4318/v1/traces'
    }))
  ]
});
provider.register();

registerInstrumentations({
  instrumentations: [new OpenAIInstrumentation({ traceContent: false })]
});

module.exports = provider;

См.: NodeTracerProvider, инструментирование OpenAI.

Загрузите этот файл перед импортом или подключением через require вашего SDK модели. Например, запустите node --require ./tracing.cjs app.cjs для приложения CommonJS. Для другого пакета SDK замените пакет OpenAI, импорт и запись регистрации элементом из соответствующей строки:

SDK	Пакет инструментирования	Запись об импорте и регистрации
OpenAI, включая клиентов Azure OpenAI	`@traceloop/instrumentation-openai`	`const { OpenAIInstrumentation } = require('@traceloop/instrumentation-openai');` `new OpenAIInstrumentation({ traceContent: false })`
Anthropic	`@traceloop/instrumentation-anthropic`	`const { AnthropicInstrumentation } = require('@traceloop/instrumentation-anthropic');` `new AnthropicInstrumentation({ traceContent: false })`
LangChain	`@traceloop/instrumentation-langchain`	`const { LangChainInstrumentation } = require('@traceloop/instrumentation-langchain');` `new LangChainInstrumentation({ traceContent: false })`
операции Azure SDK, включая Azure AI Inference	`@azure/opentelemetry-instrumentation-azure-sdk`	`const { createAzureSdkInstrumentation } = require('@azure/opentelemetry-instrumentation-azure-sdk');` `createAzureSdkInstrumentation()`

Пакеты Traceloop не являются инструментированием Microsoft. Для приложения Foundry Projects настройте инструментирование клиента, который отправляет запрос к модели. Azure SDK инструментирование не заменяет инструментирование OpenAI для вызовов, выполненных через клиент OpenAI.

Для нативных модулей ECMAScript выполните настройку ESM OpenTelemetry. Загрузка инструментирования после целевого пакета SDK может оставить вызовы неинструментированными. При завершении работы дождитесь provider.shutdown() после завершения запросов на экспорт буферизованных спанов.

Important

Эти примеры отключают запись содержимого сообщений для перечисленных инструментаторов GenAI. Это не общая гарантия сокрытия данных. Перед предоставлением общего доступа к данным просмотрите другие экспортеры, ведение журнала пакета SDK, атрибуты спана и настраиваемое инструментирование. Ознакомьтесь с документацией по инструментатору по ссылке для поддерживаемых пакетов и API.

Проверяйте локальные трассировки и управляйте ими

Используйте дерево спанов, чтобы отследить запрос от оркестрации агентов до операций модели и инструментов.

Выберите медленный или неудачный спан.
Проверьте его длительность и состояние.
Откройте Input + Output для записанных сообщений, если они предоставляются средствами инструментирования, или Metadata для атрибутов спана.

Примеры оставляют захват конфиденциального содержимого отключённым. Данные о тайминге без сообщений могут быть ожидаемым результатом.

Для управляемого теста разработки Agent Framework задайте enable_sensitive_data=True в существующей конфигурации, чтобы записывать поддерживаемое содержимое запроса, ответа и средства. Восстановите его до False, когда тест будет завершён. У других инструменторов есть собственные настройки контента.

Caution

Запись содержимого может захватывать персональные данные, секреты, аргументы инструментов и результаты. Используйте нечувствительные тестовые данные и минимизируйте содержимое или удаляйте из него конфиденциальные фрагменты до его попадания в телеметрию. Не включайте запись боевого контента исключительно для заполнения пустой входной и выходной панели.

Собранные трассировки сохраняются в локальной базе данных SQLite с именем traces.db в подкаталоге tracing.aitk в домашней папке пользователя. Закрытие средства просмотра не удаляет их.

Выберите Остановить сбор, чтобы остановить локальный сбор. Ваш агент и его вызовы модели продолжают выполняться. Чтобы удалить локальные записи, выберите трассировки в списке и нажмите кнопку Удалить.

Локальное хранилище отличается от Application Insights. Удаление локальных трассировок не удаляет облачную телеметрию, а очистка разговора в Inspector не удаляет ни одно из хранилищ.

Просмотреть трассировки размещенного агента

После развертывания используйте облачные трассировки для изучения агента, работающего в Foundry, а не локального процесса. Набор средств запрашивает подключенный ресурс Application Insights проекта. Локальная база данных трассировки не загружается.

Перед началом работы убедитесь, что выполнены предварительные требования к облаку. Сам по себе доступ к агенту не дает права запрашивать телеметрию.

Подключите Application Insights и проверьте запрос

Используйте вкладку агента Traces, чтобы подключить Application Insights и найти запрос развернутого агента.

На боковой панели набора средств Foundry откройте Мои ресурсы>Агенты. Перейдите на вкладку Hosted Agent, а затем выберите имя агента.
Выберите Трассировки. Если у проекта нет подключенного ресурса, выберите Enable App Insights.
В параметрах App Insights выберите существующее имя ресурса Application Insights. Либо выберите создание ресурса и заполните обязательные поля ресурса и рабочей области. Нажмите кнопку Отправить и подождите подтверждения.

Это изменяет общее подключение Application Insights проекта, а не предпочтение локальной рабочей области. Создание ресурсов и сбор телеметрии может повлечь расходы в Azure. Перед отправкой убедитесь, что выбраны нужные проект и ресурс.
Вернитесь в Playground и отправьте тестовый запрос развернутому агенту.
Подождите, пока данные будут обработаны, а затем снова откройте Traces. Используйте фильтры «Диапазон времени», Поиск по идентификатору беседы, Статус или Длительность, чтобы найти обращение.
Выберите трейс, а затем спан, чтобы просмотреть метаданные и входные и выходные данные, когда содержимое доступно.

Чтобы проверить операции, связанные с беседой, выберите ее идентификатор беседы в списке трассировки. В представлении беседы показаны дерево операций и метаданные.

Подключение Application Insights обеспечивает трассировку на стороне сервера Foundry. Видимость вызовов модели, вызовов инструментов и пользовательского кода также зависит от библиотеки хостинга и инструментирования фреймворка. См. сведения о настройке трассировки в Foundry для сбора на стороне службы и дополнительного клиентского инструментирования.

Запрос сведений трассировки Toolkit в настоящее время охватывает последние семь дней. Это окно запроса, а не параметр хранения. Для более старых данных используйте портал Foundry или Azure Monitor в соответствии с конфигурацией хранения подключенной рабочей области.

Данные, доступ, хранение и затраты

Определите, куда должны отправляться данные телеметрии, прежде чем включать запись содержимого или подключать облачный ресурс. Тот же запрос может создавать локальные спаны, облачную телеметрию и данные, отправленные поставщикам моделей или инструментов.

Источник данных	Responsibilities
Локальные трассы	Защитите доступ к локальной базе данных и скопированным данным. Остановка сборщика не останавливает других экспортеров, настроенных в приложении.
Облачные трассы	Application Insights и Log Analytics управляют доступом, хранением и тарификацией телеметрии. Фильтры Toolkit не изменяют эти политики.
Вызовы модели и инструментов	Локальная коллекция не препятствует тому, что запросы покидают ваш компьютер. Просмотрите обработку данных каждой подключенной службы, включая средства, отличные от Microsoft.

Используйте руководство по трассировке Foundry для обеспечения безопасности и конфиденциальности и хранения данных и затрат. Для идентификации в рабочей среде, сетевой изоляции и последующего доступа следуйте инструкциям по безопасности и обработке данных размещённого агента. Не рассматривайте локальные учетные данные как права доступа развернутого агента.

Troubleshooting

Issue	Что требуется проверить
Трассировка недоступна в боковой панели.	Убедитесь, что текущее расширение установлено и включено в среде, где вы его запускаете. Локальная трассировка требует, чтобы собственный компонент SQLite загрузился.
Сборщик не запускается.	Проверьте, не использует ли другой процесс порт 4317 или 4318, и просмотрите вывод Toolkit. Избегайте конфликтующих сборщиков на одних и тех же портах.
Локальный запрос завершается успешно, но трассировка не отображается.	Убедитесь, что инструментирование выполняется до выполнения запроса, что сборщик запущен и что экспортер использует правильный протокол и конечную точку. Проверьте переопределения конечных точек, ошибки экспорта и буферизованные данные телеметрии, а затем нажмите «Обновить».
Спаны отображаются без сообщений.	Проверьте параметры записи содержимого и поддерживаемые атрибуты. Для некоторых библиотек также требуется экспортер журналов. Отсутствующий контент не обязательно означает, что сбор данных завершился ошибкой.
Облачные трассировки пусты.	Подтвердите подключение проекта и Application Insights, создайте новый трафик, расширьте временной диапазон и учтите задержку поступления данных.
Облачные запросы завершаются ошибкой авторизации.	Проверьте наличие доступа на чтение к Application Insights и Log Analytics, включая защищенные таблицы, используя предварительные требования службы.
Для старой трассировки в Toolkit недоступны подробные сведения.	Запрос сведений охватывает семь дней. Запрос старых сохраненных записей в Foundry или Azure Monitor.

Обратная связь

Были ли сведения на этой странице полезными?

Последнее обновление: 2026-10-08