ampmInsights/docs/09-operacao-observabilidade.html

<!DOCTYPE html>
<html lang="pt-BR">
<head>
<meta charset="UTF-8">
<meta name="viewport" content="width=device-width, initial-scale=1">
<title>ampmInsights &middot; Operação & observabilidade</title>
<meta name="description" content="Como monitorar consumo e depurar erros de IA/Generative AI no ambiente ampmInsights.">
<link rel="stylesheet" href="assets/main.css">
</head>
<body>
<div class="layout">
  <aside class="sidebar">
    <div class="brand">
      <span class="oracle">ORACLE</span>
      <span class="name">ampmInsights</span>
    </div>
    <button class="menu-toggle" type="button">Menu &#9776;</button>
    <div class="kicker">Documentação V1 &middot; AM/PM</div>
    <ul class="nav-list">
      <li><a class="" href="index.html"><span class="step-no">1</span>Visão geral</a></li>
<li><a class="" href="02-arquitetura.html"><span class="step-no">2</span>Arquitetura</a></li>
<li><a class="" href="03-pre-requisitos-credenciais.html"><span class="step-no">3</span>Pré-requisitos & credenciais</a></li>
<li><a class="" href="04-passo-a-passo-banco.html"><span class="step-no">4</span>Passo a passo: banco de dados</a></li>
<li><a class="" href="05-passo-a-passo-apex.html"><span class="step-no">5</span>Passo a passo: aplicação APEX</a></li>
<li><a class="" href="06-validacao-testes.html"><span class="step-no">6</span>Validação & testes</a></li>
<li><a class="" href="07-seguranca-boas-praticas.html"><span class="step-no">7</span>Segurança & boas práticas</a></li>
<li><a class="" href="08-glossario-roadmap.html"><span class="step-no">8</span>Glossário & roadmap</a></li>
<li><a class="active" href="09-operacao-observabilidade.html"><span class="step-no">9</span>Operação & observabilidade</a></li>
    </ul>
    <div class="sidebar-footer">
      Vulnerability &amp; Audit AI Insights<br>
      Oracle AI Database 26ai &middot; AI Vector Search<br>
      Versão V1 &middot; ambiente reprodutível do cliente
    </div>
  </aside>
  <main class="content">
    <p class="page-kicker">Operação</p>
    <h1>Operação & observabilidade</h1>
    <p class="lede">Checklist de erros comuns, consultas prontas para troubleshooting e consumo de IA, e onde acompanhar custo/saúde do ambiente sem precisar de nenhuma ferramenta extra.</p>

<p>O ambiente registra, em <code>TB_26AI_TECH_LOG</code>, cada chamada feita ao Generative AI e aos
embeddings — sucesso ou erro — para que a operação do dia a dia não dependa de abrir um chamado
toda vez que algo não funcionar de primeira. Use as consultas desta página para diagnosticar
rapidamente qualquer problema, e o checklist abaixo para os casos mais comuns.</p>

<h2>Checklist de erros comuns</h2>
<div class="table-wrap">
<table>
<tr><th>Sintoma</th><th>Causa provável</th><th>Como confirmar/corrigir</th></tr>
<tr><td><code>ORA-00942</code> em qualquer objeto <code>TB_26AI_TECH_*</code></td><td>Conectado como <code>ADMIN</code> em vez de <code>AMPMINSIGHTS</code>.</td><td>Rode <code>SELECT USER FROM DUAL;</code> — tem que voltar <code>AMPMINSIGHTS</code>. Reconecte e repita a seção que falhou.</td></tr>
<tr><td>"AI Insight"/chat sempre retorna um texto genérico de indisponibilidade</td><td>Credencial <code>OCI_CRED</code> ausente ou quebrada.</td><td><code>SELECT credential_name FROM user_credentials WHERE credential_name = 'OCI_CRED';</code> — se não retornar linha, refaça a Seção 3 conectado como <code>AMPMINSIGHTS</code>. Depois, confira o motivo exato na consulta de "Erros recentes" abaixo.</td></tr>
<tr><td>Erro de rede/timeout ao chamar o Generative AI</td><td>ACL de rede (Seção 1.6) não cobre o host correto.</td><td><code>SELECT host, privilege FROM dba_host_aces WHERE principal = 'AMPMINSIGHTS';</code> — deve listar <code>inference.generativeai.us-chicago-1.oci.oraclecloud.com</code> com <code>RESOLVE</code> e <code>CONNECT</code>.</td></tr>
<tr><td><code>ORA-20404</code> ("Object not found", domínio <code>oci.my$cloud_domain</code>)</td><td>Perfil de SELECT AI usando a região "de casa" do tenancy em vez da região do Generative AI.</td><td>A região do Generative AI já vem fixa (<code>us-chicago-1</code>) na Seção 5.3 do <a href="04-passo-a-passo-banco.html">Passo a passo: banco de dados</a> — não troque pelo valor de <code>OCI_REGION</code>.</td></tr>
</table>
</div>

<h2>O que <code>TB_26AI_TECH_LOG</code> guarda</h2>
<p>Toda chamada a Generative AI/embeddings feita pelas funções internas do ampmInsights grava uma
linha nesta tabela — sucesso ou erro, sem exceção. Guarda metadados de uso (função de origem,
provider, modelo, duração, tamanho do prompt/resposta em caracteres, usuário, e o
<code>SQLCODE</code>/<code>SQLERRM</code> quando há erro) — <strong>deliberadamente não guarda o
prompt ou a resposta completos</strong>, só o tamanho, por privacidade e para não inchar a tabela.</p>

