Manutenção e Solução de Problemas de Cubos Federados

Modelar e Testar Cubos Federados

Ao projetar um cubo federado do Essbase, siga estas diretrizes de design e teste para obter uma abordagem em fases para solucionar problemas ou monitorar o desempenho.

Inicie o projeto de cubo federado em um ambiente de teste.
Comece com modelos de cubo ASO ou BSO do Essbase que tenham as seguintes características:
- não tem muitos níveis
- não tem muitos membros ou atributos compartilhados

Ao criar uma partição federada, programe as operações off-line quando as consultas não forem permitidas na instância.
Desconecte gradualmente as sessões de usuário ativas do Essbase, usando o aplicativo alter disable commands e/ou disable connects (para impedir qualquer nova atividade de usuário), seguido por alter system logout session e/ou kill request (se você precisar encerrar todas as sessões ativas que não precisam ser concluídas). Observe que o MaxL não pode encerrar as solicitações que podem estar sendo executadas no Autonomous AI Lakehouse. Se você desativar comandos no aplicativo, lembre-se de reativá-los após a criação da partição federada.

Para encerrar solicitações que estão sendo executadas como sessões SQL no Autonomous AI Lakehouse, são necessárias etapas adicionais. Consulte Cancelar SQL de Longa Execução em Cubos Federados.
Executar ajuste de timeout:
- Proxy HTTPS na rede do cliente - ajuste os timeouts da rede do cliente
- Balanceador de carga - aumente o timeout do LoadBalance para 1.260 segundos (21 minutos)
- Aumente os timeouts de HTTPD para 21 minutos
```
/etc/httpd/conf.d/00_base.conf:ProxyTimeout 1260
```
```
/etc/httpd/conf.d/00_base.conf:Timeout 1260
```
- Timeout de APS/JAPI:
  - Na página Console da interface web do Essbase, selecione Configuração e anote o valor de olap.server.netSocketTimeOut. Um valor de 200 ms significa que cada contagem de 5 para essas propriedades dá 1 segundo de tempo de espera.
  - Para definir o limite do tempo limite do APS/JAPI como 30 minutos, defina olap.server.netRetryCount como 9000.
Crie a partição federada.
Reverter os ajustes de timeout na etapa 3.
Ative os usuários de volta ao sistema usando alter application ativar comandos e/ou connects, se eles tiverem sido desativados anteriormente.
Para relatórios em um cubo federado, ajuste QRYGOVEXECTIME para ser maior que o tempo esperado para executar consultas em partições federadas. Observe que QRYGOVEXECTIME não pode encerrar as solicitações que podem estar sendo executadas no Autonomous AI Lakehouse.
Depois que o teste e o ajuste forem concluídos, use as etapas acima de 1 a 7 para implementar um ambiente para produção.

Observação:

Se você vir um erro "Falha ao salvar o outline" quando criar a partição federada, aguarde a conclusão das sessões e,, em seguida, atualize o browser. Se a partição federada tiver sido criada, valide-a no SQL Developer. Se ele for validado no SQL Developer, o cubo federado estará pronto para uso. Caso contrário, o modelo deverá ser corrigido e será necessário ajuste de timeout, conforme descrito acima na etapa 3.

Precauções de Metadados para Cubos Federados

Tome cuidado ao editar o outline de um cubo federado não gerenciado pelo Essbase. Se você adicionar ou renomear membros, certifique-se de que as alterações de metadados também sejam representadas na sua tabela de fatos no Autonomous AI Lakehouse.

Este tópico não se aplica a cubos federados com armazenamento de dados gerenciado do Essbase.

Se o outline do Essbase ficar fora de sincronia com a tabela de fato no Autonomous AI Lakehouse, o cubo federado se tornará inválido ou não funcionará corretamente. Para corrigi-la, elimine a partição federada, faça as alterações no outline e na tabela de fatos e, em seguida, recrie a partição federada.

Se um cubo federado se tornar inválido, você poderá encontrar um erro começando com Essbase Error(1040235): Remote warning from federated partition.

Os seguintes tipos de alterações de outline do Essbase farão com que um cubo federado (não gerenciado pelo Essbase) se torne inválido:

Adicionando, renomeando ou removendo dimensões
Adicionando, renomeando ou removendo membros armazenados na dimensão dinâmica
Alterando qualquer membro de armazenado para dinâmico

