instrumenting-with-mlflow-tracing

Этот навык MLflow описывает внедрение MLflow Tracing в Python-, TypeScript- и JavaScript-приложения, где важно видеть не только итог запроса, но и ход работы AI-системы. Он предназначен для observability во время разработки и оценки агентов: помогает выбрать операции, которые дают диагностическую ценность, запустить инструментированный код и проверить, что traces действительно дошли до эксперимента. Перед настройкой нужно определить язык проекта: для Python источник направляет к references/python.md, для TypeScript и JavaScript — к references/typescript.md. Если язык неочевиден, его предлагают определить по package.json, requirements.txt или pyproject.toml. Приоритет для трассировки — корневые операции и входные точки пайплайна, LLM-вызовы и embeddings, retrieval-запросы и получение документов, tool или function calls, решения агента по маршрутизации и выбору инструмента, а также обращения к внешним сервисам, HTTP API, файловой системе и очередям. Такой список связывает trace с практической диагностикой: по нему можно искать задержку, расход токенов, проблемы релевантности, ошибки внешней зависимости и неудачный выбор инструмента. Простые преобразования словарей и списков, форматирование, parsing, validation, загрузку конфигурации, emission метрик и чистые utility-функции источник предлагает не трассировать, потому что слишком мелкие spans создают шум. После изменения кода проверка обязательна. Сначала нужно реально выполнить приложение или агент так, чтобы сработала хотя бы одна instrumented operation. Затем через mlflow.search_traces() или MlflowClient().search_traces() проверяется, что trace появился в нужном experiment. Поскольку отправка может быть асинхронной, перед поиском следует вызвать mlflow.flush_trace_async_logging(). Одного пустого trace недостаточно: из mlflow.get_trace(trace_id).data.spans нужно убедиться, что записаны ожидаемые spans, и зафиксировать их имена и span_type. Пример из первоисточника использует assert, поэтому отсутствие traces превращается в проверяемую ошибку, а не в незаметный пропуск. Если traces не найдены, навык предлагает последовательную диагностику. Сначала проверяется, не выполнен ли поиск раньше экспорта фоновой очереди, затем tracking URI и локальный fallback в ./mlruns. После этого нужно убедиться, что выбран правильный experiment ID, сверив его с активным экспериментом, и посмотреть предупреждения autolog или framework-specific autolog. Последняя группа причин связана с сетью и авторизацией tracking server, включая 401 и 403. Для автоматической проверки источник указывает validate_tracing_runtime.py. Это не замена наблюдаемому запуску: приложение всё равно должно породить реальную операцию и trace. Дополнительные разделы покрывают feedback для traces, сохранение рейтингов и комментариев через mlflow.log_feedback(), возврат trace ID клиенту и LLM-as-judge evaluation. Для production предусмотрены отдельные рекомендации по environment variables, асинхронному логированию, MLFLOW_TRACE_SAMPLING_RATIO и lightweight SDK mlflow-tracing. Для сложных систем есть материалы по async-функциям, передаче контекста между потоками, PII-redaction через span processors и distributed tracing. Карточка полезна как проверяемый маршрут instrumentation и verification, но сама по себе не выбирает tracking server, experiment или политику хранения: эти параметры остаются частью конкретного проекта.