Ir para o conteúdo principal
Português— Escolher um idioma
Menu

Observabilidade e OpenTelemetry

Aula 14 de 14 Atualizada a 2 de novembro de 2026 Avancado
Nesta página
  1. Por que observar os seus workflows
  2. Nomeie as atividades para legibilidade
  3. Recuperar rastreios programaticamente
  4. Dominar a amostragem
  5. Monitorizar em produção
  6. Depurar um workflow com falha
  7. Resumo do curso
  8. Pontos-chave
  9. Teste os seus conhecimentos

Atualizado em 2 de novembro de 2026 com base no SDK mistralai 3.7.0: os métodos de rastreio estão localizados em client.workflows.executions; as suas versões assíncronas têm o sufixo _async (aguardar a versão síncrona falha), o execution_id é passado como um argumento nomeado e as respostas expõem otel_trace_data, span_tree e events (os campos spans, activity_count ou error_count lidos pela versão anterior deixaram de existir); o traceparent é passado como um parâmetro de execução, pois o cabeçalho HTTP está obsoleto. Fontes: Observabilidade de workflows · client-python.

Por que observar os seus workflows

Um workflow em produção pode encadear dezenas de atividades, chamar múltiplos serviços externos e executar desde alguns segundos até vários dias. Sem observabilidade, diagnosticar um problema é como procurar uma agulha num palheiro: sabe que a execução falhou, mas não em que passo, após quantas tentativas, ou se o culpado é o seu código ou uma API de terceiros. A plataforma Workflows da Mistral integra o OpenTelemetry nativamente para responder a esta questão: cada atividade, cada erro e cada duração é registado como um span num rastreio distribuído, sem necessidade de instrumentação da sua parte.

Dois conceitos estruturam este modelo. O rastreio (trace) representa toda a jornada de uma execução, desde o gatilho inicial até ao resultado final. O span, por outro lado, é uma operação individual dentro desse rastreio: cada atividade gera automaticamente um, contendo o seu nome, horas de início e fim, duração da execução, estado (sucesso ou erro) e quaisquer atributos personalizados. Estes spans formam uma hierarquia — o span do workflow é o pai e os spans das atividades são os seus filhos — que reproduz a estrutura completa da execução.

Nomeie as atividades para legibilidade

O parâmetro name do decorador de atividade determina o rótulo que aparece nos rastreios. É um investimento de dez segundos na escrita que lhe poupará muito tempo durante um incidente.

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"}

Coloque-se no lugar do engenheiro de guarda que abre uma vista de rastreio às 3 da manhã. Entre fetch_user_data e “Retrieve user profile”, este último é imediatamente compreensível, mesmo para alguém que nunca leu este código.

Recuperar rastreios programaticamente

O SDK expõe três métodos de acesso sob client.workflows.executions; as suas versões assíncronas têm o sufixo _async. O primeiro devolve dados OpenTelemetry brutos — spans, durações, atributos, relações pai-filho — permitindo-lhe reingeri-los na sua própria ferramenta de observabilidade (Jaeger, Grafana Tempo, etc.).

from mistralai.client import Mistral

client = Mistral()

# Dados OpenTelemetry brutos para a execução
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  # Rastreio completo, para reexportar para o seu backend

Quando quer principalmente saber se a execução teve sucesso e quanto tempo demorou, o resumo é suficiente. Inclui o estado, a duração total e a árvore de spans, que pode percorrer recursivamente:

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

print(f"Workflow: {summary.workflow_name} — estado {summary.status}")
print(f"Duração total: {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)} evento(s)")
    for child in span.children or []:
        display(child, depth + 1)


if summary.span_tree:
    display(summary.span_tree)

O terceiro método devolve uma lista cronológica de eventos de execução:

response = await client.workflows.executions.get_workflow_execution_trace_events_async(
    execution_id="exec_abc123def456",
    include_internal_events=False,  # Excluir eventos internos da plataforma
)

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

O parâmetro include_internal_events=False filtra os eventos técnicos da plataforma, mantendo apenas os do seu workflow e das suas atividades. Num workflow ligeiramente longo, a diferença de legibilidade é considerável. Para os próprios registos — aqueles exibidos no Studio — get_workflow_execution_logs devolve-os página a página.

Dominar a amostragem

Por predefinição, todos os rastreios são exportados: o worker faz amostragem a 100%. Para definir o ID do rastreio ou controlar a amostragem de uma execução, passe um traceparent no formato W3C no corpo do pedido de execução. O worker utiliza um amostrador baseado no pai: segue a sua decisão, transportada pelo último campo (01 para recolher, 00 para não recolher).

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

Os SDKs da Mistral fazem isto automaticamente: com cada execução, transmitem o traceparent do span atual. Passar o traceparent num cabeçalho HTTP ainda é aceite, mas está obsoleto, porque um cabeçalho pode ser reescrito em trânsito; utilize antes o parâmetro.