Para outros tipos de alterações no outline do Essbase não indicadas acima (por exemplo, adicionar ou renomear um membro de dimensão não dinâmica), faça a alteração correspondente na linha de dados afetada da tabela de fatos. Caso contrário, o cubo federado poderá não funcionar corretamente.

Se você souber por antecedência que os metadados do outline do Essbase serão alterados, o melhor será remover a partição federada primeiro, fazer as alterações no outline, atualizar a tabela de fatos e, em seguida, recriar a partição federada.

No entanto, se os metadados do Essbase forem alterados e tornarem a partição federada inválida, execute a seguinte ação:

Remova a partição federada e a conexão associada a ela (se de outra forma não utilizada), conforme descrito em Remover uma Partição Federada.

No esquema do usuário no Autonomous AI Lakehouse, exclua manualmente todas as tabelas geradas pelo Essbase e outros objetos que não foram removidos com a partição federada.
Certifique-se de que as alterações no outline sejam concluídas no cubo do Essbase.
Crie a tabela de fatos novamente. Consulte Criar a Tabela de Fatos.
Recrie a conexão com o Autonomous AI Lakehouse. Essa pode ser uma conexão global (abaixo do ícone Origens principal na interface Web do Essbase) ou pode estar nas Origens definidas apenas para o aplicativo. Siga as instruções em Criar uma Conexão para Cubos Federados.
Recrie a partição federada, conforme descrito em Criar uma Partição Federada.

Cancelar SQL de Longa Execução em Cubos Federados

Você pode cancelar sessões SQL que estão em execução nos cubos federados do Essbase. O cancelamento de SQL poderá ser necessário se um cálculo estiver demorando muito ou se o cubo federado precisar de backup ou recuperação.

Se cálculos, carregamentos de dados ou agregações do Essbase em execução em cubos federados gerarem instruções SQL de longa execução, será possível cancelar as sessões, mesmo que elas estejam em execução no Autonomous AI Lakehouse.

Para que o cancelamento da sessão SQL por meio do Essbase possa ser disponibilizado, um fluxo de trabalho breve de etapas deve ser concluído para ativar o SQL Session Governor no Essbase.

Os usuários com os seguintes tipos de acesso estão envolvidos nas etapas de preparação.

Tipo de Usuário	Atribuição no Workflow
Administrador de Banco de Dados	Sabe o nome e a senha do esquema do administrador do Autonomous AI Lakehouse. Pode criar procedimentos PL/SQL armazenados no Autonomous AI Lakehouse e conceder privilégios a outros usuários.
Usuário do Banco de Dados Também conhecido como usuário da partição federada	Sabe o nome e senha do esquema do Autonomous AI Lakehouse -- o mesmo esquema e senha usados para criar a conexão do Essbase ao Oracle Database (um pré-requisito obrigatório antes de criar a partição federada).
Gerente de Aplicativos do Essbase	O gerente/proprietário de um aplicativo Essbase usado para um cubo federado.

O seguinte workflow de etapas deve ser concluído para ativar o SQL Session Governor:

Administrador de BD: Crie os seguintes procedimentos armazenados PL/SQL no Autonomous AI Lakehouse e conceda o privilégio EXECUTE ao Usuário de BD:

Observação:

Os procedimentos armazenados devem ser criados no esquema do usuário do Banco de Dados.

ESS_SESSION_SET_MODULE (jagent_id em VARCHAR2,app_name em VARCHAR2, db_name em VARCHAR2, req_id em VARCHAR2)

Use a seguinte instrução para criar o procedure:

CREATE OR REPLACE NONEDITIONABLE PROCEDURE "ESS_SESSION_SET_MODULE" (jagent_id in VARCHAR2, app_name in VARCHAR2, db_name in VARCHAR2, req_id in VARCHAR2) AS
    ess_jagentid VARCHAR2(256);
    ess_appname VARCHAR2(256);
    ess_dbname VARCHAR2(256);
    ess_reqid VARCHAR2(256);
    hash_str VARCHAR2(100);
