Documentação Técnica — Quarkus IRIS Monitor System

1. Objetivo e Escopo

Este módulo permite a integração entre aplicações Java baseadas em Quarkus e as capacidades nativas de monitoramento de performance do InterSystems IRIS.
Ele possibilita que o desenvolvedor anote métodos com @PerfmonReport, acionando automaticamente as rotinas ^PERFMON do IRIS durante a execução do método e gerando relatórios de performance sem intervenção manual.

2. Componentes do Sistema

2.1 Anotação: @PerfmonReport

• Definida como InterceptorBinding do CDI.
• Pode ser aplicada a métodos ou classes.
• Instrui o framework a envolver a execução do método com a lógica de monitoramento do IRIS.

2.2 Interceptor: PerfmonReportInterceptor

• Intercepta chamadas a métodos anotados.

• Fluxo de execução:

  1. Registrar evento de início (LOG.infof("INIT: …"))
  2. Chamar monitorSystem.startPerfmon()
  3. Prosseguir com context.proceed()
  4. No bloco finally:
     • Chamar monitorSystem.generateReportPerfmon(...)
     • Chamar monitorSystem.stopPerfmon()
     • Registrar evento de fim com tempo de execução

• Garante que o monitoramento sempre será encerrado, mesmo se ocorrer uma exceção.

2.3 Bean DAO: MonitorSystem

• Bean CDI anotado com @ApplicationScoped.

• Mantém uma única instância de IRIS inicializada na inicialização.

• Configuração injetada via @ConfigProperty (URL JDBC, usuário, senha).

• Utiliza DriverManager.getConnection(...) para obter uma IRISConnection nativa.

• Contém os métodos:

  • startPerfmon()
  • generateReportPerfmon(String reportName)
  • stopPerfmon()

• Cada método chama as correspondentes rotinas ObjectScript em iris.src.dc.AdapterPerfmonProc via iris.classMethodVoid(...).

2.4 Adapter ObjectScript: iris.src.dc.AdapterPerfmonProc

• Define as rotinas que encapsulam a lógica do ^PERFMON:

    Class iris.src.dc.AdapterPerfmonProc Extends %RegisteredObject
    {
        ClassMethod start() As %Status
        {
            Set namespace = $NAMESPACE
            zn "%SYS"
            set status = $$Stop^PERFMON()
            set status = $$Start^PERFMON()
            zn namespace
            return status
        }
  
        ClassMethod generateReport(nameReport As %String = "report.txt") As %Status
        {
            Set namespace = $NAMESPACE
            zn "%SYS"
            Set tempDirectory = ##class(%SYS.System).TempDirectory()
            set status = $$Report^PERFMON("R","R","P", tempDirectory_"/"_nameReport)
            zn namespace
  
            return status
        }
  
        ClassMethod stop() As %Status
        {
            Set namespace = $NAMESPACE
            zn "%SYS"
            Set status = $$Stop^PERFMON()
            zn namespace
  
            return status
        }
    }
  

  Opera no namespace %SYS para acessar as rotinas ^PERFMON e, em seguida, retorna para o namespace original.

• Opera no namespace %SYS para acessar as rotinas ^PERFMON, retornando ao namespace original.

3. Fluxo de Execução

1. Uma requisição entra na aplicação Quarkus.

2. O interceptor CDI detecta a anotação @PerfmonReport e intercepta a chamada do método.

3. monitorSystem.startPerfmon() é invocado, acionando o monitoramento ^PERFMON do IRIS.

4. O método de negócio é executado normalmente (acesso a dados, transformações, lógica, etc.).

5. Após o método retornar ou lançar uma exceção, o interceptor garante que:

   • monitorSystem.generateReportPerfmon(...) seja chamado para criar um relatório de performance .txt.
   • monitorSystem.stopPerfmon() seja executado para encerrar a sessão de monitoramento.
   • O tempo total de execução do lado Java seja registrado usando Logger.infof(...).

6. O arquivo de relatório gerado é armazenado no diretório temporário do IRIS, normalmente: /usr/irissys/mgr/Temp/

   • O nome do arquivo segue o padrão: <ClassName><MethodName><timestamp>.txt

4. Desafios Técnicos e Soluções