Monitorizar em produção

Cinco indicadores são suficientes para manter um workflow sob controlo: a taxa de sucesso, ou seja, a percentagem de execuções que terminam sem erro; a duração média de uma execução completa; as durações P95 e P99, que revelam as execuções mais lentas que a média esconde; a taxa de repetição por atividade, cujo aumento súbito denuncia um serviço externo instável muito antes de a taxa de sucesso se degradar; e, finalmente, a identificação da atividade mais lenta, o seu gargalo.

Como os rastreios respeitam o padrão OpenTelemetry, nada o obriga a consultá-los a partir do SDK: podem ser exportados para o Datadog através do seu coletor OTel, para o Grafana e Tempo pelo mesmo mecanismo, para o Jaeger para visualização de rastreios distribuídos, ou para o New Relic através do seu exportador dedicado. Os seus workflows integram assim o painel onde já reside o resto da sua infraestrutura.

Depurar um workflow com falha

Perante uma falha, um procedimento metódico evita adivinhações.

  1. Recuperar o ID da execução a partir dos registos ou da resposta da API
  2. Consultar o resumo do rastreio para conhecer o estado e detetar a atividade com falha na árvore de spans
  3. Examinar os eventos detalhados para compreender a sequência que levou ao erro
  4. Verificar as repetições: a atividade foi reiniciada? Quantas vezes?
  5. Analisar a mensagem de erro: timeout, erro de rede, erro de negócio?

Os dois primeiros passos podem ser scriptados em poucas linhas, utilizando a função display vista acima, dando-lhe uma ferramenta de diagnóstico reutilizável.

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

    # Passo 1: Resumo e árvore de spans
    summary = await executions.get_workflow_execution_trace_summary_async(execution_id=execution_id)
    print(f"Estado: {summary.status}")
    if summary.span_tree:
        display(summary.span_tree)

    # Passo 2: Eventos do seu código, por ordem
    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)

O número de tentativas merece atenção especial: uma atividade que falha na primeira tentativa e outra que falha após cinco repetições contam histórias diferentes e exigem correções distintas.

Resumo do curso

Parabéns, concluiu este curso sobre Mistral Workflows. A jornada levou-o desde a orquestração durável e o mecanismo de event sourcing até à instalação do SDK (lições 1 a 3), passando pela criação de atividades, workflows e workers, acionando-os e testando-os (lições 4 a 7). As lições 8 a 11 estabeleceram as restrições de estruturação — determinismo, inputs Pydantic, timeouts, limitações — antes de abrir espaço para padrões avançados de paralelismo e continuação. As últimas três cobriram políticas de repetição, a exigência de I/O assíncrono e a observabilidade com OpenTelemetry.

A plataforma está em Pré-visualização Pública: as APIs e funcionalidades podem evoluir. Consulte regularmente a documentação oficial em docs.mistral.ai/workflows para acompanhar as atualizações.

Pontos-chave

  • Cada atividade gera automaticamente spans OpenTelemetry com nome, duração e estado
  • Nomeie as suas atividades com o parâmetro name para facilitar a depuração
  • Três métodos para aceder aos rastreios, sob client.workflows.executions: OTel bruto, resumo (estado, duração, árvore de spans) e eventos detalhados
  • A amostragem é controlada pelo parâmetro traceparent da execução (100% por predefinição; o cabeçalho HTTP está obsoleto)
  • Em produção, monitore a taxa de sucesso, a duração e a taxa de repetição
  • Os rastreios OTel padrão são exportáveis para Datadog, Grafana, Jaeger ou New Relic

Teste os seus conhecimentos

Workflows duráveis: regras do motor antes da produção.

1. O que garante a plataforma Mistral Workflows?

Resposta: Durabilidade: um workflow sobrevive a falhas e retoma onde parou — a orquestração de longa duração torna-se fiável por conceção.

2. Atividade, workflow, worker: quem faz o quê?

Resposta: A atividade é a unidade de trabalho (chamada externa, computação), o workflow orquestra as atividades, o worker executa — a separação que permite o retomar e o escalonamento.

3. O que impõe a regra do determinismo?

Resposta: O código do workflow deve ser reproduzível de forma idêntica: sem aleatoriedade ou acesso direto ao relógio na orquestração — os efeitos não deterministas vivem nas atividades.

4. Como são tratadas as falhas transitórias?

Resposta: Através da política de repetição da atividade (tentativas, backoff) e timeouts — a falha é um caso normal, tratado de forma declarativa em vez de manual.

5. O que traz a integração OpenTelemetry?

Resposta: Observabilidade padrão: rastreios de execução, métricas e correlação com o resto do seu sistema — essencial para operar workflows em produção.

Durabilidade, determinismo, repetição, observabilidade: quatro regras que mantêm coesas as longas orquestrações — o motor trata do resto.