BEGIN
    IF jagent_id is not NULL AND app_name is not NULL AND db_name is not NULL AND req_id is not NULL THEN
        -- add prefixes to identify essbase sessions
        ess_jagentid := CONCAT('ess_jagentid_', jagent_id);
        ess_appname := CONCAT('ess_appname_', app_name);
        ess_dbname := CONCAT('ess_dbname_', db_name);
        ess_reqid := CONCAT('ess_reqid_', req_id);

        -- ess_jagentid is stored in client_info
        dbms_application_info.set_client_info(ess_jagentid);

        -- create hash out of CONCAT(ess_jagentid, ess_appname, ess_dbname)
        -- the hash identifies the fed partition
        -- store the hash as the module
        -- store the ess_reqid as the action
        SELECT TO_CHAR(ORA_HASH(CONCAT(CONCAT(ess_jagentid, ess_appname), ess_dbname))) INTO hash_str from dual;
        dbms_application_info.set_module(module_name => hash_str, action_name => ess_reqid);
        
    ELSIF jagent_id is NULL AND app_name is NULL AND db_name is NULL AND req_id is NULL THEN
        -- reset session
        dbms_application_info.set_module(null,null);
        dbms_application_info.set_client_info(null);
    END IF;
END ESS_SESSION_SET_MODULE;

ESS_SESSION_CANCEL (jagent_id em VARCHAR2, app_name em VARCHAR2, db_name em VARCHAR2, req_id em VARCHAR2)

Use a seguinte instrução para criar o procedure:

CREATE OR REPLACE NONEDITIONABLE PROCEDURE "ESS_SESSION_CANCEL" (jagent_id in VARCHAR2, app_name in VARCHAR2, db_name in VARCHAR2, req_id in VARCHAR2) AS
    ess_jagentid VARCHAR2(256);
    ess_appname VARCHAR2(256);
    ess_dbname VARCHAR2(256);
    ess_reqid VARCHAR2(256);
    uname VARCHAR2(100);
    hash_str VARCHAR2(100);
    sessionid VARCHAR2(100);
    killcmd VARCHAR2(1000);
    XCP_MARKED_FOR_TERMINATION exception;
    pragma exception_init (XCP_MARKED_FOR_TERMINATION, -00031);
