Как протестировать NoOpSpan при отключённом tracing

Сигнатуры и поведение проверены 13 сентября 2026 года по руководству OpenAI Agents SDK, общему API reference tracing и профильному reference. при отключённом provider create_span возвращает NoOpSpan: trace_id и span_id равны no-op, error и export возвращают None. Цены, тарифы и неподтверждённые лимиты в материале не используются. Версию зависимости фиксируйте в lock-файле и повторяйте контрактные тесты после обновления.

Важно разделять бизнес-успех и успех telemetry. Ошибка exporter не должна превращать уже выполненную бизнес-операцию в повторную, иначе возможен дубль платежа или задания. Одновременно нельзя молча объявлять tracing надёжным: измеряйте созданные, завершённые, отправленные и отброшенные события отдельно.

Архитектура решения

В примере есть четыре слоя. Первый создаёт или получает provider. Второй формирует trace/span data только из разрешённых технических полей. Третий управляет start, finish, flush и shutdown. Четвёртый проверяет результат через свойства объекта или export. Такая схема отделяет конфигурацию от предметного кода и делает ошибки воспроизводимыми.

Не записывайте в name динамические идентификаторы пользователей: используйте стабильное имя операции, а корреляцию храните в безопасном group_id либо ограниченной metadata. Input и output могут содержать чувствительные данные, поэтому примеры используют исключительно искусственные значения. Для production создайте allowlist полей и тест с секретным маркером.

Пошаговая инструкция

1. Создайте отдельное виртуальное окружение и установите пакет openai-agents; точную версию зафиксируйте тем же инструментом зависимостей, который использует проект.
2. Вынесите tracing bootstrap в один модуль. Зафиксируйте, кто вызывает shutdown при завершении процесса.
3. Импортируйте только официальные классы и helpers, указанные в reference. Не обращайтесь к приватным полям с подчёркиванием в production-коде.
4. Подготовьте искусственный вход без токенов, email, текста реального клиента и содержимого внутренних документов.
5. Вызовите DefaultTraceProvider.set_disabled(True) и сохраните возвращённый объект, если его свойства участвуют в контрактной проверке.
6. Для ручного lifecycle используйте try/finally. Если объект становится текущим, при завершении обязательно восстановите contextvar.
7. Проверьте конкретные поля: формат ID, parent_id, span_data, started_at/ended_at, export либо identity provider.
8. Запустите негативный сценарий. Успех без такого теста не доказывает, что конфигурация ловит неправильную связь или утечку контекста.
9. В отдельном concurrency-тесте запустите две asyncio-задачи и убедитесь, что их current trace/span не смешиваются.
10. Перед выпуском вызовите flush там, где процесс короткоживущий, затем shutdown владельца processor/provider.

Готовый код

from agents.tracing.provider import DefaultTraceProvider
from agents.tracing.span_data import CustomSpanData

provider = DefaultTraceProvider()
provider.set_disabled(True)
span = provider.create_span(CustomSpanData("disabled_step", {"safe": True}))

with span as current:
    assert current.span_id == "no-op"
    assert current.trace_id == "no-op"
    assert provider.get_current_span() is current

assert provider.get_current_span() is None
assert span.parent_id is None
assert span.error is None
assert span.export() is None
print("noop_contract_verified")

Код можно скопировать в отдельный тестовый файл. Assertions являются частью решения: они превращают предположение о tracing в проверяемый контракт. Если пример использует тестовый ключ или домен example.test, не заменяйте их реальными значениями в репозитории. Секрет передавайте через менеджер секретов или переменную окружения только во время выполнения.

Реалистичный пример входа и результата

Вход: Provider отключён до создания технического span disabled_step с безопасным тестовым флагом.

Ожидаемый результат: Context manager работает, ID равны no-op, после выхода current span очищен, экспорт отсутствует.

Проверяйте структуру, а не случайное значение сгенерированного ID или микросекунды времени. Для идентификатора важны префикс, формат, уникальность и сохранение связи. Для lifecycle важны наличие отметок и очистка contextvar. Для exporter важны полученная пачка, отсутствие секретов и корректное закрытие клиента.

Негативный тест

После теста включите provider и создайте новый span внутри реальной trace. Он не должен иметь no-op ID; так обнаруживается забытый глобальный disabled.

Негативный сценарий должен быть автоматическим. Если он лишь описан в документации команды, регрессия останется незаметной. Поместите его рядом с позитивным тестом и запускайте в CI без реального сетевого экспорта. Для сетевой части используйте управляемый mock endpoint, который записывает количество запросов, заголовки без вывода секрета и последовательность кодов ответа.