# Ocorrências

> A linha do tempo persistente de toda aresta de ocorrência, observada pelo juiz de uma execução ou pelo vigia do modo Sempre fora de execução, com a condição congelada por trás de cada uma.

A aba Ocorrências de [Eventos](events) (`/events?view=occurrences`) é a linha do tempo persistente
do que as coisas sob teste fizeram: uma linha por **aresta de ocorrência**, tenha sido o juiz de uma
execução ou o vigia do modo **Sempre**, de fora de execução, quem a observou. Vê-la exige **Ver eventos**;
exportar exige **Exportar/importar históricos**. As ocorrências são definidas por modelo em
[Process > Preparação > Ocorrências](process-occurrences); esta aba lê o histórico delas e não muda nada.

Ela segue a conduta compartilhada das três linhas do tempo descrita em
[Eventos](events#how-the-three-timelines-behave): 500 linhas por página com um paginador embaixo,
um período, uma busca com atraso, atualização ao vivo, um painel de detalhes, exportação CSV e JSON
do período inteiro.

## O que é uma linha {#what-one-row-is}

Uma ocorrência é uma condição booleana sobre os canais de um modelo, com um atraso para ligar e um
atraso para desligar. Uma linha é uma das quatro transições de uma **sessão de observação**:

| Transição | Significado |
| --- | --- |
| Ativada | A condição subiu e se manteve pelo atraso para ligar. |
| Normalizada | A condição caiu e se manteve pelo atraso para desligar. |
| Indisponível | Um ou mais canais que a condição referencia pararam de entregar valor. O juiz segura a última condição confirmada e nunca fabrica uma normalização. |
| Restaurada | Todo canal referenciado entrega de novo; a condição é avaliada do zero e o seu atraso recomeça. |

Cada linha também diz em qual **escopo** ela foi observada e por que a sua sessão começou:

| Campo | Valores | Significado |
| --- | --- | --- |
| Escopo | **Execução**, **Fora de execução** | Execução: o juiz da própria execução, armado pelo procedimento; a aresta também é escrita no arquivo daquela execução. Fora de execução: o vigia do modo Sempre, que lê os vínculos da unidade entre execuções. |
| Motivo | **Execução iniciada**, **Execução retomada**, **Vigia iniciado**, **Observação fora de execução retomada**, **Definição alterada** | Por que uma sessão de observação nova começou: uma execução começou; uma execução foi retomada depois de a aplicação reiniciar; o vigia do modo Sempre começou para esta ocorrência e unidade; a unidade voltou à observação fora de execução depois de uma execução; ou a condição, os atrasos, os canais referenciados, o estado de habilitação ou o modo de armar foram editados. |

Uma sessão nova começa do zero: nenhuma condição, disponibilidade ou estado de antirrepique
atravessa um intervalo sem observação, então uma condição já verdadeira pode produzir outra
**Ativada** quando uma execução começa ou quando a aplicação volta, e não existe linha sintética de
"sessão iniciada" nesta linha do tempo. O arquivo da própria execução grava a fronteira da sessão
mesmo quando nenhuma transição a segue; Históricos e relatórios usam isso para classificar uma
ativação aberta mais antiga como Interrompida. Essa marca fica fora desta linha do tempo e não gera
notificação nenhuma. Edições só de exibição (nome, mensagem, severidade) preservam a sessão e mudam
apenas os snapshots posteriores.

## Busca e filtro {#search-and-filter}

| Controle | Valores | O que faz |
| --- | --- | --- |
| Busca | Texto de exemplo "Busque por nome, mensagem, modelo, unidade ou procedimento" | Casamento por "contém" no nome da ocorrência, na sua mensagem, no nome do modelo, no nome da unidade e no nome do procedimento, como foram fotografados na hora. |
| Severidade | **Todas as severidades** (padrão), **Crítica**, **Aviso**, **Informação** | Mantém apenas as transições de ocorrências que carregavam aquela severidade quando aconteceram. |
| Atualizar | | Relê o diário; dica "Atualizar ocorrências". |
| Exportar | **Exportar como CSV…**, **Exportar como JSON…** | Grava toda transição que a busca, a severidade e o período alcançam, página após página, e não só as linhas listadas no momento. Desenhado apenas com **Exportar/importar históricos**; fica cinza enquanto a lista está vazia. |

## As linhas {#the-rows}

| Parte da linha | Conteúdo |
| --- | --- |
| Hora | Data e hora em que o juiz observou a aresta (numa execução, o instante da própria amostra julgada). |
| Ponto | O tom da severidade: crítico para Crítica, cautela para Alerta, neutro para Informação. |
| Nome | O nome da ocorrência na hora. |
| Resumo | "Transição · observação N (Motivo) · Modelo / Unidade · contexto", onde N é a posição da aresta dentro da sua sessão e o contexto é "Execução · " seguido do nome do procedimento (ou apenas "Execução" quando nenhum nome de procedimento foi gravado) ou "Fora de execução". Exemplo: "Ativada · observação 1 (Execução iniciada) · Furnace / Linha 2 · Execução · Cozimento 180". |
| Nível | A palavra da severidade. |

A mensagem que uma linha carrega é a mensagem da própria ocorrência para **Ativada** e
**Encerrada** (vazia quando a definição não tem nenhuma, mostrada como "Nenhuma mensagem
capturada." no painel) e, para as arestas de disponibilidade, "Sinal indisponível:" ou "Sinal
restaurado:" seguido dos nomes dos canais afetados, separados por vírgulas.

## O painel de detalhes {#the-detail-panel}

Selecionar uma linha abre o painel com o distintivo da severidade e o nome, o instante completo, a
linha de resumo, a mensagem e quatro cartões:

| Cartão | Campo | Conteúdo |
| --- | --- | --- |
| EVENTO | Nível | A severidade. |
| EVENTO | ID do evento | A identidade desta aresta no diário. Numa observação de execução, é o mesmo id que o arquivo da execução guarda. |
| SNAPSHOT DA OCORRÊNCIA | Transição | Ativada, Normalizada, Indisponível ou Restaurada. |
| SNAPSHOT DA OCORRÊNCIA | Modelo | O nome do modelo na hora. |
| SNAPSHOT DA OCORRÊNCIA | Unidade | O nome da unidade na hora. |
| SNAPSHOT DA OCORRÊNCIA | Abrangência | Execução ou Fora de execução. |
| SNAPSHOT DA OCORRÊNCIA | Procedimento | Só no escopo Execução: o nome do procedimento, ou um traço quando nenhum foi gravado. |
| SNAPSHOT DA OCORRÊNCIA | ID da execução | Só no escopo Execução: o id da execução, o mesmo que Históricos mostra. |
| SNAPSHOT DA OCORRÊNCIA | ID do modelo, ID da unidade, ID da ocorrência | Os ids estáveis por trás dos nomes, que renomear não muda. |
| SESSÃO DE OBSERVAÇÃO | Sequência no diário | O número de inserção da linha no diário, que ordena linhas com o mesmo instante. |
| SESSÃO DE OBSERVAÇÃO | ID da observação | A identidade da sessão que observou a aresta; toda aresta de uma sessão a compartilha. |
| SESSÃO DE OBSERVAÇÃO | Sequência da transição | A ordem da aresta dentro da sessão, começando em um. Um salto significa uma aresta que o diário não conseguiu persistir. |
| SESSÃO DE OBSERVAÇÃO | Início | Quando a sessão começou, como instante completo. |
| SESSÃO DE OBSERVAÇÃO | Motivo | Execução iniciada, Execução retomada, Vigia iniciado, Observação fora de execução retomada ou Definição alterada. |
| CONFIGURAÇÃO CONGELADA | Condição | A condição JavaScript que a sessão de fato julgou. |
| CONFIGURAÇÃO CONGELADA | Atraso para ligar / desligar | "x ms / y ms", o antirrepique que a sessão usou. |
| CONFIGURAÇÃO CONGELADA | IDs dos canais referenciados | Os ids dos canais que condicionaram a condição, separados por ponto e vírgula. |

**Copiar o evento** copia uma linha: "instante | Ocorrência | severidade | nome | resumo |
mensagem | EventId=… | OccurrenceId=… | ObservationId=… | ObservationSequence=… |
ObservationStartedAt=… | ObservationReason=… | Condition=… | OnDelayMs=… | OffDelayMs=… |
ReferencedChannelIds=…".

## Colunas da exportação {#export-columns}

O CSV e o JSON carregam os mesmos campos, nesta ordem: `Timestamp` (o cabeçalho do CSV acrescenta a
referência de tempo, "Timestamp (UTC-03:00)"), `JournalSequence`, `Severity`, `Name`, `Transition`,
`Scope`, `Model`, `ModelId`, `Unit`, `UnitId`, `Procedure`, `RunId`, `Message`, `EventId`,
`OccurrenceId`, `ObservationId`, `ObservationSequence`, `ObservationStartedAt`,
`ObservationReason`, `Condition`, `OnDelayMs`, `OffDelayMs` e `ReferencedChannelIds` (separados por
ponto e vírgula no CSV, um vetor no JSON). O JSON é um envelope com `TimeZone` e `Events`. Os nomes
dos arquivos são `occurrence-history-<yyyyMMdd-HHmmss>.csv` e `.json`. O CSV segue a preferência de
separador decimal da estação como toda outra exportação: com decimais por ponto o separador de lista
é `,`, com decimais por vírgula ele é `;`. Uma célula que começa com `=`, `+`, `-` ou `@` recebe um
apóstrofo na frente para que a planilha a leia como texto.

## Onde mais uma ocorrência é gravada {#where-else-an-occurrence-is-recorded}

Uma observação de execução é escrita primeiro no arquivo da própria execução e depois copiada para
cá com o mesmo id de evento e o contexto da execução; se a cópia falhar, o arquivo da execução ainda
guarda a aresta e o Console carrega uma linha de Error dizendo isso. Uma observação fora de execução
existe apenas aqui. Toda aresta também deixa uma linha no Console sob a área Process: uma ativação
no nível da sua severidade (Crítica como erro, Alerta como alerta, Informação como informação), uma
perda de sinal nesse mesmo nível, uma normalização e uma restauração como informação. Uma ativação
ainda levanta uma notificação dentro da janela intitulada "Ocorrência · " seguida do nome da unidade
e, para uma ativação de Alerta ou Crítica observada durante uma execução, uma notificação do sistema
operacional enquanto a janela está escondida ou minimizada.

## Estados vazios e a linha de status {#empty-states-and-the-status-line}

- "Nenhuma ocorrência ainda" com "As transições de ocorrência das execuções e do
  monitoramento Sempre fora de execução vão aparecer aqui."
- "Nenhum registro de ocorrências combina com estes filtros" com "Ajuste o filtro de severidade ou os termos de busca para
  ampliar este histórico."
- A linha de status diz "N mostrados · página 1" e, em seguida, " · filtrado" quando uma busca, uma
  severidade ou um período está em vigor; à direita, "1 selecionada" e
  "Atualizado hh:mm:ss".

## O que a aba Ocorrências não faz {#what-the-occurrences-tab-does-not-do}

- Ela não define, arma nem edita uma ocorrência
  ([Process > Preparação > Ocorrências](process-occurrences)).
- Ela não emparelha arestas em episódios com duração: essa visão derivada, com as suas
  classificações Interrompida e Incompleta, está em [Históricos](histories) para uma execução e nos
  painéis da própria unidade.
- Ela não tem filtro por unidade, execução, escopo ou data; busque pelo nome da unidade, do modelo
  ou do procedimento, ou abra a execução em Históricos.
- Ela não mostra estado ao vivo: se uma ocorrência está ativa agora se lê no painel da unidade, não
  aqui.