<h2>Consultas prontas</h2>
<div class="code-block">
  <div class="code-bar">
    <span class="code-label">Erros recentes (últimas 24h)</span>
    <button class="copy-btn" type="button">Copiar</button>
  </div>
  <pre><code class="lang-sql">SELECT log_ts, calling_object, operation, provider, model_name,
       error_code, error_message
FROM   TB_26AI_TECH_LOG
WHERE  status = 'ERROR'
AND    log_ts >= SYSTIMESTAMP - INTERVAL '24' HOUR
ORDER  BY log_ts DESC;</code></pre>
</div>
<div class="code-block">
  <div class="code-bar">
    <span class="code-label">Taxa de erro por dia e por função/modelo</span>
    <button class="copy-btn" type="button">Copiar</button>
  </div>
  <pre><code class="lang-sql">SELECT TRUNC(log_ts) AS dia, calling_object, model_name,
       COUNT(*) AS total,
       SUM(CASE WHEN status = 'ERROR' THEN 1 ELSE 0 END) AS erros,
       ROUND(100 * SUM(CASE WHEN status = 'ERROR' THEN 1 ELSE 0 END) / COUNT(*), 1) AS pct_erro
FROM   TB_26AI_TECH_LOG
GROUP  BY TRUNC(log_ts), calling_object, model_name
ORDER  BY dia DESC, pct_erro DESC;</code></pre>
</div>
<div class="code-block">
  <div class="code-bar">
    <span class="code-label">Chamadas mais lentas</span>
    <button class="copy-btn" type="button">Copiar</button>
  </div>
  <pre><code class="lang-sql">SELECT log_ts, calling_object, operation, model_name, duration_ms, status
FROM   TB_26AI_TECH_LOG
WHERE  duration_ms IS NOT NULL
ORDER  BY duration_ms DESC
FETCH FIRST 20 ROWS ONLY;</code></pre>
</div>
<div class="code-block">
  <div class="code-bar">
    <span class="code-label">Qual registro de negócio está falhando</span>
    <button class="copy-btn" type="button">Copiar</button>
  </div>
  <pre><code class="lang-sql">SELECT l.log_ts, l.source_type, l.source_id, l.error_message,
       v.asset_name, v.definition_name
FROM   TB_26AI_TECH_LOG l
LEFT JOIN TB_26AI_TECH_v2 v ON v.rowid = CHARTOROWID(l.source_id)
WHERE  l.status = 'ERROR'
AND    l.source_id IS NOT NULL
ORDER  BY l.log_ts DESC;</code></pre>
</div>
<div class="code-block">
  <div class="code-bar">
    <span class="code-label">Purga do log (usa AI_LOG_RETENTION_DAYS)</span>
    <button class="copy-btn" type="button">Copiar</button>
  </div>
  <pre><code class="lang-sql">DECLARE
  v_days TB_26AI_TECH_PARAMS.PARAM_VALUE%TYPE;
BEGIN
  SELECT param_value INTO v_days FROM TB_26AI_TECH_PARAMS WHERE param_name = 'AI_LOG_RETENTION_DAYS';
  DELETE FROM TB_26AI_TECH_LOG WHERE log_ts < SYSTIMESTAMP - NUMTODSINTERVAL(v_days, 'DAY');
  COMMIT;
END;
/</code></pre>
</div>

<h2>Ferramentas nativas — sem código novo</h2>
<div class="grid">
  <div class="card"><h4>ADB Performance Hub</h4><p>Saúde do banco (CPU, I/O, sessões, SQL Monitor) direto no Console OCI, sem instrumentação extra.</p></div>
  <div class="card"><h4>OCI Cost Analysis</h4><p>Custo real do Generative AI, filtrado por serviço/compartimento — complementa o <code>TB_26AI_TECH_LOG</code> (que dá contagem/latência, não valor faturado).</p></div>
  <div class="card"><h4>Activity Reports (páginas 10020-10026)</h4><p>Atividade de usuário/sessão e erros não tratados do APEX, já vêm prontas na aplicação (<code>apex_activity_log</code>).</p></div>
</div>

<div class="callout info">
  <div class="callout-title">Job de geração em lote (JOB_26AI_TECH_VULNERABILIDADE)</div>
  <p>O botão "Gerar Insights em Lote" cria um job que roda a cada 20 segundos processando os
  registros pendentes. Ele mesmo verifica, a cada execução, se ainda há registros com
  <code>insight_report</code> nulo e se auto-remove
  (<code>DBMS_SCHEDULER.stop_job</code>/<code>drop_job</code>) quando não sobra nada para processar
  — não é necessário clicar em "parar" manualmente ao final de um lote. Para confirmar, rode
  <code>SELECT job_name, state FROM dba_scheduler_jobs WHERE job_name = 'JOB_26AI_TECH_VULNERABILIDADE';</code>
  — não deve retornar linha depois que o processamento terminar.</p>
</div>

    <div class="pillnav"><a class="prev" href="08-glossario-roadmap.html">&larr; Glossário & roadmap</a></div>
  </main>
</div>
<script src="assets/main.js"></script>
</body>
</html>