5. Casos de Uso e Benefícios

• Permite visibilidade em tempo real da atividade do IRIS a partir do código Java.
• Simplifica a análise de performance e otimização de consultas para desenvolvedores.
• Útil para benchmarking, profiling e testes de regressão do sistema.
• Pode servir como um registro leve de auditoria de performance para operações críticas.

6. Exemplo Prático de Uso

O código-fonte completo e o setup de deployment estão disponíveis em:

• Open Exchange: https://openexchange.intersystems.com/package/quarkus-iris-monitor-system
• Repositório GitHub: https://github.com/Davi-Massaru/quarkus-iris-monitor-system

6.1 Visão Geral

A aplicação roda um servidor Quarkus conectado a uma instância InterSystems IRIS configurada com o namespace FHIRSERVER.
A camada ORM é implementada usando Hibernate ORM com PanacheRepository, permitindo mapeamento direto entre entidades Java e classes do banco IRIS.

Quando a aplicação é iniciada (via docker-compose up), são iniciados:

• O container IRIS, hospedando o modelo de dados FHIR e rotinas ObjectScript (incluindo AdapterPerfmonProc);
• O container Quarkus, expondo endpoints REST e conectando-se ao IRIS via driver JDBC nativo.

6.2 Endpoint REST

Um recurso REST expõe um endpoint simples para recuperar informações de pacientes:

@Path("/patient")
public class PatientResource {

    @Inject
    PatientService patientService;

    @GET
    @Path("/info")
    @Produces(MediaType.APPLICATION_JSON)
    public PatientInfoDTO searchPatientInfo(@QueryParam("key") String key) {
        return patientService.patientGetInfo(key);
    }
}

Este endpoint aceita um parâmetro de consulta (key) que identifica o recurso do paciente dentro do repositório de dados FHIR.

6.3 Camada de Serviço com @PerfmonReport

A classe PatientService contém a lógica de negócio para recuperar e compor informações do paciente.
Ela é anotada com @PerfmonReport, o que significa que cada requisição para /patient/info aciona o monitoramento de performance do IRIS:

@ApplicationScoped
public class PatientService {

    @Inject
    PatientRepository patientRepository;

    @PerfmonReport
    public PatientInfoDTO patientGetInfo(String patientKey) {

        Optional<Patient> patientOpt = patientRepository.find("key", patientKey).firstResultOptional();
        Patient patient = patientOpt.orElseThrow(() -> new IllegalArgumentException("Patient not found"));

        PatientInfoDTO dto = new PatientInfoDTO();
        dto.setKey(patient.key);
        dto.setName(patient.name);
        dto.setAddress(patient.address);
        dto.setBirthDate(patient.birthDate != null ? patient.birthDate.toString() : null);
        dto.setGender(patient.gender);
        dto.setMedications(patientRepository.findMedicationTextByPatient(patientKey));
        dto.setConditions(patientRepository.findConditionsByPatient(patientKey));
        dto.setAllergies(patientRepository.findAllergyByPatient(patientKey));

        return dto;
    }
}

6.4 Fluxo de Execução

Uma requisição é feita para: GET /patient/info?key=Patient/4

O Quarkus encaminha a requisição para PatientResource.searchPatientInfo().

O interceptor CDI detecta a anotação @PerfmonReport em PatientService.patientGetInfo().

Antes de executar a lógica de serviço:

• O interceptor invoca MonitorSystem.startPerfmon(), que chama a classe IRIS iris.src.dc.AdapterPerfmonProc.start().

• O método executa a lógica de negócio, consultando dados do paciente usando os mapeamentos Hibernate PanacheRepository.

Após a conclusão do método:

• MonitorSystem.generateReportPerfmon() é chamado para criar o relatório de performance.

• MonitorSystem.stopPerfmon() interrompe o monitoramento de performance do IRIS.

Um relatório .txt é gerado em: usr/irissys/mgr/Temp/

Exemplo de nome de arquivo: PatientService_patientGetInfo_20251005_161906.txt

6.5 Resultado

O relatório gerado contém estatísticas detalhadas de execução do IRIS, por exemplo:

                         Routine Activity by Routine

Started: 10/11/2025 05:07:30PM                    Collected: 10/11/2025 05:07:31PM

