# Investigando execuções

O melhor uso do MCP do TunnelHub hoje é investigação operacional.

Em vez de navegar manualmente pelo portal, você pode combinar ferramentas para localizar uma execução, abrir o resumo e seguir para logs ou traces.

## Fluxo recomendado

O fluxo mais seguro costuma ser:

1. localizar a execução por janela de tempo;
2. capturar `automationId`, `executionId` e `executionPeriod`;
3. abrir o resumo da execução;
4. aprofundar em logs ou traces.

## Passo 1: encontrar a execução

Use `find_execution_tunnelhub` quando você já tem uma janela de tempo e quer localizar uma execução específica.

Exemplo de parâmetros:

```json
{
  "startDate": "2026-03-17 00:00:00",
  "endDate": "2026-03-17 23:59:59",
  "automationId": "<automation-id>",
  "status": "ERROR"
}
```

Essa etapa é importante porque as ferramentas de detalhe exigem `executionPeriod` no formato `YYYY-MM`.

## Passo 2: abrir o resumo

Depois de encontrar a execução, use `summarize_execution_tunnelhub` ou `get_execution_tunnelhub`.

Exemplo conceitual:

```json
{
  "automationId": "<automation-id>",
  "executionId": "<execution-id>",
  "executionPeriod": "2026-03"
}
```

O resumo é o melhor ponto de entrada para entender:

* status consolidado;
* mensagens principais;
* volume processado;
* indícios iniciais de falha.

## Passo 3: abrir traces

Quando o problema parece técnico, siga para `get_execution_traces_tunnelhub`.

Use filtros quando quiser reduzir ruído, por exemplo:

* `level`;
* `status`;
* `message`;
* `timestampStart` e `timestampEnd`.

Os traces ajudam mais quando você quer reconstruir a sequência de eventos internos da execução.

## Passo 4: abrir logs de processamento

Quando o problema parece ligado a registros de negócio, use `get_execution_logs_tunnelhub`.

Esse caminho é ideal para responder perguntas como:

* quais itens falharam;
* qual ação foi tentada;
* quais mensagens apareceram por item;
* como os metadados definidos no SDK explicam o erro.

## Quando usar cada ferramenta

* `find_execution_tunnelhub`: localizar a execução certa.
* `summarize_execution_tunnelhub`: obter contexto rápido.
* `get_execution_tunnelhub`: abrir o detalhe estruturado.
* `get_execution_traces_tunnelhub`: investigar comportamento técnico.
* `get_execution_logs_tunnelhub`: investigar itens de negócio.

## Exemplo de pergunta em linguagem natural

Você pode pedir algo como:

"Encontre execuções com erro da automação X hoje, resuma a mais recente e destaque os traces com falha."

O bom resultado depende de informar:

* período;
* automação, quando conhecida;
* status desejado;
* profundidade esperada da análise.

## Cuidados práticos

* sempre informe janela de tempo explícita nas buscas;
* guarde `executionPeriod`, porque ele é obrigatório nas ferramentas de detalhe;
* lembre que logs e traces podem conter dados sensíveis dependendo da automação;
* sanitize qualquer saída antes de reutilizar o conteúdo em documentação pública ou tickets externos.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.tunnelhub.io/mcp/investigating-executions.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.