Operação

Operação & observabilidade

Checklist de erros comuns, consultas prontas de troubleshooting/consumo de IA, e onde olhar ferramentas nativas que já vêm sem custo de desenvolvimento.

Esta seção nasceu de um incidente real: o recurso "AI Insight" ficava sempre retornando o texto genérico de fallback, e não havia nenhum log que revelasse o motivo. Investigando, encontramos duas causas encadeadas — a Seção 3 (credencial OCI_CRED) tinha sido rodada conectado como ADMIN em vez de AMPMINSIGHTS (por isso a credencial nunca existiu), e a função que chama o LLM engolia qualquer erro silenciosamente, sem logar nada. As duas coisas foram corrigidas: a função agora loga cada chamada (sucesso ou erro) em TB_26AI_TECH_LOG, e esta página documenta como usar esse log — junto com um checklist dos erros mais comuns — para nunca mais operar "às cegas".

Checklist de erros comuns

O que TB_26AI_TECH_LOG guarda

Toda chamada a Generative AI/embeddings feita pelas funções FNC_26ai_rag, fnc_26ai_tech_rag, fnc_26ai_embed e PRC_26AI_TECH grava uma linha nesta tabela — sucesso ou erro, sem exceção. Guarda metadados de uso (objeto/função de origem, provider, modelo, duração, tamanho do prompt/resposta em caracteres, usuário, e o SQLCODE/SQLERRM completo quando há erro) — deliberadamente não guarda o prompt ou a resposta completos, só o tamanho, por privacidade e para não inchar a tabela.

Consultas prontas

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;

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;

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;

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;

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;
/

Application Settings do APEX — uma segunda fonte de configuração

A funcionalidade "AI Insight" (lupa na lista de vulnerabilidades) não lê EMBEDDING_COMPARTMENT direto de TB_26AI_TECH_PARAMS — o processo da página 81 chama apex_app_setting.get_value('OCI_CREDENTIAL') e apex_app_setting.get_value('COMPARTMENT_ID'), valores configurados dentro do próprio APEX (App Builder → Shared Components → Application Settings), totalmente separados da tabela de configuração do banco. Descobrimos isso em 2026-07-24 depois de corrigir tudo no banco e a lupa continuar falhando — os dois lugares tinham valores diferentes.

Não há uma view SQL simples e confiável pra conferir isso via Database Actions (evite adivinhar o nome — já tentamos apex_application_settings com colunas erradas e perdemos tempo); confira direto no App Builder: abra a aplicação → Shared Components → Application Settings, e compare os três valores acima com a TB_26AI_TECH_PARAMS atual. Sempre que corrigir EMBEDDING_COMPARTMENT ou GENAI_REGION no banco, atualize também aqui — são dois lugares de armazenamento independentes, corrigir um não corrige o outro.

Ferramentas nativas — sem código novo