Премини към основното съдържание
Български— Изберете език
Меню

Наблюдаемост и OpenTelemetry

Урок 14 от 14 Обновен 2 ноември 2026 г. Напреднало
На тази страница
  1. Защо да наблюдавате вашите работни потоци
  2. Именувайте дейностите за по-добра четимост
  3. Извличане на проследявания програмно
  4. Управление на семплирането
  5. Мониторинг в продукционна среда
  6. Отстраняване на грешки в неуспешен работен поток
  7. Обобщение на курса
  8. Ключови изводи
  9. Проверете знанията си

Обновено на 2 ноември 2026 г. въз основа на SDK mistralai версия 3.7.0: методите за проследяване (trace) се намират под client.workflows.executions; техните асинхронни версии носят суфикса _async (изчакването на синхронната версия води до грешка), execution_id се предава като именован аргумент, а отговорите излагат otel_trace_data, span_tree и events (полетата spans, activity_count или error_count, четени от по-старата версия, вече не съществуват); traceparent се предава като параметър за изпълнение, тъй като HTTP заглавката е остаряла. Източници: Наблюдаемост на работни потоци · client-python.

Защо да наблюдавате вашите работни потоци

Един работен поток в продукционна среда може да свърже десетки дейности, да извика множество външни услуги и да се изпълнява от няколко секунди до няколко дни. Без наблюдаемост диагностицирането на проблем прилича на търсене на игла в купа сено: знаете, че изпълнението е се провалило, но не знаете на коя стъпка, след колко опита или дали виновникът е вашият код, или API на трета страна. Платформата Mistral Workflows интегрира OpenTelemetry по подразбиране, за да отговори на този въпрос: всяка дейност, всяка грешка и всяка продължителност се записват като span (обхват) в разпределено проследяване, без да е необходима никаква инструментация от ваша страна.

Две понятия структурират този модел. Проследяването (trace) представлява целия път на едно изпълнение, от първоначалното задействане до крайния резултат. Обхватът (span), от друга страна, е индивидуална операция в рамките на това проследяване: всяка дейност автоматично генерира такъв, носещ своето име, време на начало и край, продължителност на изпълнение, статус (успех или грешка) и всички персонализирани атрибути. Тези обхвати формират йерархия – обхватът на работния поток е родител, а обхватите на дейностите са негови деца – което възпроизвежда пълната структура на изпълнението.

Именувайте дейностите за по-добра четимост

Параметърът name на декоратора за дейност определя етикета, който се появява в проследяванията. Това е инвестиция от десет секунди по време на писането на кода, която ще ви спести много време по време на инцидент.

import mistralai.workflows as workflows

@workflows.activity(name="Extract source text")
async def extraire_texte(url: str) -> dict:
    async with httpx.AsyncClient() as client:
        response = await client.get(url)
    return {"texte": response.text}

@workflows.activity(name="Mistral sentiment analysis")
async def analyser_sentiment(texte: str) -> dict:
    client = Mistral()
    response = await client.chat.complete_async(
        model="mistral-large-latest",
        messages=[
            {"role": "system", "content": "Analyze the sentiment."},
            {"role": "user", "content": texte}
        ]
    )
    return {"sentiment": response.choices[0].message.content}

@workflows.activity(name="Send email notification")
async def envoyer_notification(destinataire: str, contenu: str) -> dict:
    # ...
    return {"status": "sent"}

Поставете се на мястото на дежурния инженер, който отваря изглед за проследяване в 3 сутринта. Между fetch_user_data и “Retrieve user profile” (Извличане на потребителски профил), второто е веднага разбираемо, дори за някой, който никога не е чел този код.

Извличане на проследявания програмно

SDK предоставя три метода за достъп под client.workflows.executions; техните асинхронни версии носят суфикса _async. Първият връща сурови данни на OpenTelemetry – обхвати, продължителности, атрибути, връзки родител-дете – което ви позволява да ги reinjectирате във вашия собствен инструмент за наблюдаемост (Jaeger, Grafana Tempo и др.).