Routine Name                        RtnLines  % Lines   RtnLoads  RtnFetch  Line/Load Directory
----------------------------------- --------- --------- --------- --------- --------- ---------
Other                                     0.0       0.0       0.0       0.0         0
PERFMON                                  44.0       0.0       0.0       0.0         0 /usr/irissys/mgr/
%occLibrary                         3415047.0      34.1   48278.0       0.0      70.7 /usr/irissys/mgr/irislib/
iris.src.dc.AdapterPerfmonProc.1          7.0       0.0       2.0       0.0       3.5 /usr/irissys/mgr/FHIRSERVER/
%occName                            5079994.0      50.7       0.0       0.0         0 /usr/irissys/mgr/irislib/
%apiDDL2                            1078497.0      10.8   63358.0       0.0      17.0 /usr/irissys/mgr/irislib/
%SQL.FeatureGetter.1                 446710.0       4.5   66939.0       0.0       6.7 /usr/irissys/mgr/irislib/
%SYS.WorkQueueMgr                       365.0       0.0       1.0       0.0     365.0 /usr/irissys/mgr/
%CSP.Daemon.1                            16.0       0.0       1.0       0.0      16.0 /usr/irissys/mgr/irislib/
%SYS.TokenAuth.1                         14.0       0.0       5.0       0.0       2.8 /usr/irissys/mgr/
%Library.PosixTime.1                      2.0       0.0       0.0       0.0         0 /usr/irissys/mgr/irislib/
%SYS.sqlcq.uEXTg3QR7a7I7Osf9e8Bz...      52.0       0.0       1.0       0.0      52.0 /usr/irissys/mgr/
%SYS.SQLSRV                              16.0       0.0       0.0       0.0         0 /usr/irissys/mgr/
%apiOBJ                                 756.0       0.0       0.0       0.0         0 /usr/irissys/mgr/irislib/
FT.Collector.1                            0.0       0.0       0.0       0.0         0 /usr/irissys/mgr/
SYS.Monitor.FeatureTrackerSensor.1        0.0       0.0       0.0       0.0         0 /usr/irissys/mgr/
%SYS.Monitor.Control.1                    0.0       0.0       0.0       0.0         0 /usr/irissys/mgr/
%SYS.DBSRV.1                            252.0       0.0       4.0       0.0      63.0 /usr/irissys/mgr/
%sqlcq.FHIRSERVER.cls12.1                19.0       0.0       0.0       0.0         0 /usr/irissys/mgr/irislocaldata/
%sqlcq.FHIRSERVER.cls13.1                74.0       0.0       0.0       0.0         0 /usr/irissys/mgr/irislocaldata/
%sqlcq.FHIRSERVER.cls14.1                74.0       0.0       0.0       0.0         0 /usr/irissys/mgr/irislocaldata/
%sqlcq.FHIRSERVER.cls15.1                52.0       0.0       0.0       0.0         0 /usr/irissys/mgr/irislocaldata/
%SYS.System.1                             1.0       0.0       0.0       0.0         0 /usr/irissys/mgr/

Esses dados fornecem uma visão precisa sobre quais rotinas foram executadas internamente pelo IRIS durante aquela chamada REST — incluindo compilação de SQL, execução e acesso a dados FHIR.

Observação: As rotinas %sqlcq.FHIRSERVER.* registram todas as consultas SQL cache executadas pelo Quarkus dentro do método. Monitorar essas rotinas permite aos desenvolvedores analisar a execução das queries, compreender o comportamento do código e identificar possíveis gargalos de performance. Isso as torna uma ferramenta poderosa para desenvolvimento e depuração de operações relacionadas ao FHIR.

6.6 Resumo

Este exemplo demonstra como um serviço padrão Quarkus pode utilizar de forma transparente as ferramentas nativas de monitoramento do IRIS usando a anotação @PerfmonReport.
Ele combina:

• Interceptadores CDI (Quarkus)
• Hibernate PanacheRepositories (ORM)
• Rotinas ObjectScript nativas do IRIS (^PERFMON)

O resultado é um mecanismo de profiling de performance totalmente automatizado e reproduzível, que pode ser aplicado a qualquer método de serviço na aplicação.