BEGIN
    -- add prefixes to identify Essbase sessions
    ess_jagentid := CONCAT('ess_jagentid_', jagent_id);
    ess_appname := CONCAT('ess_appname_', app_name);
    ess_dbname := CONCAT('ess_dbname_', db_name);
    ess_reqid := CONCAT('ess_reqid_', req_id);

    -- create hash out of CONCAT(ess_jagentid, ess_appname, ess_dbname)
    -- the hash identifies the federated partition
    SELECT TO_CHAR(ORA_HASH(CONCAT(CONCAT(ess_jagentid, ess_appname), ess_dbname))) INTO hash_str from dual;
    uname := SYS_CONTEXT('USERENV', 'SESSION_USER');

    IF jagent_id is not NULL AND app_name is not NULL AND db_name is not NULL AND req_id is not NULL THEN
        -- valid jagent_id, app_name, db_name, req_id
        -- kill sessions associated with the given federated cube and request id
        FOR r IN (select sid,serial# from v$session where username=uname AND module=hash_str AND action=ess_reqid)
        LOOP
            BEGIN
                sessionid := DBMS_ASSERT.ENQUOTE_LITERAL(r.sid || ',' || r.serial#);
                killcmd:='ALTER SYSTEM KILL SESSION ' || sessionid || ' IMMEDIATE';
                EXECUTE IMMEDIATE killcmd;
            EXCEPTION
                WHEN XCP_MARKED_FOR_TERMINATION THEN
                    -- ignore - the session could not be terminated immediately, but is marked for termination.
                    NULL;
            END;
        END LOOP;
    ELSIF jagent_id is not NULL AND app_name is not NULL AND db_name is not NULL AND req_id is NULL THEN
        -- null req_id
        -- kill all sessions for the given federated cube - invoked at app startup
        FOR r IN (select sid,serial# from v$session where username=uname AND module=hash_str)
        LOOP
            BEGIN
                sessionid := DBMS_ASSERT.ENQUOTE_LITERAL(r.sid || ',' || r.serial#);
                killcmd:='ALTER SYSTEM KILL SESSION ' || sessionid || ' IMMEDIATE';
                EXECUTE IMMEDIATE killcmd;
            EXCEPTION
                WHEN XCP_MARKED_FOR_TERMINATION THEN
                    -- ignore - the session could not be terminated immediately, but is marked for termination.
                    NULL;
            END;
        END LOOP;
    END IF;

    EXCEPTION
        WHEN OTHERS THEN
            RAISE;
END ESS_SESSION_CANCEL;

Conceda privilégios EXECUTE para os procedimentos armazenados acima ao Usuário de BD.

GRANT EXECUTE on ESS_SESSION_SET_MODULE TO "DB User";
GRANT EXECUTE on ESS_SESSION_CANCEL TO "DB User";
CREATE OR REPLACE SYNONYM "DB User".ESS_SESSION_SET_MODULE FOR ESS_SESSION_SET_MODULE;
CREATE OR REPLACE SYNONYM "DB User".ESS_SESSION_CANCEL FOR ESS_SESSION_CANCEL;

Usuário de BD: Em seu esquema do Autonomous AI Lakehouse, confirme se você tem acesso aos seguintes procedimentos armazenados em Sinônimos:
- MÓDULO ESS_SESSION_SET_
- CANCELAMENTO_DA_SESSÃO
Com esses pré-requisitos atendidos, as solicitações SQL de longa execução no cubo federado podem ser canceladas da mesma forma que outras solicitações do Essbase podem. As solicitações podem ser canceladas na interface Web do Essbase na área Sessões da Console. Se você estiver usando o MaxL, poderá cancelar solicitações usando a instrução alter system kill request. Revise Modelar e Testar Cubos de Partição Federados para obter diretrizes sobre encerramento de sessão.

O Que Fazer Se os Detalhes da Conexão do Banco de Dados Forem Alterados

Se os detalhes da conexão do Autonomous AI Lakehouse que o Essbase usa para um cubo federado tiverem sido alterados, você precisará eliminar e recriar a partição federada e limpar objetos e tabelas de metadados associados do esquema do banco de dados.

Este tópico não se aplica a cubos federados com armazenamento de dados gerenciado do Essbase.

Será necessário eliminar e recriar a partição federada se algum dos seguintes eventos ocorrer após sua criação:

As alterações na porta do Autonomous AI Lakehouse
O Nome da conexão é alterado
A conexão usa uma wallet e você alterna de um nome para outro (para fazer alterações no desempenho ou na simultaneidade)
Uma atualização de outline altera o mapeamento de membros para a tabela de fatos, fazendo com que a partição federada fique fora de sincronização. Consulte Precauções de Metadados para Cubos Federados para obter detalhes.

Se você souber com antecedência que os detalhes de conexão vão mudar, o melhor será remover a partição federada antes da alteração e criá-la novamente depois. No entanto, se a conexão for alterada e o cubo federado se tornar inválido, execute as etapas a seguir.

Eliminar a Partição Federada

Remova a partição federada e a conexão associada a ela (se não forem utilizadas), conforme descrito em Remover uma Partição Federada.

Remover Objetos Relacionados à Partição Federada e Tabelas de Metadados

No esquema do usuário no Autonomous AI Lakehouse, elimine todas as tabelas geradas pelo Essbase e outros objetos que não foram removidos com a partição federada.

ssh para o host do Servidor do Essbase como o usuário opc.
```
ssh -i MPOCI_KEY.pem opc@100.xxx.xxx.xxx
```
Altere para o usuário oracle (e vá para o respectivo diretório home).
```
sudo su - oracle
```
Navegue até o diretório de aplicativos.
```
cd /u01/data/essbase/app
```
Usando o aplicativo Essbase e o nome do cubo, identifique o prefixo exclusivo associado aos seus objetos e metadados da partição federada.
1. Obtenha o nome do aplicativo (AppName). O nome faz distinção entre maiúsculas e minúsculas; portanto, capture o tipo de letra exato. Neste exemplo, AppName = Amostra.
```
ls
Sample
```
2. Navegue até o diretório do cubo e obtenha o nome do cubo (DbName). O nome faz distinção entre maiúsculas e minúsculas; portanto, capture o tipo de letra exato. Neste exemplo, DbName = Básico.
```
cd /Sample
ls
Basic
```
3. Usando o SQL Developer ou outra ferramenta, conecte-se ao Autonomous AI Database como o usuário do esquema ao qual o cubo federado está (ou foi) conectado.
4. No SQL Developer, execute uma instrução SELECT para obter o valor de OTL_ID e OTL_STATUS.
  
  O formato da instrução SELECT é:
```
SELECT OTL_ID, OTL_STATUS, TRC_HOST FROM ESSAV_OTL_MTD_VERSION where APPNAME ='<AppName>';
```
  Exemplo
  
  Substitua Sample pelo seu AppName.
```
SELECT OTL_ID, OTL_STATUS, TRC_HOST FROM ESSAV_OTL_MTD_VERSION WHERE APPNAME='Sample';
```
  A consulta acima deve retornar o valor OTL_ID; por exemplo,
```
987
```
  Observação:
  Se forem retornadas linhas em que OTL_STATUS seja ACTIVE, você deverá tentar eliminar o aplicativo da instância TRC_HOST antes de prosseguir para a próxima etapa.
5. Crie a Prefix como:
```
ESSAV_<OTL_ID>_
```
  Exemplo:
```
<Prefix> = ESSAV_987_
```
Execute uma instrução SELECT para criar uma lista de objetos associados ao seu cubo federado. Esses são objetos que você vai remover na próxima etapa.

O formato da instrução SELECT é:
```
SELECT * FROM user_OBJECTS WHERE OBJECT_NAME LIKE '<Prefix>%' ESCAPE '\';
```
Exemplo:
```
SELECT * FROM user_OBJECTS WHERE OBJECT_NAME LIKE 'ESSAV_987_%' ESCAPE '\';
```

Execute um procedimento PL/SQL armazenado que elimine todas as views analíticas, pacotes, hierarquias, tabelas e outros objetos associados ao Prefix.

Exemplo

Substitua ESSAV_987_ pelo seu Prefix.

SET SERVEROUTPUT ON;

declare
  prefix_str varchar2(70) := 'ESSAV_987_';

BEGIN

  FOR c IN ( SELECT ANALYTIC_VIEW_NAME FROM user_analytic_views WHERE ANALYTIC_VIEW_NAME like prefix_str || '%' )
  LOOP
    EXECUTE IMMEDIATE 'DROP ANALYTIC VIEW "' || c.ANALYTIC_VIEW_NAME || '" ';
    DBMS_OUTPUT.PUT_LINE('ANALYTIC VIEW ' || c.ANALYTIC_VIEW_NAME || ' dropped successfully.');
  END LOOP;

  FOR c IN ( SELECT distinct OBJECT_NAME FROM USER_PROCEDURES WHERE OBJECT_TYPE='PACKAGE' and OBJECT_NAME like prefix_str || '%' )
  LOOP
    EXECUTE IMMEDIATE 'DROP PACKAGE "' || c.OBJECT_NAME || '" ';
    DBMS_OUTPUT.PUT_LINE('PACKAGE ' || c.OBJECT_NAME || ' dropped successfully.');
  END LOOP;

  FOR c IN ( SELECT distinct HIER_NAME FROM USER_HIERARCHIES WHERE HIER_NAME like prefix_str || '%' )
  LOOP
    EXECUTE IMMEDIATE 'DROP HIERARCHY "' || c.HIER_NAME || '" ';
    DBMS_OUTPUT.PUT_LINE('HIERARCHY ' || c.HIER_NAME || ' dropped successfully.');
  END LOOP;

  FOR c IN ( SELECT distinct DIMENSION_NAME FROM USER_ATTRIBUTE_DIM_TABLES_AE WHERE DIMENSION_NAME like prefix_str || '%' )
  LOOP
    EXECUTE IMMEDIATE 'DROP ATTRIBUTE DIMENSION "' || c.DIMENSION_NAME || '" ';
    DBMS_OUTPUT.PUT_LINE('ATTRIBUTE DIMENSION ' || c.DIMENSION_NAME || ' dropped successfully.');
  END LOOP;

  FOR c IN ( SELECT distinct VIEW_NAME FROM USER_VIEWS WHERE VIEW_NAME like prefix_str || '%' )
  LOOP
    EXECUTE IMMEDIATE 'DROP VIEW "' || c.VIEW_NAME || '" ';
    DBMS_OUTPUT.PUT_LINE('VIEW ' || c.VIEW_NAME || ' dropped successfully.');
  END LOOP;

  FOR c IN ( SELECT distinct TABLE_NAME FROM USER_TABLES WHERE TABLE_NAME like prefix_str || '%' )
  LOOP
    EXECUTE IMMEDIATE 'DROP TABLE "' || c.TABLE_NAME || '" purge';
    DBMS_OUTPUT.PUT_LINE('TABLE ' || c.TABLE_NAME || ' dropped successfully.');
  END LOOP;

  FOR c IN ( SELECT distinct TYPE_NAME FROM USER_TYPES WHERE TYPE_NAME like prefix_str || '%' )
  LOOP
    EXECUTE IMMEDIATE 'DROP TYPE "' || c.TYPE_NAME || '" FORCE';
    DBMS_OUTPUT.PUT_LINE('TYPE ' || c.TYPE_NAME || ' dropped successfully.');
  END LOOP;

END;
/

Elimine e atualize tabelas associadas relativas a metadados.

Execute um procedimento PL/SQL armazenado para eliminar tabelas relacionadas a metadados associadas ao OTL_ID.

Exemplo

Substitua 987 pelo seu OTL_ID.

SET SERVEROUTPUT ON;
BEGIN
  FOR c IN ( SELECT distinct TABLE_NAME FROM USER_TABLES WHERE TABLE_NAME like 'ESSAV_MTD_987_%' )
  LOOP
    EXECUTE IMMEDIATE 'DROP TABLE "' || c.TABLE_NAME || '" purge';
    DBMS_OUTPUT.PUT_LINE('TABLE ' || c.TABLE_NAME || ' dropped successfully.');
  END LOOP;
END;
/

Execute uma instrução UPDATE para definir a tabela ESSAV_OTL_MTD_VERSION para o status inativo.

Exemplo

Substitua Sample pelo seu AppName.
```
UPDATE "ESSAV_OTL_MTD_VERSION" SET  "OTL_STATUS" = 'INACTIVE'  where APPNAME ='Sample';
commit;
```

Observação:

Como apenas uma instância do Essbase deve usar o esquema do Autonomous AI Database, você não precisa especificar o ESSBASE_INSTANCE_UNIQUE_ID quando estiver executando as tarefas de limpeza. Consulte Restrições para Cubos Federados.

Recrie a Conexão e a Partição Federada

Recrie a conexão com o Autonomous AI Lakehouse. Essa pode ser uma conexão global (abaixo do ícone Origens principal na interface Web do Essbase) ou pode estar nas Origens definidas apenas para o aplicativo. Siga as instruções na conexão. Certifique-se de Testar e Salvar a conexão.
Recrie a partição federada, conforme descrito em Criar uma Partição Federada.
Se você continuar a ver um erro de conexão, como Essbase Error(1350012): Attempt to connect to OCI failed, verifique https://support.oracle.com/rs?type=doc&id=2925030.1.

Fazer Backup e Restaurar um Cubo Federado

As partições federadas não são migradas com os aplicativos do Essbase. Ao se preparar para mover seu cubo federado para outro servidor ou para migrar para outra versão do Essbase, exclua a partição federada e recrie-a no novo ambiente.

Para fazer backup do seu cubo federado,

Faça backup do aplicativo, sem os dados, mas incluindo tudo o mais de que você possa precisar (como propriedades de configuração, filtros, variáveis, scripts de cálculo e outros artefatos). Para isso, use LcmExport (ou o job Exportar LCM na interface Web do Essbase).
Faça backup da tabela de fatos. Consulte Fazendo Backup e Restaurando Autonomous Database.
Exclua a definição de partição federada do cubo, seguindo as etapas em Remover uma Partição Federada.

Para restaurar seu cubo federado de backup,

Recrie o aplicativo usando o LcmImport (ou o job Importar LCM na interface Web do Essbase).
Se necessário, restaure a tabela de fatos no Autonomous AI Lakehouse.
Recrie a conexão com o Autonomous AI Lakehouse. Recomenda-se usar um novo nome de conexão para evitar encontrar erros.
Recriar a partição federada.

Manutenção e Resolução de Problemas do Cubo Federado

Modelar e Testar Cubos Federados

Precauções de Metadados para Cubos Federados

Cancelar SQL de Longa Execução em Cubos Federados

O Que Fazer Se os Detalhes da Conexão do Banco de Dados Forem Alterados

Fazer Backup e Restaurar um Cubo Federado