from mistralai.client import Mistral

client = Mistral()

# Сурови данни на OpenTelemetry за изпълнението
trace = await client.workflows.executions.get_workflow_execution_trace_otel_async(
    execution_id="exec_abc123def456"
)

print(f"OTel Trace: {trace.otel_trace_id}")
otel_data = trace.otel_trace_data  # Пълно проследяване, за ре-експортиране към вашия бекенд

Когато основно искате да знаете дали изпълнението е успешно и колко време е отнело, обобщението е достатъчно. То включва статуса, общата продължителност и дървото с обхвати (span tree), което можете да обходите рекурсивно:

summary = await client.workflows.executions.get_workflow_execution_trace_summary_async(
    execution_id="exec_abc123def456"
)

print(f"Workflow: {summary.workflow_name} — status {summary.status}")
print(f"Total duration: {summary.total_duration_ms} ms")


def display(span, depth=0):
    end = span.end_time_unix_nano or span.start_time_unix_nano
    duration_ms = (end - span.start_time_unix_nano) / 1e6
    print(f"{'  ' * depth}{span.name}: {duration_ms:.0f} ms, {len(span.events)} event(s)")
    for child in span.children or []:
        display(child, depth + 1)


if summary.span_tree:
    display(summary.span_tree)

Третият метод връща хронологичен списък със събития от изпълнението:

response = await client.workflows.executions.get_workflow_execution_trace_events_async(
    execution_id="exec_abc123def456",
    include_internal_events=False,  # Изключва вътрешните събития на платформата
)

for event in response.events or []:
    print(event)

Параметърът include_internal_events=False филтрира техническите събития на платформата, запазвайки само тези от вашия работен поток и дейности. При леко дълъг работен поток разликата в четимостта е значителна. За самите логове – тези, показани в Studio – get_workflow_execution_logs ги връща страница по страница.

Управление на семплирането

По подразбиране всички проследявания се експортират: worker-ът семплира на 100%. За да зададете ID на проследяване или да контролирате семплирането за дадено изпълнение, предайте traceparent във формат W3C в тялото на заявката за изпълнение. Worker-ът използва семплър, базиран на родител: той следва вашето решение, носено от последното поле (01 за събиране, 00 за несъбиране).

execution = await client.workflows.execute_workflow_async(
    workflow_identifier="my_workflow",
    input={"data": "test"},
    traceparent="00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01",
)

Mistral SDK правят това автоматично: при всяко изпълнение те предават traceparent на текущия обхват. Предаването на traceparent в HTTP заглавка все още се приема, но е остаряло, защото заглавката може да бъде презаписана по време на трансфер; използвайте параметъра вместо това.

Мониторинг в продукционна среда

Пет индикатора са достатъчни, за да държите работния поток под контрол: процентът на успех, т.е. процентът на изпълненията, завършващи без грешка; средната продължителност на пълно изпълнение; продължителностите P95 и P99, които разкриват най-бавните изпълнения, скрити от средната стойност; процентът на повторни опити (retry) на дейност, чието внезапно повишаване издава нестабилна външна услуга много преди процентът на успех да се влоши; и накрая, идентифицирането на най-бавната дейност, вашето тясно място.

Тъй като проследяванията спазват стандарта OpenTelemetry, нищо не ви задължава да ги консултирате от SDK: те могат да бъдат експортирани към Datadog чрез неговия OTel колектор, към Grafana и Tempo по същия механизъм, към Jaeger за визуализация на разпределени проследявания или към New Relic чрез неговия специализиран експортер. Така вашите работни потоци се присъединяват към таблото за управление, където вече живее останалата част от вашата инфраструктура.

Отстраняване на грешки в неуспешен работен поток

Пред лицето на неуспех, методична процедура избягва предположенията.

  1. Извлечете ID на изпълнението от логовете или отговора на API
  2. Консултирайте обобщението на проследяването, за да узнаете статуса и да откриете дефектната дейност в дървото с обхвати
  3. Разгледайте подробните събития, за да разберете последователността, довела до грешката
  4. Проверете повторните опити: дали дейността е рестартирана? Колко пъти?
  5. Анализирайте съобщението за грешка: изтекло време (timeout), мрежова грешка, бизнес грешка?

