Baseline v1.0.0 do pacote cliente ampmInsights
Estado na virada para versionamento: Secoes 1-5 do setup de banco validadas ponta a ponta (ONNX CLIP corrigido - ORA-54426; regiao do Generative AI corrigida na Secao 5.3 - ORA-20404), observabilidade de IA adicionada (TB_26AI_TECH_LOG + PRC_26AI_TECH_LOG instrumentando FNC_26ai_rag/fnc_26ai_tech_rag/fnc_26ai_embed/PRC_26AI_TECH), bug de vazamento de sqlerrm em insight_report corrigido, job de geracao em lote agora se autoencerra, e nova doc 09-operacao-observabilidade.html com checklist de erros comuns e consultas de troubleshooting. Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
This commit is contained in:
152
docs/09-operacao-observabilidade.html
Normal file
152
docs/09-operacao-observabilidade.html
Normal file
@@ -0,0 +1,152 @@
|
||||
<!DOCTYPE html>
|
||||
<html lang="pt-BR">
|
||||
<head>
|
||||
<meta charset="UTF-8">
|
||||
<meta name="viewport" content="width=device-width, initial-scale=1">
|
||||
<title>ampmInsights · 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 ☰</button>
|
||||
<div class="kicker">Documentação V1 · 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 & Audit AI Insights<br>
|
||||
Oracle AI Database 26ai · AI Vector Search<br>
|
||||
Versão V1 · 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">← Glossário & roadmap</a></div>
|
||||
</main>
|
||||
</div>
|
||||
<script src="assets/main.js"></script>
|
||||
</body>
|
||||
</html>
|
||||
Reference in New Issue
Block a user