Observabilidade e OpenTelemetry
Nesta página
Atualizado em 2 de novembro de 2026 com base no SDK
mistralai3.7.0: os métodos de rastreio estão localizados emclient.workflows.executions; as suas versões assíncronas têm o sufixo_async(aguardar a versão síncrona falha), oexecution_idé passado como um argumento nomeado e as respostas expõemotel_trace_data,span_treeeevents(os camposspans,activity_countouerror_countlidos pela versão anterior deixaram de existir); otraceparenté 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.
- Recuperar o ID da execução a partir dos registos ou da resposta da API
- Consultar o resumo do rastreio para conhecer o estado e detetar a atividade com falha na árvore de spans
- Examinar os eventos detalhados para compreender a sequência que levou ao erro
- Verificar as repetições: a atividade foi reiniciada? Quantas vezes?
- 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
namepara 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
traceparentda 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.