Първите две стъпки могат да бъдат скриптирани в няколко реда, използвайки функцията display, видяна по-горе, което ви дава многократен диагностичен инструмент.

async def diagnose_failure(execution_id: str):
    client = Mistral()
    executions = client.workflows.executions

    # Стъпка 1: Обобщение и дърво с обхвати
    summary = await executions.get_workflow_execution_trace_summary_async(execution_id=execution_id)
    print(f"Status: {summary.status}")
    if summary.span_tree:
        display(summary.span_tree)

    # Стъпка 2: Събития от вашия код, по ред
    response = await executions.get_workflow_execution_trace_events_async(
        execution_id=execution_id,
        include_internal_events=False,
    )
    for event in response.events or []:
        print(event)

Броят на опитите заслужава специално внимание: дейност, която се проваля при първия опит, и такава, която се проваля след пет повторни опита, разказват различни истории и изискват различни поправки.

Обобщение на курса

Поздравления, завършихте този курс за Mistral Workflows. Пътуването ви отведе от трайната оркестрация и механизма за извличане на събития (event sourcing) до инсталирането на SDK (уроци 1 до 3), след това към създаването на дейности, работни потоци и worker-и, тяхното задействане и тестване (уроци 4 до 7). Уроци 8 до 11 очертаха структурните ограничения – детерминизъм, входове на Pydantic, таймаути, ограничения – преди да се отворят към разширени модели на паралелизъм и продължаване. Последните три обхванаха политики за повторни опити, изискването за асинхронен I/O и наблюдаемостта с OpenTelemetry.

Платформата е в Public Preview: API и функциите могат да се променят. Проверете официалната документация редовно на docs.mistral.ai/workflows, за да следите актуализациите.

Ключови изводи

  • Всяка дейност автоматично генерира OpenTelemetry обхвати (spans) с име, продължителност и статус
  • Именувайте вашите дейности с параметъра name, за да улесните отстраняването на грешки
  • Три метода за достъп до проследявания, под client.workflows.executions: сурови OTel данни, обобщение (статус, продължителност, дърво с обхвати) и подробни събития
  • Семплирането се контролира от параметъра traceparent на изпълнението (100% по подразбиране; HTTP заглавката е остаряла)
  • В продукционна среда следете процента на успех, продължителността и процента на повторни опити
  • Стандартните OTel проследявания могат да се експортират към Datadog, Grafana, Jaeger или New Relic

Проверете знанията си

Трайни работни потоци: правила на двигателя преди продукцията.

1. Какво гарантира платформата Mistral Workflows?

Отговор: Трайност: един работен поток оцелява при повреди и възобновява работата си оттам, където е спрял – дълготрайната оркестрация става надеждна по дизайн.

2. Дейност, работен поток, worker: кой какво прави?

Отговор: Дейността е единицата работа (външно извикване, изчисление), работният поток оркестрира дейностите, worker-ът изпълнява – разделението, което позволява възобновяване и мащабиране.

3. Какво налага правилото за детерминизъм?

Отговор: Кодът на работния поток трябва да може да се възпроизвежда идентично: без случайност или директен достъп до часовника в оркестрацията – недетерминистичните ефекти живеят в дейностите.

4. Как се обработват преходните грешки?

Отговор: Чрез политиката за повторни опити на дейността (опити, backoff) и таймаути – грешката е нормален случай, обработван декларативно, а не ръчно.

5. Какво носи интеграцията с OpenTelemetry?

Отговор: Стандартна наблюдаемост: проследявания на изпълнения, метрики и корелация с останалата част от вашата система – от съществено значение за оперирането на работни потоци в продукционна среда.

Трайност, детерминизъм, повторни опити, наблюдаемост: четири правила, които държат дългите оркестрации заедно – двигателят се грижи за останалото.