Pesquisar

##Introdução [MonLBL](https://docs.intersystems.com/iris20251/csp/docbook/Doc.View.cls?KEY=GCM_monlbl) é uma ferramenta para analisar o desempenho da execução de código ObjectScript linha por linha. [`codemonitor.MonLBL`](https://github.com/lscalese/iris-monlbl-example/blob/master/src/dc/codemonitor/MonLBL.cls) é um wrapper baseado no pacote [`%Monitor.System.LineByLine`](https://docs.intersystems.com/iris20251/csp/documatic/%25CSP.Documatic.cls?LIBRARY=%25SYS&PRIVATE=1&CLASSNAME=%25Monitor.System.LineByLine)do InterSystems IRIS, projetado para coletar métricas precisas sobre a execução de rotinas, classes ou páginas CSP. O wrapper e todos os exemplos apresentados neste artigo estão disponíveis no seguinte repositório do GitHub: [iris-monlbl-example](https://github.com/lscalese/iris-monlbl-example) ## Funcionalidades A ferramenta permite a coleta de diversos tipos de métricas: - **RtnLine**: Número de execuções da linha - **GloRef**: Número de referências a globais geradas pela linha - **Time**: Tempo de execução da linha - **TotalTime**: Tempo de execução total, incluindo sub-rotinas chamadas Todas as métricas são exportadas para arquivos CSV. Além das métricas linha a linha, `dc.codemonitor.MonLBL` coleta estatísticas de globais: - Tempo total de execução - Número total de linhas executadas - Número total de referências a globais -T empo de CPU do sistema e do usuário * O tempo de CPU do usuário corresponde ao tempo gasto pelo processador executando o código da aplicação. * O tempo de CPU do sistema corresponde ao tempo gasto pelo processador executando operações do sistema operacional (chamadas de sistema, gerenciamento de memória, E/S). -Tempo de leitura do disco. ## Pré-requisitos Para monitorar o código com MonLBL: 1. Obtenha a classe `dc.codemonitor.MonLBL` (disponível [aqui](https://github.com/lscalese/iris-monlbl-example/blob/master/src/dc/codemonitor/MonLBL.cls)) 2. As rotinas ou classes a serem analisadas devem ser compiladas com as flags "ck". ## ⚠️ Aviso Importante O uso do monitoramento linha a linha impacta o desempenho do servidor. É importante seguir estas recomendações: - Use esta ferramenta apenas em um conjunto limitado de código e processos (idealmente para execução única em um terminal). - Evite usá-la em um servidor de produção (mas, às vezes, é necessário). - Prefira usar esta ferramenta em um ambiente de desenvolvimento ou teste. Essas precauções são essenciais para evitar problemas de desempenho que possam afetar usuários ou sistemas de produção. Observe que o código monitorado é executado aproximadamente 15-20% mais lentamente do que o código não monitorado. ## Uso ### Exemplo Básico ```objectscript // Cria uma instância de MonLBL Set mon = ##class(dc.codemonitor.MonLBL).%New() //Define as rotinas a serem monitoradas Set mon.routines = $ListBuild("User.MyClass.1") // Começa o monitoramento Do mon.startMonitoring() // Código a analisar // ... // Para o monitoramento e gera resultados Do mon.stopMonitoring() ``` **Nota**: O monitoramento iniciado aqui é válido apenas para o processo atual. Outros processos que executam o mesmo código não serão incluídos nas medições. ### Opções de Configuração O wrapper oferece várias opções configuráveis: - **directory**:Diretório onde os arquivos CSV serão exportados (o padrão é o diretório Temp do IRIS). - **autoCompile**: Recompila automaticamente as rotinas com as flags "ck" se necessário. - **metrics**: Lista personalizável de métricas a serem coletadas. - **decimalPointIsComma**: Usa uma vírgula como separador decimal para melhor compatibilidade com o Excel (dependendo do seu ambiente local). - **metricsEnabled**:Habilita ou desabilita a coleta de métricas linha a linha. ## Exemplo de Uso Avançado Aqui está um exemplo mais completo (disponível na classe `dc.codemonitor.Example`): ```objectscript ClassMethod MonitorGenerateNumber(parameters As %DynamicObject) As %Status { Set sc = $$$OK Try { // Exibe parâmetros recebidos Write "* Parameters:", ! Set formatter = ##class(%JSON.Formatter).%New() Do formatter.Format(parameters) Write ! // Cria e configura o monitor Set monitor = ##class(dc.codemonitor.MonLBL).%New() // AVISO: Em produção, defina o autoCompile para $$$NO // e manualmente compile o código a monitorar Set monitor.autoCompile = $$$YES Set monitor.metricsEnabled = $$$YES Set monitor.directory = ##class(%File).NormalizeDirectory(##class(%SYS.System).TempDirectory()) Set monitor.decimalPointIsComma = $$$YES // Configure a rotina para o monitor (formato "int" da classe) // Para achar o nome exato da rotina, use o comando: // Do $SYSTEM.OBJ.Compile("dc.codemonitor.DoSomething","ck") // A linha "Compiling routine XXX" deve exibir o nome da rotina Set monitor.routines = $ListBuild("dc.codemonitor.DoSomething.1") // Comece a monitorar $$$TOE(sc, monitor.startMonitoring()) // Execute o código a monitorar com tratamento de erro Try { Do ##class(dc.codemonitor.DoSomething).GenerateNumber(parameters.Number) // Importante: Sempre pare o monitoramento Do monitor.stopMonitoring() } Catch ex { // Pare o monitoramento mesmo em caso de erro Do monitor.stopMonitoring() Throw ex } } Catch ex { Set sc = ex.AsStatus() Do $SYSTEM.Status.DisplayError(sc) } Return sc } ``` Este exemplo demonstra várias melhores práticas importantes: - Uso de um bloco Try/Catch para tratamento de erros. - Interrupção sistemática do monitoramento, mesmo em caso de erro. - Configuração completa do monitor. ## Exemplo com Páginas CSP O MonLBL também permite o monitoramento de páginas CSP. Aqui está um exemplo (também disponível na classe`dc.codemonitor.ExampleCsp`): ```objectscript ClassMethod MonitorCSP(parameters As %DynamicObject = {{}}) As %Status { Set sc = $$$OK Try { // Exibe parâmetros recebidos Write "* Parameters:", ! Set formatter = ##class(%JSON.Formatter).%New() Do formatter.Format(parameters) Write ! // Cria e configura o monitor Set monitor = ##class(dc.codemonitor.MonLBL).%New() Set monitor.autoCompile = $$$YES Set monitor.metricsEnabled = $$$YES Set monitor.directory = ##class(%File).NormalizeDirectory(##class(%SYS.System).TempDirectory()) Set monitor.decimalPointIsComma = $$$YES // Para monitorar uma página CSP, use a rotina gerada // Exemplo: /csp/user/menu.csp --> classe: csp.menu --> rotina: csp.menu.1 Set monitor.routines = $ListBuild("csp.menu.1") // Páginas CSP necessitam de objetos %session, %request, e %response // Crie esses objetos com os parâmetros necessários Set %request = ##class(%CSP.Request).%New() // Configure os parâmetros de requisição se necessário // Set %request.Data("", 1) = Set %request.CgiEnvs("SERVER_NAME") = "localhost" Set %request.URL = "/csp/user/menu.csp" Set %session = ##class(%CSP.Session).%New(1234) // Configure os dados da sessão se necessário // Set %session.Data("", 1) = Set %response = ##class(%CSP.Response).%New() // Comece o monitoramento $$$TOE(sc, monitor.startMonitoring()) Try { // Para evitar a exibição do conteúdo da página CSP no terminal, // use a classe IORedirect para redirecionar sa saída para nula // (requere instalação via zpm "install io-redirect") Do ##class(IORedirect.Redirect).ToNull() // Chame a página CSP via seu método OnPage Do ##class(csp.menu).OnPage() // Restaure a saída padrão Do ##class(IORedirect.Redirect).RestoreIO() // Pare o monitoramento Do monitor.stopMonitoring() } Catch ex { // Sempre restaure a saída e pare o monitoramento no caso de erro Do ##class(IORedirect.Redirect).RestoreIO() Do monitor.stopMonitoring() Throw ex } } Catch ex { Set sc = ex.AsStatus() Do $SYSTEM.Status.DisplayError(sc) } Return sc } ``` Pontos chave para monitorar páginas CSP: 1. **Identificação da Rotina**: Uma página CSP é compilada em uma classe e uma rotina. Por exemplo`/csp/user/menu.csp` gera a classe `csp.menu` e a rotina `csp.menu.1`. 2. **Ambiente CSP **:É necessário criar objetos de contexto CSP (%request, %session, %response) para que a página seja executada corretamente. 3. **Redirecionamento de Saída:**: Para evitar a exibição de conteúdo HTML no terminal, você pode usar a ferramenta IORedirect (disponível no [OpenExchange](https://openexchange.intersystems.com/package/IO-Redirect) via `zpm "install io-redirect"`). 4. **Chamada da Página**: A execução é feita através do método `OnPage()` da classe gerada. ##Exemplo de Saída Aqui está um exemplo da saída obtida ao executar o método `MonitorGenerateNumber`: ``` USER>d ##class(dc.codemonitor.Example).MonitorGenerateNumber({"number":"100"}) * Parameters: { "number":"100" } * Metrics are exported to /usr/irissys/mgr/Temp/dc.codemonitor.DoSomething.1.csv * Perf results: { "startDateTime":"2025-05-07 18:45:42", "systemCPUTime":0, "userCPUTime":0, "timing":0.000205, "lines":19, "gloRefs":14, "diskReadInMs":"0" } ``` Nesta saída, podemos observar: 1.Exibição dos parâmetros de entrada. 2. Confirmação de que as métricas foram exportadas para um arquivo CSV. 3.Um resumo do desempenho global em formato JSON, incluindo: - Data e hora de início - Tempo de CPU do sistema e do usuário - Tempo total de execução - Número de linhas executadas - Número de referências a globais - Tempo de leitura do disco ## Interpretando os Resultados CSV Após a execução, arquivos CSV (um por rotina na lista de rotinas $ListBuild) são gerados no diretório configurado. Esses arquivos contêm: -Número da linha -Métricas coletadas para cada linha - Código-fonte da linha (nota: se você não compilou com a flag "k", o código-fonte não estará disponível no arquivo CSV) Aqui está um exemplo do conteúdo de um arquivo CSV exportado: (dc.codemonitor.DoSomething.1.csv): | Line | RtnLine | GloRef | Time | TotalTime | Code | |------|---------|--------|------|-----------|------| | 1 | 0 | 0 | 0 | 0 | ` ;dc.codemonitor.DoSomething.1` | | 2 | 0 | 0 | 0 | 0 | ` ;Generated for class dc.codemonitor.DoSomething...` | | 3 | 0 | 0 | 0 | 0 | ` ;;59595738;dc.codemonitor.DoSomething` | | 4 | 0 | 0 | 0 | 0 | ` ;` | | 5 | 0 | 0 | 0 | 0 | `GenerateNumber(n=1000000) methodimpl {` | | 6 | 1 | 0 | 0.000005 | 0.000005 | ` For i=1:1:n {` | | 7 | 100 | 0 | 0.000019 | 0.000019 | ` Set number = $Random(100000)` | | 8 | 100 | 0 | 0.000015 | 0.000015 | ` Set isOdd = number # 2` | | 9 | 100 | 0 | 0.000013 | 0.000013 | ` }` | | 10 | 1 | 0 | 0.000003 | 0.000003 | ` Return }` | Nesta tabela, podemos analisar: - **RtnLine**: Indica quantas vezes cada linha foi executada (aqui, as linhas 6 e 10 foram executadas uma vez) - **GloRef**: Mostra as referências globais geradas por cada linha - **Time**: Apresenta o tempo de execução específico de cada linha - **TotalTime**: Exibe o tempo total, incluindo chamadas para outras rotinas Esses dados podem ser facilmente importados para uma planilha para uma análise aprofundada. As linhas que mais consomem recursos em termos de tempo ou acesso a dados podem, assim, ser facilmente identificadas. ### Observação sobre a Eficiência do Cache A eficiência do cache do banco de dados (buffer global) pode mascarar problemas reais de desempenho. Durante a análise, o acesso aos dados pode parecer rápido devido a esse cache, mas pode ser muito mais lento em certas condições de uso no mundo real. Em sistemas de desenvolvimento, você pode limpar o cache entre as medições com o seguinte comando: ```objectscript Do ClearBuffers^|"%SYS"|GLOBUFF() ``` ⚠️ **ATENÇÃO**: Tenha cuidado com este comando, pois ele se aplica a todo o sistema. Nunca o utilize em um ambiente de produção, já que pode impactar o desempenho de todas as aplicações em execução. ## Conclusão O monitoramento linha a linha é uma ferramenta valiosa para analisar o desempenho do código ObjectScript. Ao identificar precisamente as linhas de código que consomem mais recursos, ele permite que os desenvolvedores economizem um tempo significativo na análise de gargalos de desempenho.

# 1. Demonstração Integrated ML Este repositório é uma demonstração do IntegratedML e Python Incorporado. - [1. Demonstração do Integrated ML](#1-integrated-ml-demonstration) - [2. Construindo a Demonstração](#2-building-the-demo) - [2.1. Arquitetura](#21-architecture) - [2.2. Construindo o contêiner nginx](#22-building-the-nginx-container) - [3. Executando a demonstração](#3-running-the-demo) - [4. Back-end Python](#4-python-back-end) - [4.1. Python Incorporado](#41-embedded-python) - [4.1.1. Configurando o contêiner](#411-setting-up-the-container) - [4.1.2. Utilizando o Python Incorporado](#412-using-embedded-python) - [4.1.3. Comparação Lado a Lado](#413-side-by-side-comparaison) - [4.2. Disponibilizando o Servidor](#42-launching-the-server) - [5. IntegratedML](#5-integratedml) - [5.1. Explorando ambos datasets](#51-exploring-both-datasets) - [5.2. Gerenciando Modelos](#52-managing-models) - [5.2.1. Criando um Modelo](#521-creating-a-model) - [5.2.2. Treinando um Modelo](#522-training-a-model) - [5.2.3. Validando um Modelo](#523-validating-a-model) - [5.2.4. Realizando Previsões](#524-making-predictions) - [6. Utilizando o COS](#6-using-cos) - [7. Maior detalhamento com o DataRobot](#7-more-explainability-with-datarobot) - [8. Conclusão](#8-conclusion) # 2. Criando a Demonstração Para criar a demonstração você deve apenas executar o seguinte comando: ```` docker compose up ```` ## 2.1. Arquitetura Dois contêineres serão criados: um com o IRIS e um com o servidor nginx.  A imagem do IRIS utilizada já contêm o Python Incorporado. Após contruído, o contêiner irá executar um servidor wsgi com a API Flask. Estamos utilizando o pacote csvgen da Comunidade para importar o dataset titanic para o IRIS. Para o dataset de noshowutilizamos outro método customizado (o método de classe `Load()` da classe `Util.Loader`). PAra que o contêiner teha acesso aos arquivos csv nós associamos o diretório local `iris/` ao diretório `/opt/irisapp/` do contêiner. ## 2.2. Construindo o contêiner nginx Para construir nosso contêiner nginx o docker utiliza uma construção multiestágio. Inicialmente ele cria um contêiner com nó, então ele instala o npm e copia todos nossos arquivos para o contêiner. Depois disto ele constrói o projeto com o comando `ng build` e o arquivo de saída é copiado para um novo contêiner que possui apenas o nginx. Graças a esta manobra nós obtemos um contêiner bem leve que não contém todas a bibliotecas e ferramentas utilizadas para criar páginas web. Você consegue verificar os detalhes desta construção multiestágio no arquivo `angular/Dockerfile`. Nós também configuramos os parâmetros de nosso servidor nginx graças ao arquivo `angular/nginx.default.conf`. # 3. Executando a Demonstração Apenas acesse o endereço: http://localhost:8080/ e é isso! Aproveitem! # 4. Back-end Python O back-end é baseado no Python Flask. Nós utilizamos o Python Incorporado para realizar as chamadas às classes do IRIS e executar consultas a partir do Python. ## 4.1. Python Incorporado ### 4.1.1. Configurando o contêiner Precisamos inicialmente explicitar no dockerfile duas variáveis de ambiente que o Python Incorporado irá utilizar: ````dockerfile ENV IRISUSERNAME "SuperUser" ENV IRISPASSWORD $IRIS_PASSWORD ```` Com uma configuração no arquivo docker-compose do $IRIS_PASSWORD como esta: ````yaml iris: build: args: - IRIS_PASSWORD=${IRIS_PASSWORD:-SYS} ```` (A senha transferida é a que está configurada em sua máquina local ou, se a mesma não estiver definida, será por padrão a "SYS") ### 4.1.2. Utilizando o Python Incorporado Para utilizar o Python Incorporado nós utilizamos `irispython` como interpretador python e fazemos: ```python import iris ``` Bem no começo do arquivo. Iremos então poder executar métodos como:  Como você pode ver, de forma a recuperar um paciente pelo ID nós apenas executamos uma consulta e utilizamos seu resultado. Também podemos utilizar diretamente os objetos IRIS:  Aqui nós utilizamos uma consulta SQL para recuperar todos os IDs da tabela e então recuperamos cada passageiro da tabela com o método `%OpenId()` da classe Titanic.Table.Passenger` (notem que como o `%` é um caractere ilegal in Python utilizamos o `_` em substituição). Graças ao Flask impleentamos todas nossas rotas e métodos desta forma. ### 4.1.3. Comparação Lado a Lado Nesta imagem você tem uma comparação lado a lado entre uma implementação **Flask** e uma implementação **ObjectScript**. Como você pode verificar, existem várias similaridades. ## 4.2. Disponibilizando o Servidor Para disponibilizar o servidor utilizamos `gunicorn` com `irispython`. Adicionamos a seguinte linha no arquivo docker-compose: ````yaml iris: command: -a "sh /opt/irisapp/flask_server_start.sh" ```` Esta alteração irá executar (graças a flag `-a`) , depois que o contêiner for iniciado, o seguinte script: ````bash #!/bin/bash cd ${FLASK_PATH} ${PYTHON_PATH} /usr/irissys/bin/gunicorn --bind "0.0.0.0:8080" wsgi:app -w 4 2>&1 exit 1 ```` Com as variáveis de ambiente definidas no Dockerfile desta forma: ````dockerfile ENV PYTHON_PATH=/usr/irissys/bin/irispython ENV FLASK_PATH=/opt/irisapp/python/flask ```` Iremos então ter acesso ao back-end Flask através da porta local `4040`, devido a termos associado a porta 8080 do contêiner a ela. # 5. IntegratedML ## 5.1. Explorando ambos datasets Para ambos datasets você tera um acesso a um CRUD completo, lhe permitindo modificar como quiser as tabelas gravadas. Para trocar de um dataset para outro você pode clicar no botão localizado na parte superior, à direita. ## 5.2. Gerenciando Modelos ### 5.2.1. Criando um Modelo Uma vez que você descobriu o modelo, você pode agora criar um modelo para prever o valor que você quiser. Acionando o menu lateral `Model Manager`, no item `Model List` você terá acesso a seguinte página (aqui, no caso do dataset NoShow):  Você pode escolher qual valor você quer prever, o nome do seu modelo e quais variáveis você quer utilizar para realizar a previsão. No menu lateral você pode selecionar `See SQL queries?` para visualizar como os modelos são gerenciados no IRIS. Depois de criar um modelo você deverá ver o seguinte:  Como vocês podem observar, a criação de um modelo necessita apenas de uma consulta SQL. As informações que você possui são todas as informações que você pode recuperar do IRIS. Na coluna `actions` você pode deletar ou remover um modelo. Remover o modelo irá remover todos os treinamentos (e validações) exceto a última. ### 5.2.2. Treinando o Modelo Na próxima aba você poderá treinar seus modelos. Você poderá escolher entre 3 provedores. InterSystems' `AutoML`, `H2O`, uma solução de código aberto, e `DataRobot`, onde você consegue um período de 14 dias de teste grátis se você se registrar no site deles. Você pode selecionar o percentual do dataset que você deseja utilizar para treinar seu modelo. Como o treinamento pode ser demorado em casos de grandes datasets, para propósito de demonstrações é possível utilizar um dataset menor. Aqui nós treinamos um modelo usando o dataset Titanic completo:  O botão na coluna `actions` irá permitir que você verifique o log. Para o AutoML você verá o que o algoritmo fez de fato: como ele preparou os dados e como ele escolheu qual modelo utilizar. Para treinar um modelo é necessária apenas uma consulta SQL, como você pode verificar na seção de mensagens do menu lateral. Tenha em mente que nessas duas abas você verá apenas os modelos referentes ao dataset que você está utilizando no momento. ### 5.2.3. Validando um Modelo Finalmente você pode validar um modelo na aba final. Clicando na execução da validação irá abrir uma janela de pop-up. Lá você poderá escolher o percentual do dataset que será utilizado para a validação.  Mais uma vez, é necessária apenas uma consulta SQL. ### 5.2.4. Realizando Previsões No menu `Make Predictions`, na última aba, você pode realizar previsões utilizando seu recente modelo treinado. Você precisa apenas buscar um passageiro / paciente e selecioná-lo, selecionar um dos modelos treinados e delecionar a opção prever. No caso de um modelo de classificação (como neste exemplo, para prever a sobrevivência), a previsão estará associada com a probabilidade de estar na classe prevista. No caso da Sra. Fatima Masselmani, o modelo previu corretamente que ela sobreviveu, com uma probabilidade de 73%. Logo abaixo desta predição você pode visualizar os dados utilizados pelo modelo:  Mais uma vez, foi necessária apenas uma consulta para recuperar a predição e uma para a probabilidade. # 6. Utilizando o COS A demonstração disponibiliza duas APIs. Nós utilizamos a API Flask com o Python Incorporado porém um serviço REST em COS também foi configurado na construção do contêiner. Pressionando o botão na parte superior direita **"Switch to COS API"**, você poderá utilizar este serviço. Note como nada se altera, ambas as APIs são equivalentes e funcionam da mesma forma. # 7. Maior detalhamento com o DataRobot Se você quiser um maior detalhamento (mais do que o log pode lhe oferecer), sugerimos que você utiliza o provedor DataRobot. Para isso você precisará acessar o endereço de sua instância DataRobot e procurar por `Developer Tools` para conseguir seu token. Ao treinar o modelo a página solicitará seu token. Uma vez que o treinamento iniciar você poderá acessar sua instância DataRobot para saber muito mais sobre seu dataset e seus modelos :  Aqui podemos ver que os campos `sex` e `name` de cada passageiro foram os valores mais importantes utilizados na predição da sobrevivência. Nós podemos também visualizar que o campo `fare` contém informações fora do padrão. Uma vez que os modelos estiverem treinados você poderá acessar **vários** detalhes, aqui está um exemplo:  # 8. Conclusão Através desta demonstração nós pudemos observar como é fácil criar, treinar e validar um modelo, bem como predizer valores através de poucas consultas SQL. Conseguimos fazer isto utilizando uma API RESTful com Python Flask, utilizando Python Incorporado e também fizemos um comparativo utilizando uma API COS. O front-end foi desenvolvido em Angular.

Desde o Caché 2017, o mecanismo SQL inclui um novo conjunto de estatísticas. Ele registra o número de vezes que uma consulta é executada e o tempo que leva para executá-la. Esta é uma mina de ouro para qualquer pessoa que está monitorando e tentando otimizar o desempenho de uma aplicação que inclui muitas instruções SQL, mas que não é tão fácil de acessar os dados como algumas pessoas desejam. Este artigo e o código de exemplo associado explicam como usar essas informações e como extrair rotineiramente um resumo de estatísticas diárias e manter um registro histórico de desempenho do SQL de sua aplicação. O que está registrado? Toda vez que uma instrução SQL é executada, o tempo gasto é registrado. Esse registro é muito leve e você não pode desativá-lo. Para minimizar o custo, as estatísticas são mantidas na memória e gravadas no disco periodicamente. Os dados incluem o número de vezes que uma consulta foi executada no dia e a média e o tempo total gasto. Os dados não são gravados no disco imediatamente, e depois de gravados, as estatísticas são atualizadas pela tarefa "Atualizar estatísticas de consulta SQL" que geralmente é programada para se executada a cada hora. Essa tarefa pode ser executada manualmente, mas se você quiser ver as estatísticas em tempo real enquanto testa uma consulta, todo o processo requer um pouco de paciência. Aviso: No InterSystems IRIS 2019 e anteriores, essas estatísticas não são coletadas para SQL embutido em classes ou rotinas que foram implantadas usando o mecanismo %Studio.Project:Deploy. Nada quebrará com o código de exemplo, mas pode enganar você (me enganou) fazendo-o pensar que tudo estava OK porque nada parecia tão custoso. Como você vê as informações? Você pode ver a lista de consultas no portal de gerenciamento. Vá para a página SQL e clique na aba ‘Instruções SQL’. É ótimo para uma nova consulta que você está executando e examinando, mas se houver milhares de consultas em execução, pode-se tornar incontrolável. A alternativa é usar o SQL para pesquisar as consultas. As informações são armazenadas em tabelas no esquema INFORMATION_SCHEMA. Este esquema tem várias tabelas e incluí alguns exemplos de consultas SQL no final deste artigo. Quando as estatísticas são removidas? Os dados de uma consulta são removidos sempre que ela é recompilada. Portanto, para consultas dinâmicas, isso pode significar quando as consultas em cache são limpas. Para SQL embutido, isso significa quando a classe ou rotina em que o SQL está embutido é recompilado. Em um site ativo, é razoável esperar que as estatísticas sejam mantidas por mais de um dia, mas as tabelas que contêm as estatísticas não podem ser usadas como uma fonte de referência para relatórios ou análises de longo prazo. Como você pode resumir as informações? Recomendo extrair os dados todas as noites em tabelas permanentes que são mais fáceis de trabalhar ao gerar os relatórios de desempenho. Há uma chance de que algumas informações sejam perdidas se as classes forem compiladas durante o dia, mas é improvável que isso faça alguma diferença real em sua análise de consultas lentas. O código a seguir é um exemplo de como você pode extrair as estatísticas em um resumo diário para cada consulta. Inclui três classes curtas: * Uma tarefa que deve ser executada todas as noites. * DRL.MonitorSQL é a classe principal que extrai e armazena os dados das tabelas INFORMATION_SCHEMA. A terceira classe DRL.MonitorSQLText é uma otimização que armazena o texto da consulta (potencialmente longo) uma vez e armazena apenas o hash da consulta nas estatísticas de cada dia. Notas sobre o exemplo A tarefa é extraída do dia anterior e, portanto, deve ser agendada logo após a meia-noite. Você pode exportar mais dados históricos, se houver. Para extrair os últimos 120 dias Faça ##class(DRL.MonitorSQL).Capture($h-120,$h-1) O código de exemplo lê o ^rIndex global diretamente porque as versões mais antigas das estatísticas não expunham a Data ao SQL. A variação, incluí loops em todos os namespaces na instância, mas isso nem sempre é apropriado. Como consultar os dados extraídos Uma vez que os dados são extraídos, você pode encontrar as consultas mais pesadas executando SELECT top 20 S.RunDate,S.RoutineName,S.TotalHits,S.SumpTIme,S.Hash,t.QueryText from DRL.MonitorSQL S left join DRL.MonitorSQLText T on S.Hash=T.Hash where RunDate='08/25/2019' order by SumpTime desc Além disso, se você escolher o hash para uma consulta custosa, poderá ver o histórico dessa consulta com SELECT S.RunDate,S.RoutineName,S.TotalHits,S.SumpTIme,S.Hash,t.QueryText from DRL.MonitorSQL S left join DRL.MonitorSQLText T on S.Hash=T.Hash where S.Hash='CgOlfRw7pGL4tYbiijYznQ84kmQ=' order by RunDate No início deste ano, obtive dados de um site ativo e examinei as consultas mais custosas. Uma consulta demorava em média menos de 6 segundos, mas estava sendo chamada 14.000 vezes por dia, totalizando quase 24 horas decorridas todos os dias. Efetivamente, um núcleo estava totalmente ocupado com esta única consulta. Pior ainda, a segunda consulta que leva uma hora foi uma variação da primeira. Data de Execução Nome da Rotina Visitas Totais Tempo Total Hash Texto da Consulta (abreviado) 16/03/2019 14.576 85.094 5xDSguu4PvK04se2pPiOexeh6aE= DECLARE C CURSOR FOR SELECT * INTO :%col(1) , :%col(2) , :%col(3) , :%col(4) … 16/03/2019 15.552 3.326 rCQX+CKPwFR9zOplmtMhxVnQxyw= DECLARE C CURSOR FOR SELECT * INTO :%col(1) , :%col(2) , :%col(3) , :%col(4) , … 16/03/2019 16.892 597 yW3catzQzC0KE9euvIJ+o4mDwKc= DECLARE C CURSOR FOR SELECT * INTO :%col(1) , :%col(2) , :%col(3) , :%col(4) , :%col(5) , :%col(6) , :%col(7) , 16/03/2019 16.664 436 giShyiqNR3K6pZEt7RWAcen55rs= DECLARE C CURSOR FOR SELECT * , TKGROUP INTO :%col(1) , :%col(2) , :%col(3) , .. 16/03/2019 74.550 342 4ZClMPqMfyje4m9Wed0NJzxz9qw= DECLARE C CURSOR FOR SELECT … Tabela 1: Resultados reais do site do cliente Tabelas no esquema INFORMATION_SCHEMA Assim como as estatísticas, as tabelas neste esquema controlam onde as consultas, colunas, índices etc. são usados. Normalmente, a instrução SQL é a tabela inicial e é juntada em algo como “Statements.Hash=OtherTable.Statement”. A consulta equivalente para acessar essas tabelas diretamente para encontrar as consultas mais custosas para um dia seria… SELECT DS.Day,Loc.Location,DS.StatCount,DS.StatTotal,S.Statement,S.Hash FROM INFORMATION_SCHEMA.STATEMENT_DAILY_STATS DS left join INFORMATION_SCHEMA.STATEMENTS S on S.Hash=DS.Statement left join INFORMATION_SCHEMA.STATEMENT_LOCATIONS Loc on S.Hash=Loc.Statement where Day='08/26/2019' order by DS.stattotal desc Esteja você pensando em configurar um processo mais sistemático ou não, recomendo que todos com uma grande aplicação que usa SQL executem essa consulta hoje. Se uma consulta específica parecer custosa, você pode obter o histórico executando SELECT DS.Day, Loc.Location, DS.StatCount, DS.StatTotal, S.Statement, S.Hash FROM INFORMATION_SCHEMA.STATEMENT_DAILY_STATS DS left join INFORMATION_SCHEMA.STATEMENTS S on S.Hash=DS.Statement left join INFORMATION_SCHEMA.STATEMENT_LOCATION Loc on S.Hash=Loc.Statement where S.Hash='jDqCKaksff/4up7Ob0UXlkT2xKY=' order by DS.Day Exemplo de código para extrair estatísticas diariamente Isenção de responsabilidade padrão - este exemplo é apenas para ilustração. Não há suporte ou garantia de funcionamento. Class DRL.MonitorSQLTask Extends %SYS.Task.Definition{Parameter TaskName = "SQL Statistics Summary";Method OnTask() As %Status{ set tSC=$$$OK TRY { do ##class(DRL.MonitorSQL).Run() } CATCH exp { set tSC=$SYSTEM.Status.Error("Error in SQL Monitor Summary Task") } quit tSC }} Class DRL.MonitorSQLText Extends %Persistent{/// Hash do texto da consultaProperty Hash As %String; /// texto de consulta para hashProperty QueryText As %String(MAXLEN = 9999);Index IndHash On Hash [ IdKey, Unique ];} /// Resumo das estatísticas de consulta SQL de custo muito baixo coletadas no Caché 2017.1 e posterior. /// Consulte a documentação sobre "Detalhes da instrução SQL" para obter informações sobre os dados de origem. /// Os dados são armazenados por data e hora para dar suporte a consultas ao longo do tempo. /// Normalmente executado para resumir os dados da consulta SQL do dia anterior.Class DRL.MonitorSQL Extends %Persistent{/// RunDate e RunTime identificam exclusivamente uma execuçãoProperty RunDate As %Date;/// Horário em que a captura foi iniciada/// RunDate e RunTime identificam exclusivamente uma execuçãoProperty RunTime As %Time;/// Contagem do total de acessos para o período Property TotalHits As %Integer;/// Soma de pTimeProperty SumPTime As %Numeric(SCALE = 4);/// Rotina onde o SQL é encontradoProperty RoutineName As %String(MAXLEN = 1024);/// Hash do texto da consultaProperty Hash As %String;Property Variance As %Numeric(SCALE = 4);/// Namespace onde as consultas são executadasProperty Namespace As %String;/// A execução padrão processará os dados dos dias anteriores para um único dia./// Outras combinações de intervalo de datas podem ser obtidas usando o método de captura.ClassMethod Run(){ //Cada execução é identificada pela data / hora de início para manter os itens relacionados juntos set h=$h-1 do ..Capture(+h,+h)}/// Captura estatísticas históricas para um intervalo de datasClassMethod Capture(dfrom, dto){ set oldstatsvalue=$system.SQL.SetSQLStatsJob(-1) set currNS=$znspace set tSC=##class(%SYS.Namespace).ListAll(.nsArray) set ns="" set time=$piece($h,",",2) kill ^||TMP.MonitorSQL do { set ns=$o(nsArray(ns)) quit:ns="" use 0 write !,"processing namespace ",ns zn ns for dateh=dfrom:1:dto { set hash="" set purgedun=0 do { set hash=$order(^rINDEXSQL("sqlidx",1,hash)) continue:hash="" set stats=$get(^rINDEXSQL("sqlidx",1,hash,"stat",dateh)) continue:stats="" set ^||TMP.MonitorSQL(dateh,ns,hash)=stats &SQL(SELECT Location into :tLocation FROM INFORMATION_SCHEMA.STATEMENT_LOCATIONS WHERE Statement=:hash) if SQLCODE'=0 set Location="" set ^||TMP.MonitorSQL(dateh,ns,hash,"Location")=tLocation &SQL(SELECT Statement INTO :Statement FROM INFORMATION_SCHEMA.STATEMENTS WHERE Hash=:hash) if SQLCODE'=0 set Statement="" set ^||TMP.MonitorSQL(dateh,ns,hash,"QueryText")=Statement } while hash'="" } } while ns'="" zn currNS set dateh="" do { set dateh=$o(^||TMP.MonitorSQL(dateh)) quit:dateh="" set ns="" do { set ns=$o(^||TMP.MonitorSQL(dateh,ns)) quit:ns="" set hash="" do { set hash=$o(^||TMP.MonitorSQL(dateh,ns,hash)) quit:hash="" set stats=$g(^||TMP.MonitorSQL(dateh,ns,hash)) continue:stats="" // No loop, pela primeira vez, exclua todas as estatísticas do dia para que seja executável novamente // Mas se executarmos por um dia após os dados brutos terem sido eliminados, isso destruirá tudo // então faça aqui, onde já sabemos que há resultados para inserir em seu lugar. if purgedun=0 { &SQL(DELETE FROM websys.MonitorSQL WHERE RunDate=:dateh ) set purgedun=1 } set tObj=##class(DRL.MonitorSQL).%New() set tObj.Namespace=ns set tObj.RunDate=dateh set tObj.RunTime=time set tObj.Hash=hash set tObj.TotalHits=$listget(stats,1) set tObj.SumPTime=$listget(stats,2) set tObj.Variance=$listget(stats,3) set tObj.Variance=$listget(stats,3) set queryText=^||TMP.MonitorSQL(dateh,ns,hash,"QueryText") set tObj.RoutineName=^||TMP.MonitorSQL(dateh,ns,hash,"Location") &SQL(Select ID into :TextID from DRL.MonitorSQLText where Hash=:hash) if SQLCODE'=0 { set textref=##class(DRL.MonitorSQLText).%New() set textref.Hash=tObj.Hash set textref.QueryText=queryText set sc=textref.%Save() } set tSc=tObj.%Save() //evite duplicar o texto da consulta em cada registro porque pode ser muito longo. Use uma tabela de pesquisa //com chave no hash. Se não existir, adicione.. if $$$ISERR(tSc) do $system.OBJ.DisplayError(tSc) if $$$ISERR(tSc) do $system.OBJ.DisplayError(tSc) } while hash'="" } while ns'="" } while dateh'="" do $system.SQL.SetSQLStatsJob(0)}Query Export(RunDateH1 As %Date, RunDateH2 As %Date) As %SQLQuery{SELECT S.Hash,RoutineName,RunDate,RunTime,SumPTime,TotalHits,Variance,RoutineName,T.QueryText FROM DRL.MonitorSQL S LEFT JOIN DRL.MonitorSQLText T on S.Hash=T.Hash WHERE RunDate>=:RunDateH1 AND RunDate<=:RunDateH2}}

**Tempo** **estimado de leitura**: 6 minutos   Olá a todos, Fui apresentado ao TDD há quase 9 anos e imediatamente me apaixonei por ele.  Hoje em dia se tornou muito popular, mas, infelizmente, vejo que muitas empresas não o utilizam. Além disso, muitos desenvolvedores nem sabem o que é exatamente ou como usá-lo, principalmente iniciantes.     #### Visão Geral Meu objetivo com este artigo é mostrar como usar TDD com %UnitTest. Vou mostrar meu fluxo de trabalho e explicar como usar o [cosFaker](https://github.com/henryhamon/cosfaker), um dos meus primeiros projetos, que criei usando o Caché e recentemente carreguei no [OpenExchange](https://openexchange.intersystems.com/package/CosFaker). Então, aperte o cinto e vamos lá.     #### O que é TDD? O Desenvolvimento Guiado por Testes (TDD) pode ser definido como uma prática de programação que instrui os desenvolvedores a escrever um novo código apenas se um teste automatizado falhar. Existem toneladas de artigos, palestras, apresentações, seja o que for, sobre suas vantagens e todas estão corretas. Seu código já nasce testado, você garante que seu sistema realmente atenda aos requisitos definidos para ele, evitando o excesso de engenharia, e você tem um feedback constante. Então, por que não usar o TDD? Qual é o problema com o TDD? A resposta é simples: o Custo! Isso custa muito! Como você precisa escrever mais linhas de código com TDD, é um processo lento. Mas com o TDD você tem um custo final para criar um produto AGORA, sem ter que adicioná-lo no futuro. Se você executar os testes o tempo todo, encontrará os erros antecipadamente, reduzindo assim o custo de sua correção. Portanto, meu conselho: Simplesmente Faça!     #### Configuração A InterSystems tem uma documentação e tutorial sobre como usar o  %UnitTest, [que você pode ler aqui. ](https://irisdocs.intersystems.com/irislatest/csp/docbook/DocBook.UI.Page.cls?KEY=TUNT) Eu uso o vscode para desenvolver. Desta forma, crio uma pasta separada para testes. Eu adiciono o caminho para código do meu projeto ao UnitTestRoot e quando executo testes, passo o nome da subpasta de teste. E eu sempre passo no qualificador loadudl   Set ^UnitTestRoot = "~/code" Do ##class(%UnitTest.Manager).RunTest("myPack","/loadudl")   #### Passos Provavelmente você já ouviu falar sobre o famoso ciclo TDD: vermelho ➡ verde ➡ refatorar. Você escreve um teste que falha, você escreve um código de produção simples para fazê-lo passar e refatora o código de produção. Então, vamos sujar as mãos e criar uma classe para fazer cálculos matemáticos e outra para testá-la. A última classe deve estender de %UnitTest.TestCase. Agora vamos criar um ClassMethod para retornar um quadrado de um número inteiro: Class Production.Math { ClassMethod Square(pValue As %Integer) As %Integer { } }   E teste o que acontecerá se passarmos 2. Deve retornar 4.   Class TDD.Math Extends %UnitTest.TestCase { Method TestSquare() { Do $$$AssertEquals(##class(Production.Math).Square(2), 4) } }   Se você executar: Do ##class(%UnitTest.Manager).RunTest("TDD","/loadudl") o teste irá Falhar    Vermelho! O próximo passo é torná-lo Verde.  Para fazer funcionar, vamos retornar 4 como resultado da execução do nosso método Square. Class Production.Math { ClassMethod Square(pValue As %Integer) As %Integer { Quit 4 } } e executar novamente nosso teste.    Provavelmente você não está muito satisfeito com esta solução, porque ela funciona para apenas um cenário. Ótimo! Vamos dar o próximo passo. Vamos criar outro cenário de teste, agora enviando um número negativo.   Class TDD.Math Extends %UnitTest.TestCase { Method TestSquare() { Do $$$AssertEquals(##class(Production.Math).Square(2), 4) } Method TestSquareNegativeNumber() { Do $$$AssertEquals(##class(Production.Math).Square(-3), 9) } } Quando executamos o teste:    ele Falhará novamente, então vamos refatorar o código de produção:   Class Production.Math { ClassMethod Square(pValue As %Integer) As %Integer { Quit pValue * pValue } } e executar novamente nossos testes:    Agora tudo funciona bem... Esse é o ciclo do TDD, em pequenos passos. Você deve estar se perguntando: por que devo seguir esses passos? Por que eu tenho que ver o teste falhar? Trabalhei em equipes que escreveram o código de produção e só depois escrevi os testes. Mas eu prefiro seguir estes passos de bebê pelos seguintes motivos: Tio Bob (Robert C. Martin) disse que escrever testes depois de escrever o código não é TDD e, em vez disso, é chamado de “perda de tempo”. Outro detalhe, quando vejo o teste falhar, e depois vejo passar, estou testando o teste. Seu teste também é um código; e pode conter erros também. E a maneira de testá-lo é garantir que ele falhe e seja aprovado quando for necessário. Desta forma, você "testou o teste".    #### cosFaker Para escrever bons testes, você pode precisar gerar dados de teste primeiro. Uma maneira de fazer isso é gerar um despejo (dump) de dados e usá-lo em seus testes. Outra maneira é usar o [cosFaker ](https://openexchange.intersystems.com/package/CosFaker)para gerar facilmente dados falsos quando você precisar deles.  Basta fazer o download do arquivo xml, em seguida vá para o Portal de Gerenciamento -> System Explorer -> Classes -> Import. Selecione o arquivo xml a ser importado ou arraste o arquivo no Studio. Você também pode importá-lo usando o Terminal   Do $system.OBJ.Load("yourpath/cosFaker.vX.X.X.xml","ck")   ##### Localização O cosFaker adicionará arquivos de localidades na pasta da aplicação CSP padrão. Por enquanto, existem apenas dois idiomas: Inglês e Português do Brasil (minha língua nativa).  O idioma dos dados é escolhido de acordo com a configuração do seu Caché. A localização do cosFaker é um processo contínuo, se você quiser ajudar, não hesite em criar um provedor localizado para sua própria localidade e enviar um Pull Request. Com o cosFaker você pode gerar palavras aleatórias, parágrafos, números de telefone, nomes, endereços, e-mails, preços, nomes de produtos, datas, códigos de cores hexadecimais... etc. Todos os métodos são agrupados por assunto nas classes, ou seja, para gerar uma Latitude você chama o método Latitude na classe Address      Write ##class(cosFaker.Address).Latitude() -37.6806 Você também pode gerar Json para seus testes Write ##class(cosFaker.JSON).GetDataJSONFromJSON("{ip:'ipv4',created_at:'date.backward 40',login:'username', text: 'words 3'}") {     "created_at":"2019-03-08",     "ip":"95.226.124.187",     "login":"john46",     "text":"temporibus fugit deserunt" }   Aqui está uma lista completa das classes e métodos do **cosFaker**: * **cosFaker.Address** * StreetSuffix * StreetPrefix * PostCode * StreetName * Latitude * _Output:_ -54.7274 * Longitude * _Output:_ -43.9504 * Capital( Location = “” ) * State( FullName = 0 ) * City( State = “” ) * Country( Abrev = 0 ) * SecondaryAddress * BuildingNumber * **cosFaker.App** * FunctionName( Group= “”, Separator = “” ) * AppAction( Group= “” ) * AppType * **cosFaker.Coffee** * BlendName * _Output:_ Cascara Cake * Variety * _Output:_ Mundo Novo * Notes * _Output:_ crisp, slick, nutella, potato defect!, red apple * Origin * _Output:_ Rulindo, Rwanda * **cosFaker.Color** * Hexadecimal * _Output:_ #A50BD7 * RGB * _Output:_ 189,180,195 * Name * **cosFaker.Commerce** * ProductName * Product * PromotionCode * Color * Department * Price( Min = 0, Max = 1000, Dec = 2, Symbol = “” ) * _Output:_ 556.88 * CNPJ( Pretty = 1 ) * CNPJ is the Brazilian National Registry of Legal Entities * _Output:_ 44.383.315/0001-30 * **cosFaker.Company** * Name * Profession * Industry * **cosFaker.Dates** * Forward( Days = 365, Format = 3 ) * Backward( Days = 365, Format = 3 ) * **cosFaker.DragonBall** * Character * _Output:_ Gogeta * **cosFaker.File** * Extension * _Output:_ txt * MimeType * _Output:_ application/font-woff * Filename( Dir = “”, Name = “”, Ext = “”, DirectorySeparator = “/” ) * _Output:_ repellat.architecto.aut/aliquid.gif * **cosFaker.Finance** * Amount( Min = 0, Max = 10000, Dec = 2, Separator= “,”, Symbol = “” ) * _Output:_ 3949,18 * CreditCard( Type = “” ) * _Output:_ 3476-581511-6349 * BitcoinAddress( Min = 24, Max = 34 ) * _Output:_ 1WoR6fYvsE8gNXkBkeXvNqGECPUZ * **cosFaker.Game** * MortalKombat * _Output:_ Raiden * StreetFighter * _Output:_ Akuma * Card( Abrev = 0 ) * _Output:_ 5 of Diamonds * **cosFaker.Internet** * UserName( FirstName = “”, LastName = “” ) * Email( FirstName = “”, LastName = “”, Provider = “” ) * Protocol * _Output:_ http * DomainWord * DomainName * Url * Avatar( Size = “” ) * _Output:_ http://www.avatarpro.biz/avatar?s=150 * Slug( Words = “”, Glue = “” ) * IPV4 * _Output:_ 226.7.213.228 * IPV6 * _Output:_ 0532:0b70:35f6:00fd:041f:5655:74c8:83fe * MAC * _Output:_ 73:B0:82:D0:BC:70 * **cosFaker.JSON** * GetDataOBJFromJSON( Json = “” //  String de modelo JSON para criar dados ) * _Parameter Example_: "{dates:'5 date'}" * _Output_: {"dates":["2019-02-19","2019-12-21","2018-07-02","2017-05-25","2016-08-14"]} * **cosFaker.Job** * Title * Field * Skills * **cosFaker.Lorem** * Word * Words( Num = “” ) * Sentence( WordCount = “”, Min = 3, Max = 10 ) * _Output:_ Sapiente et accusamus reiciendis iure qui est. * Sentences( SentenceCount = “”, Separator = “” ) * Paragraph( SentenceCount = “” ) * Paragraphs( ParagraphCount = “”, Separator = “” ) * Lines( LineCount = “” ) * Text( Times = 1 ) * Hipster( ParagraphCount = “”, Separator = “” ) * **cosFaker.Name** * FirstName( Gender = “” ) * LastName * FullName( Gender = “” ) * Suffix * **cosFaker.Person** * cpf( Pretty = 1 ) * CPF is the Brazilian Social Security Number * _Output:_ 469.655.208-09 * **cosFaker.Phone** * PhoneNumber( Area = 1 ) * _Output:_ (36) 9560-9757 * CellPhone( Area = 1 ) * _Output:_ (77) 94497-9538 * AreaCode * _Output:_ 17 * **cosFaker.Pokemon** * Pokemon( EvolvesFrom = “” ) * _Output:_ Kingdra * **cosFaker.StarWars** * Characters * _Output:_ Darth Vader * Droids * _Output:_ C-3PO * Planets * _Output:_ Takodana * Quotes * _Output:_ Only at the end do you realize the power of the Dark Side. * Species * _Output:_ Hutt * Vehicles * _Output:_ ATT Battle Tank * WookieWords * _Output:_ nng * WookieSentence( SentenceCount = “” ) * _Output:_ ruh ga ru hnn-rowr mumwa ru ru mumwa. * **cosFaker.UFC** * Category * _Output:_ Middleweight * Fighter( Category = “”, Country = “”, WithISOCountry = 0 ) * _Output:_ Dmitry Poberezhets * Featherweight( Country = “” ) * _Output:_ Yair Rodriguez * Middleweight( Country = “” ) * _Output:_ Elias Theodorou * Welterweight( Country = “” ) * _Output:_ Charlie Ward * Lightweight( Country = “” ) * _Output:_ Tae Hyun Bang * Bantamweight( Country = “” ) * _Output:_ Alejandro Pérez * Flyweight( Country = “” ) * _Output:_ Ben Nguyen * Heavyweight( Country = “” ) * _Output:_ Francis Ngannou * LightHeavyweight( Country = “” ) * _Output:_ Paul Craig * Nickname( Fighter = “” ) * _Output:_ Abacus Vamos criar uma classe para o usuário com um método que retorna seu nome de usuário, que será FirstName concatenado com LastName. Class Production.User Extends %RegisteredObject { Property FirstName As %String; Property LastName As %String; Method Username() As %String { } }   Class TDD.User Extends %UnitTest.TestCase { Method TestUsername() { Set firstName = ##class(cosFaker.Name).FirstName(), lastName = ##class(cosFaker.Name).LastName(), user = ##class(Production.User).%New(), user.FirstName = firstName, user.LastName = lastName Do $$$AssertEquals(user.Username(), firstName _ "." _ lastName) } }    Refatorando: Class Production.User Extends %RegisteredObject { Property FirstName As %String; Property LastName As %String; Method Username() As %String { Quit ..FirstName _ "." _ ..LastName } }    Agora vamos adicionar uma data de expiração da conta e validá-la. Class Production.User Extends %RegisteredObject { Property FirstName As %String; Property LastName As %String; Property AccountExpires As %Date; Method Username() As %String { Quit ..FirstName _ "." _ ..LastName } Method Expired() As %Boolean { } } Class TDD.User Extends %UnitTest.TestCase { Method TestUsername() { Set firstName = ##class(cosFaker.Name).FirstName(), lastName = ##class(cosFaker.Name).LastName(), user = ##class(Production.User).%New(), user.FirstName = firstName, user.LastName = lastName Do $$$AssertEquals(user.Username(), firstName _ "." _ lastName) } Method TestWhenIsNotExpired() As %Status { Set user = ##class(Production.User).%New(), user.AccountExpires = ##class(cosFaker.Dates).Forward(40) Do $$$AssertNotTrue(user.Expired()) } }    Refatorando: Method Expired() As %Boolean { Quit ($system.SQL.DATEDIFF("dd", ..AccountExpires, +$Horolog) > 0) }    Agora vamos testar quando a conta expirou: Method TestWhenIsExpired() As %Status { Set user = ##class(Production.User).%New(), user.AccountExpires = ##class(cosFaker.Dates).Backward(40) Do $$$AssertTrue(user.Expired()) }    E tudo está verde... Eu sei que esses são exemplos bobos, mas dessa forma você verá a simplicidade não apenas no código, mas também no design da classe.   #### Conclusão Neste artigo, você aprendeu um pouco sobre Desenvolvimento Guiado por Testes e como usar a classe %UnitTest. Também cobrimos o cosFaker e como gerar dados falsos para seus testes. Há muito mais para aprender sobre testes e TDD, como usar essas práticas com código legado, testes de integração, testes de aceitação (ATDD), bdd, etc...  Se você quiser saber mais sobre isso, recomendo fortemente 2 livros:   [Test Driven Development Teste e design no mundo real com Ruby - Mauricio Aniche](https://www.amazon.com/Test-driven-development-Teste-design-Portuguese-ebook/dp/B01B6MSVBK/ref=sr_1_3?qid=1553909895&refinements=p_27%3AMauricio+Aniche&s=digital-text&sr=1-3&text=Mauricio+Aniche), realmente não sei se este livro tem versão em inglês. Existem edições para Java, C #, Ruby e PHP. Este livro me surpreendeu com sua grandiosidade. E, claro, o livro de Kent Beck [Test Driven Development by Example](https://www.amazon.com.br/Test-Driven-Development-Kent-Beck/dp/0321146530/ref=pd_sbs_14_2/131-5080621-0921627?_encoding=UTF8&pd_rd_i=0321146530&pd_rd_r=23604a58-528d-11e9-8a77-f188713467c0&pd_rd_w=TSR2y&pd_rd_wg=JBqE6&pf_rd_p=80c6065d-57d3-41bf-b15e-ee01dd80424f&pf_rd_r=CJ3QPX0H0P6H0EMNFZYJ&psc=1&refRID=CJ3QPX0H0P6H0EMNFZYJ) Sinta-se à vontade para deixar comentários ou perguntas. Isso é tudo, pessoal Parabéns @Henry.HamonPereira pelo excelente artigo!

Este projeto é um experimento em usar as APIs da OpenAI para responder prompts de usuários no domínio de saúde usando recursos FHIR e codificação em Python. ## Ideia do projeto IA generativas, como os modelos de LLM disponíveis na [OpenAI](https://platform.openai.com/docs/models), vem demonstrando impressionante capacidade para compreender e responder à questões de alto nível. Elas podem inclusive [usar linguagens de programação para criar códigos baseado em instruções contidas nos prompts](https://platform.openai.com/examples?category=code) - e tenho que confessar que a ideia de ter meu trabalho automatizado me causa um pouco de ansiedade. Mas pelo o que tenho visto até agora, parece que isso é algo sobre o qual as pessoas serão obrigadas a se acostumar, gostando ou não. Então, decidi fazer alguns experimentos. A ideia principal por traz desse projeto veio quando li [este artigo](https://the-decoder.com/chatgpt-programs-ar-app-using-only-natural-language-chatarkit/) sobre o [projeto ChatARKit](https://github.com/trzy/ChatARKit). Este projeto usa as APIs da OpenAI para interpretar comandos de voz para renderizar objetos 3D em vídeos exibidos em smartphones - um projeto muito interessante. E parece que este é um assunto de interesse, já que encontrei um [artigo recente](https://dl.acm.org/doi/pdf/10.1145/3581791.3597296) seguindo a mesma ideia. O que mais me deixou curioso sobre este artigo foi o uso do ChatGPT para **programar** uma aplicação de AR. Como o repositório do github está publicamente disponível, procurei nele e achei [como o autor usou o ChatGPT para gerar código](https://github.com/trzy/ChatARKit/blob/master/iOS/ChatARKit/ChatARKit/Engine/ChatGPT.swift). Depois, descobri que este tipo de técnica é chamada de *engenharia de prompt* - [aqui está um artigo da Wikipedia sobre este assunto](https://en.wikipedia.org/wiki/Prompt_engineering), ou então estes dois outros mais práticos: [1](https://microsoft.github.io/prompt-engineering/) e [2](https://learn.microsoft.com/en-us/azure/cognitive-services/openai/concepts/advanced-prompt-engineering?pivots=programming-language-chat-completions). Assim, pensei - e se eu tentasse algo similar, mas usando FHIR e Python? Isto foi o que veio à mente: Fig.1 - Ideia básica do projeto Seus principais elementos são: - Um módulo para tratar da engenharia de prompt, o qual irá instruir o modelo de IA usar FHIR e Python - Um módulo de integração com as APIs da OpenAI - Um interpretador Python para executar o código gerado - Um servidor FHIR para responder às consultas geradas pelo modelo de IA A ideia básica é usar a [API Completion da OpenAI](https://platform.openai.com/docs/api-reference/completions) para solicitar à IA dividir o prompt do usuário como um conjunto de consultas FHIR. Então, o modelo de IA cria um script Python para manipular os recursos FHIR retornados pelo servidor FHIR no InterSystems IRIS for Health. Se este simples esquema funcionar, usuários poderiam obter respostas à perguntas as quais ainda não são suportadas pelo modelo analítico das aplicações. Posteriormente, estas questões respondidas pelo modelo de IA, poderiam ser analisadas de forma a descobrir novas necessidades dos usuários. Outra vantagem deste esquema é o fato de que não há necessidade de exportar dados e esquemas para APIs externas. Por exemplo, perguntas sobre pacientes podem ser realizadas sem a necessidade de enviar dados desses pacientes ou esquemas do banco de dados para um servidor de IA. Como o modelo de AI usa somente elementos publicamente disponíveis - FHIR e Python nesse caso, não há necessidade de publicação de dados internos. No entanto, este mesmo esquema também nos remete à algumas dúvidas, tais como: - Como guiar o modelo de IA à usar FHIR e Python de acordo com as necessidades dos usuários? - As respostas geradas pelo modelo de IA são corretas? - Como lidar com problemas de segurança que a execução de código Python gerado externamente? Desta forma, de forma a construir algum suporte à essas dúvidas, realizei algumas alterações sobre o esquema pensado inicialmente: Fig.2 - Ideia depois de refinamento Agora, alguns novos elementos foram adicionados: - Um analisador de código Python para localizar problemas de segurança - Um módulo para registro de eventos (logs) para análise posterior. - Uma API REST para futuras integrações Assim, este projeto tem por objetivo ser uma prova de conceito o qual pode suportar experimentos para obter informações para tentar responder às questões como as propostas anteriormente. Nas próximas seções, você verá como usar o projeto, alguns resultados obtidos tentando responder às questões mencionadas acima e, algumas conclusões. Espero que você goste do projeto e o julgue útil. E sua colaboração com o projeto é mais que bem vinda! ## Usando o projeto Para usar o projeto, abra um terminal IRIS e execute o seguinte: ```objectscript ZN "USER" Do ##class(fhirgenerativeai.FHIRGenerativeAIService).RunInTerminal("") ``` Por exemplo, as seguintes questões foram usadas para testar o projeto: 1. How many patients are in the dataset? 2. What is the average age of patients? 3. Give me all conditions (code and name) removing duplications. Present the result in a table format. (Don't use pandas) 4. How many patients has the condition viral sinusitis (code 444814009)? 5. What is the prevalence of viral sinusitis (code 444814009) in the patient population? For patients with the same condition multiple times, consider just one hit to your calculations. 6. Among patients with viral sinusitis (code 444814009), what is the distribution of gender groups? Você encontra exemplos de saídas para essas questões [aqui](https://github.com/jrpereirajr/iris-fhir-generative-ai/blob/master/misc/tests-accuacy). > OBS: mantive as questões em inglês para caso você tente usa-las no projeto, os resultados sejam o mais parecido possível. Mas nada impede de você tentar traduzi-las antes de enviar para a API da OpenAI. > Por favor, observe que ao tentar repetir essas perguntas em seu sistema as respostas podem variar, mesmo para as mesmas perguntas. Isso se deve à natureza estocástica dos modelos de LLM. Estas questões foram sugeridas pelo ChatGPT. Foi solicitado que tais questões fossem criadas de uma forma na qual o nível de complexidade fosse sendo aumentado. Com exceção da terceira questão, que foi elaborada pelo autor. ## Engenharia de prompt O prompt usado pelo projeto pode ser encontrado [aqui](https://github.com/jrpereirajr/iris-fhir-generative-ai/blob/master/src/fhirgenerativeai/PromptService.cls) no método `GetSystemTemplate()`. Ele segue os princípios de engenharia de prompt onde, primeiro é atribuído um papel ao modelo de IA, e após isso, uma série de restrições e instruções. O objetivo de cada uma de suas seções estão comentadas, assim é possível entender como o prompt funciona. Observe o uso de um tipo de definição de interface, quando o modelo é instruído à assumir a existência de uma função chamada `CallFHIR()` para interagir com FHIR, ao invés de deixar o modelo declarar funções para tal. Isto foi inspirado pelo projeto ChatARKit, onde o autor define um conjunto de funções que abstraem a complexidade de uso de uma biblioteca de AR. Aqui, usei esta técnica para evitar que o modelo crie código para realizar chamadas HTTP de forma direta. Um achado interessante aqui foi sobre forçar o modelo de IA à retornar sua resposta em formato XML. Como é esperado que um código Python seja retornado, formatei-o em XML para uso do bloco CDATA. Apesar de ter sido claro no prompt para que a resposta também seja no formato XML, o modelo de IA só passou a seguir à esta instrução após também enviar o prompt do usuário formato em XML. É possível verifica isso no método `FormatUserPrompt()` na mesma classe referenciada acima. ## Analisador de código Python Este módulo usa a [biblioteca bandit](https://bandit.readthedocs.io/en/latest/) para procurar por problemas de segurança no código Python gerado. Esta biblioteca gera a AST do programa Python e o testa com relação à problemas de segurança comuns. Os tipos de problemas detectados estão nos seguintes links: - [Test plugins](https://bandit.readthedocs.io/en/latest/plugins/index.html#complete-test-plugin-listing) - [Calls blacklist](https://bandit.readthedocs.io/en/latest/blacklists/blacklist_calls.html) - [Imports blacklist](https://bandit.readthedocs.io/en/latest/blacklists/blacklist_imports.html) Cada código Python retornado pelo modelo de IA é testado para verificar se há problemas de segurança. Caso algo esteja errado, a execução é cancelada e um evento de erro é registrado. ## Registro de eventos Todos os eventos do sistema são registrados para análise posterior na tabela [LogTable](https://github.com/jrpereirajr/iris-fhir-generative-ai/blob/master/src/fhirgenerativeai/LogTable.cls). Cada execução para responder à uma pergunta possui em ID de sessão. Este ID pode ser encontrado na coluna 'SessionID' na tabela e usado para recuperar todos os eventos associados a ele, passando-o para o método `RunInTerminal("", )`. Por exemplo: ```objectscript Do ##class(fhirgenerativeai.FHIRGenerativeAIService).RunInTerminal("", "asdfghjk12345678") ``` Também é possível recuperar todos os eventos usando este SQL: ```sql SELECT * FROM fhirgenerativeai.LogTable order by id desc ``` ## Testes Alguns testes foram executados para conseguir informações para medir o desempenho do modelo de IA. Cada testes foi repetido 15 vezes e suas saídas estão armazenadas [neste](https://github.com/jrpereirajr/iris-fhir-generative-ai/blob/master/misc/tests-accuacy) e [neste](https://github.com/jrpereirajr/iris-fhir-generative-ai/blob/master/misc/tests-security) diretórios. > Por favor, observe que ao tentar repetir essas perguntas em seu sistema as respostas podem variar, mesmo para as mesmas perguntas. Isso se deve à natureza estocástica dos modelos de LLM. ### Taxa de acertos Nos testes da questão número 1, foram obtidos `14 resultados 6`, e `1 erro`. O valor correto é `6`. Então, houve `100%` de acertos, mas um percentual de falhas de execução de `6%`. SQL usado para validar os resultados do teste para a questão número 1: ```sql SELECT count(*) FROM HSFHIR_X0001_S.Patient ``` Nos testes da questão número 2, foram obtidos `3 resultados 52`, `6 resultados 52.5` e `6 erros`. O valor correto - considerando idades com valores decimais, é `52.5`. Desta forma, considerei ambos os valores corretos já que essa pequena diferença de valores seja provavelmente devido à ambiguidades no prompt - ele não menciona nada sobre permitir ou não idades com valores decimais. Assim, houve `100%` de acerto, mas com uma taxa de erros de execução de `40%`. SQL usado para validar os resultados do teste para a questão número 2: ```sql SELECT birthdate, DATEDIFF(yy,birthdate,current_date), avg(DATEDIFF(yy,birthdate,current_date)) FROM HSFHIR_X0001_S.Patient ``` Nos testes da questão número 3, foram obtidos `3 erros` e `12 tabelas com 23 linhas`. Os valores das tabelas não ficaram nas mesmas posições e formato, porém novamente atribuí esse comportamento à limitações no prompt. Desta forma, houve `100%` de acerto, porém com uma taxa de falha de execução de `20%`. SQL usado para validar os resultados do teste para a questão número 3: ```sql SELECT code, count(*) FROM HSFHIR_X0001_S.Condition group by code ``` Nos testes da questão número 4, foram obtidos `2 erros`, `12 resultados 7` e `1 resultado 4`. O valor correto é `4`. Então, foram `7%` acertos, e uma taxa de erros de execução de `13%`. SQL usado para validar os resultados do teste para a questão número 4: ```sql SELECT p.Key patient, count(c._id) qtde_conditions, list(c.code) conditions FROM HSFHIR_X0001_S.Patient p join HSFHIR_X0001_S.Condition c on c.patient = p.key where code like '%444814009%' group by p.Key ``` Nos testes da questão número 5, foram obtidos `11 erros`, `3 resultados 4` e `1 resultado 0.6`. O valor correto é `4`. Então, houve `75%` de acertos, e uma taxa de erros de execução de `73%`. O SQL usado para validar os resultados da questão número 5 foi o mesmo usado na questão número 4. Nos testes da questão número 6, foram obtidos `12 erros` e `3 resultados {female: 4, male: 2, other: 0}`. O valor correto é `{female: 3, male: 1, other: 0}`. Desta forma, houve `0%` de acertos, e uma taxa de erros de execução de `80%`. SQL usado para validar os resultados do teste para a questão número 6: ```sql SELECT p.gender, count(distinct p._id) qty_patients, list(p.key) patients, list(c.code) conditions FROM HSFHIR_X0001_S.Patient p join HSFHIR_X0001_S.Condition c on c.patient = p.key where code like '%444814009%' group by p.gender ``` Resumindo os resultados: | Número do teste | Taxa de acertos| Taca de erros de execução| |-----------------|----------------|--------------------------| | 1 | 100% | 6% | | 2 | 100% | 40% | | 3 | 100% | 20% | | 4 | 7% | 13% | | 5 | 75 % | 73% | | 6 | 0% | 80% | ### Segurança Como se pode observar nos códigos gerados no [diretório de testes](https://github.com/jrpereirajr/iris-fhir-generative-ai/blob/master/misc/tests-accuacy), aparentemente nenhum problema de segurança foi gerado pelo modelo de IA - e esse foi o mesmo resultado que o analisador de código encontrou, nenhum problema de segurança. Então, de forma a testar se o analisador de código era capaz de detectar problemas de segurança, o [módulo que executa os códigos Python](https://github.com/jrpereirajr/iris-fhir-generative-ai/blob/master/src/fhirgenerativeai/PythonService.cls) tem uma propriedade chamada `CodeInjection` , onde códigos maliciosos podem ser injetados para serem testados. Desta forma, os seguintes códigos maliciosos foram injetados para o teste de segurança: 1. Teste de segurança número 1: ```python print(eval("os.chmod('%s', 0o777)" % 'test.txt')) ``` Este código tenta acessar o sistema de arquivos do SO e alterar as permissões de um arquivo. Isto é claramente um código não esperado para o propósito do projeto, assim tendo que ser bloqueado. 2. Teste de segurança número 2: ```python import requests url = "https://postman-echo.com/get" params = {"arg": "value"} response = requests.get(url, params=params) data = response.json() print(data) ``` Este código tenta realizar uma requisição HTTP para um endereço externo - uma API do Postman neste caso. Se o código for executado, informações locais poderiam ser facilmente vazadas. Como pode ser observado no [diretório para os testes de segurança](https://github.com/jrpereirajr/iris-fhir-generative-ai/blob/master/misc/tests-security), o analisador de códigos foi bem sucedido em encontrar os problemas de segurança. ## Conclusões No que diz respeito à taxa de acertos, o modelo de IA obteve resultados corretos para as questões de baixa complexidade, mas começou a falhar conforme essa complexidade aumentou. O mesmo foi observado para taxa de falhas na execução. Assim, quanto mais complexas são as questões, mais o modelo de IA gera código com falha de execução e com maior probabilidade de levar a resultados com valores incorretos. Isto significa que melhorias devem ser realizadas no prompt. Por exemplo, no [código da questão 6](https://github.com/jrpereirajr/iris-fhir-generative-ai/blob/master/misc/tests-accuacy/6/1688265739062.txt), o erro foi pesquisar apenas os recursos Patient e ignorar os códigos dos recursos Conditions associados. Este tipo de análise é necessária para guiar as mudanças necessárias no prompt. No geral, o desempenho do modelo de IA nos testes mostra que ainda é necessário melhorias antes de que este seja considerado apto à responder perguntas analíticas. Isto é devido à natureza estocástica dos modelos de IA. Quero dizer, no projeto ChartARKit citado anteriormente, se o modelo de IA renderizar um objeto 3D não exatamente no lugar requisitado mas próximo a ele, provavelmente o usuário não irá ligar muito. Infelizmente, o mesmo não pode ser dito para perguntas analíticas, nesse caso as respostas devem ser exatas. Entretanto, é importante ressaltar que não estou dizendo que os modelos de IA são incapazes de realizarem tal tarefa. O que estou dizendo é que a maneira como o modelo de IA foi utilizado nesse projeto precisa de melhorias. Importante também notar que este projeto não usou técnicas mais avançadas de IAs generativas, como [Langchain](https://python.langchain.com/docs/get_started/introduction.html) e [AutoGPT](https://autogpt.net/autogpt-installation-and-features/). Aqui um abordagem mais "pura" foi utilizada; talvez o uso ferramentas mais sofisticadas podem levar a resultados melhores. Com relação à segurança, o analisador de código foi capaz de detectar todos os problemas de segurança testados. Entretanto, isto não significa que o código gerado pelo modelo de IA é 100% seguro. Além disso, permitir a execução de código Python gerado externamente pode ser perigoso, sem sobra de dúvidas. Nem mesmo é possível afirmar com 100% de segurança que o sistema que está entregando o código Python é realmente o servidor da OpenAI... Uma melhor saída para evitar problemas de segurança poderia ser o uso de outra linguagem de programação menos poderosa que Python, ou até mesmo criar uma "linguagem" própria e solicitar ao modelo de IA que a use, como pode ser visto [neste exemplo simples](https://platform.openai.com/examples/default-text-to-command). Finalmente, é importante observar que aspectos como desempenho de execução de código, não foram considerados nesse projeto e provavelmente seria também um bom assunto para trabalhos futuros. Assim, espero que você tenha achado esse projeto interessante e útil. >**Aviso: Este é um projeto experimental. Ele envia dados para APIs da OpenAI e executa código gerado pelo modelo de IA no seu sistema. Então, não o use sobre dados sensíveis e/ou sistemas em produção. Observe também que chamadas para APIs da OpenAI são cobradas. Use este projeto sobre risco próprio. Ele não é um projeto pronto para ser usado em produção.** muito bom!!! parabéns!!!

Olá Comunidade, Gostaria de apresentar meu último pacote OpenAPI-Suite. Este é um conjunto de ferramentas para gerar código ObjectScript a partir de uma especificação OpenAPI versão 3.0.. IEm resumo, estes pacotes permitem: Gerar classes de servidor. É bem parecido com o código gerado por ^%REST mas o valor adicionado é o suporte à versão 3.0. Gerar classes de cliente HTTP. Gerar classes de produção de cliente (business services, business operation, business process, Ens.Request, Ens.Response). Uma interface web para gerar e baixar o código ou gerar e compilar diretamente no servidor. Converter especificações das versões 1.x, 2.x para a versão 3.0. Visão Geral O OpenAPI Suite é dividido em vários pacotes e utiliza diferentes bibliotecas da comunidade de desenvolvedores e também serviços REST públicos. Você pode ver no esquema abaixo todos os pacotes que foram desenvolvidos, e as bibliotecas e serviços web utilizados: Observação: Em caso de problemas ao usar serviços REST públicos, é possível iniciar uma instância Docker do serviço de conversão e validação. O que cada pacote faz? O OpenAPI Suite foi projetado em diferentes pacotes para facilitar a manutenção, melhoria e extensão futura. Cada pacote tem um papel. Vamos dar uma olhada! openapi-common-lib Isto contém todo o código comum aos outros pacotes. Por exemplo openapi-client-gen e openapi-server-gen aceitam a seguinte entrada para uma especificação OpenAPI: URL Caminho de arquivo %Stream.Object %DynamicObject Formato YAML Formato JSON OpenAPI versão1.x, 2.x, 3.0.x. No entanto, apenas uma especificação 3.0.x em um %DynamicObject pode ser processada. O código para a transformação está localizado neste pacote. Ele também contém várias utilidades. swagger-converter-cli É uma dependência do openapi-common-lib. Este é um cliente HTTP que utiliza o serviço REST públicoconverter.swagger.iopara converter OpenAPI versão 1.x ou 2.x para a versão 3.0. swagger-validator-cli É também uma dependência do openapi-common-lib, mesmo que seu nome seja "validator", ele não é usado para validar a especificação. O converter.swagger.iofornece o serviço "parse" que permite simplificar a estrutura de uma especificação OpenAPI. Por exemplo: criar uma definição para uma "nested object definition" e substituí-la por um "$ref". Isso reduz o número de casos a serem tratados no algoritmo de geração de código. openapi-client-gen Este pacote é dedicado à geração de código do lado do cliente para ajudar os desenvolvedores a consumir serviços REST. Ele inclui um cliente HTTP simples ou um cliente de Produção(business services, process, operation, Production classes). Originalmente criado para suportar OpenAPI 2.x, foi completamente refatorado para suportar a versão 3.x. openapi-server-gen O oposto do openapi-client-gen, é dedicado à geração de código do lado do servidor. Não há interesse na versão 2.0 da especificação porque o ^%RESTexiste, mas o objetivo deste pacote é o suporte à versão 3.0. openapi-suite Ele reúne todos os pacotes acima e fornece uma API REST para: Gerar o código e compilar o código na instância IRIS. Gerar código sem compilar para download apenas. Uma interface web também é fornecida para consumir esta API REST e, assim, explorar as funcionalidades do OpenAPI Suite. E as bibliotecas? Aqui estão algumas das bibliotecas existentes no DC que foram úteis neste desenvolvimento: objectscript-openapi-definition Uma biblioteca útil para gerar classes de modelo a partir de uma especificação OpenAPI. Esta é uma parte muito importante deste projeto e eu também sou um contribuidor. ssl-client Permite criar configurações SSL. Usado principalmente para criar um nome de configuração "DefaultSSL" para requisições HTTPS. yaml-utils No caso de especificação em formato YAML, esta biblioteca é usada para converter para o formato JSON. Essencial neste projeto. A propósito, foi desenvolvida inicialmente para testar a especificação YAML com a versão 1 do openapi-client-gen. io-redirect Esta é uma das minhas bibliotecas. Ela permite redirecionar a saída de "write" para um stream, arquivo, global ou variável string. É usada pelo serviço REST para manter um rastreamento dos logs. É inspirada nesta postagem da comunidade. Instalação IPM Para instalar a suíte, seu melhor amigo é oIPM (zpm). Existem muitos pacotes e dependências, e usar o IPM é definitivamente conveniente. zpm "install openapi-suite" ; opcional ; zpm "install swagger-ui" Instalação Docker Não há nada de especial, este projeto utiliza o intersystems-iris-dev-template. git clone git@github.com:lscalese/openapi-suite.git cd openapi-suite docker-compose up -d Se você tiver um erro ao iniciar o Iris, talvez seja um problema de permissão no arquivo iris-main.log. Você pode tentar: touch iris-main.log && chmod 777 iris-main.log Observação: Adicionar permissão de leitura e escrita (RW) para o usuário irisowner deve ser suficiente. Como Usar O OpenAPI-Suite fornece uma interface web para "Gerar e baixar" ou "Gerar e instalar" código. A interface está disponível em http://localhost:52796/openapisuite/ui/index.csp (*adapte com o seu número de porta, se necessário). É muito simples, preencha o formulário: Nome do pacote da aplicação: este é o pacote usado para as classes geradas. Deve ser um nome de pacote inexistente. Selecione o que você deseja gerar: Cliente HTTP, Produção Cliente ou Servidor REST. Selecione o namespace onde o código será gerado. Isso faz sentido apenas se você clicar em "Install On Server"; caso contrário, este campo será ignorado. Nome da Aplicação Web é opcional e está disponível apenas se você selecionar "Servidor REST" para gerar. Deixe vazio se você não quiser criar uma Aplicação Web relacionada à classe de despacho REST gerada. O campo Especificação OpenAPI pode ser uma URL apontando para a especificação ou uma cópia/cola da própria especificação (neste caso, a especificação deve estar em formato JSON). Se você clicar no botão "Download Only", o código será gerado e retornado em um arquivo XML, e então as classes serão excluídas do servidor. O namespace usado para armazenar temporariamente as classes geradas é o namespace onde o OpenAPI-Suite está instalado (por padrão IRISAPP se você usar uma instalação Docker). No entanto, se você clicar no botão "Install On Server", o código será gerado e compilado, e o servidor retornará uma mensagem JSON com o status da geração/compilação do código e também os logs. Por padrão, este recurso está desabilitado. Para habilitá-lo, basta abrir um terminal IRIS e: Set ^openapisuite.config("web","enable-install-onserver") = 1 Explore a API REST do OpenAPI-Suite O formulário CSP utiliza serviços REST disponíveis emhttp://localhost:52796/openapisuite. Abra o swagger-ui http://localhost:52796/swagger-ui/index.html e explore http://localhost:52796/openapisuite/_spec Este é o primeiro passo para criar uma aplicação front-end mais avançada com o framework Angular. Gere código programaticamente Claro, não é obrigatório usar a interface do usuário. Nesta seção, veremos como gerar o código programaticamente e como usar os serviços gerados. Todos os trechos de código também estão disponíveis na classe dc.openapi.suite.samples.PetStore. cliente HTTP Set features("simpleHttpClientOnly") = 1 Set sc = ##class(dc.openapi.client.Spec).generateApp("petstoreclient", "https://petstore3.swagger.io/api/v3/openapi.json", .features) O primeiro argumento é o pacote onde as classes serão geradas, portanto, certifique-se de passar um nome de pacote válido. O segundo argumento pode ser uma URL apontando para a especificação, um nome de arquivo, um stream ou um %DynamicObject. "features" é um array, atualmente apenas os seguintes subscritos estão disponíveis: simpleHttpClientOnly: se for 1, apenas um cliente HTTP simples será gerado; caso contrário, uma produção também será gerada (comportamento padrão). compile: se for 0, o código gerado não será compilado. Isso pode ser útil se você quiser gerar código apenas para fins de exportação. Por padrão, compile = 1. Abaixo está um exemplo de como usar o serviço "addPet" com o cliente HTTP recém-gerado: Set messageRequest = ##class(petstoreclient.requests.addPet).%New() Set messageRequest.%ContentType = "application/json" Do messageRequest.PetNewObject().%JSONImport({"id":456,"name":"Mittens","photoUrls":["https://static.wikia.nocookie.net/disney/images/c/cb/Profile_-_Mittens.jpg/revision/latest?cb=20200709180903"],"status":"available"}) Set httpClient = ##class(petstoreclient.HttpClient).%New("https://petstore3.swagger.io/api/v3","DefaultSSL") ; MessageResponse será uma instância de petstoreclient.responses.addPet Set sc = httpClient.addPet(messageRequest, .messageResponse) If $$$ISERR(sc) Do $SYSTEM.Status.DisplayError(sc) Quit sc Write !,"Http Status code : ", messageResponse.httpStatusCode,! Do messageResponse.Pet.%JSONExport() Click to show generated classes. Class petstoreclient.HttpClient Extends %RegisteredObject [ ProcedureBlock ] { Parameter SERVER = "https://petstore3.swagger.io/api/v3"; Parameter SSLCONFIGURATION = "DefaultSSL"; Property HttpRequest [ InitialExpression = {##class(%Net.HttpRequest).%New()} ]; Property SSLConfiguration As %String [ InitialExpression = {..#SSLCONFIGURATION} ]; Property Server As %String [ InitialExpression = {..#SERVER} ]; Property URLComponents [ MultiDimensional ]; Method %OnNew(Server As %String, SSLConfiguration As %String) As %Status { Set:$Data(Server) ..Server = Server Set:$Data(SSLConfiguration) ..SSLConfiguration = SSLConfiguration Quit ..InitializeHttpRequestObject() } Method InitializeHttpRequestObject() As %Status { Set ..HttpRequest = ##class(%Net.HttpRequest).%New() Do ##class(%Net.URLParser).Decompose(..Server, .components) Set:$Data(components("host"), host) ..HttpRequest.Server = host Set:$Data(components("port"), port) ..HttpRequest.Port = port Set:$$$LOWER($Get(components("scheme")))="https" ..HttpRequest.Https = $$$YES, ..HttpRequest.SSLConfiguration = ..SSLConfiguration Merge:$Data(components) ..URLComponents = components Quit $$$OK } /// Implementar operationId : addPet /// post /pet Method addPet(requestMessage As petstoreclient.requests.addPet, Output responseMessage As petstoreclient.responses.addPet = {##class(petstoreclient.responses.addPet).%New()}) As %Status { Set sc = $$$OK $$$QuitOnError(requestMessage.LoadHttpRequestObject(..HttpRequest)) $$$QuitOnError(..HttpRequest.Send("POST", $Get(..URLComponents("path")) _ requestMessage.%URL)) $$$QuitOnError(responseMessage.LoadFromResponse(..HttpRequest.HttpResponse, "addPet")) Quit sc } ... } Class petstoreclient.requests.addPet Extends %RegisteredObject [ ProcedureBlock ] { Parameter METHOD = "post"; Parameter URL = "/pet"; Property %Consume As %String; Property %ContentType As %String; Property %URL As %String [ InitialExpression = {..#URL} ]; /// Use essa propriedade para conteúdo do corpo com content-type = application/json.<br/> /// Use essa propriedade para conteúdo do corpo com content-type = application/xml.<br/> /// Use essa propriedade para conteúdo do corpo com content-type = application/x-www-form-urlencoded. Property Pet As petstoreclient.model.Pet; /// Carregue %Net.HttpRequest com esse objeto de propriedade Method LoadHttpRequestObject(ByRef httpRequest As %Net.HttpRequest) As %Status { Set sc = $$$OK Set httpRequest.ContentType = ..%ContentType Do httpRequest.SetHeader("accept", ..%Consume) If $Piece($$$LOWER(..%ContentType),";",1) = "application/json" Do ..Pet.%JSONExportToStream(httpRequest.EntityBody) If $Piece($$$LOWER(..%ContentType),";",1) = "application/xml" Do ..Pet.XMLExportToStream(httpRequest.EntityBody) If $Piece($$$LOWER(..%ContentType),";",1) = "application/x-www-form-urlencoded" { ; Para implementar. Não há código gerado neste caso. $$$ThrowStatus($$$ERROR($$$NotImplemented)) } Quit sc } } Class petstoreclient.responses.addPet Extends petstoreclient.responses.GenericResponse [ ProcedureBlock ] { /// http status code = 200 content-type = application/xml /// http status code = 200 content-type = application/json /// Property Pet As petstoreclient.model.Pet; /// Implementar operationId : addPet /// post /pet Method LoadFromResponse(httpResponse As %Net.HttpResponse, caller As %String = "") As %Status { Set sc = $$$OK Do ##super(httpResponse, caller) If $$$LOWER($Piece(httpResponse.ContentType,";",1))="application/xml",httpResponse.StatusCode = "200" { $$$ThrowStatus($$$ERROR($$$NotImplemented)) } If $$$LOWER($Piece(httpResponse.ContentType,";",1))="application/json",httpResponse.StatusCode = "200" { Set ..Pet = ##class(petstoreclient.model.Pet).%New() Do ..Pet.%JSONImport(httpResponse.Data) Return sc } Quit sc } } Produção de cliente HTTP Set sc = ##class(dc.openapi.client.Spec).generateApp("petstoreproduction", "https://petstore3.swagger.io/api/v3/openapi.json") O primeiro argumento é o nome do pacote. Se você testar a geração de código de um cliente HTTP simples e de uma produção de cliente, certifique-se de usar um nome de pacote diferente. O segundo e o terceiro seguem as mesmas regras do cliente HTTP. Antes de testar, inicie a produção através do portal de gerenciamento usando este comando: Do ##class(Ens.Director).StartProduction("petstoreproduction.Production") Abaixo está um exemplo de como usar o serviço "addPet", mas desta vez com a produção gerada: Set messageRequest = ##class(petstoreproduction.requests.addPet).%New() Set messageRequest.%ContentType = "application/json" Do messageRequest.PetNewObject().%JSONImport({"id":123,"name":"Kitty Galore","photoUrls":["https://www.tippett.com/wp-content/uploads/2017/01/ca2DC049.130.1264.jpg"],"status":"pending"}) ; MessageResponse será uma instâncoa de petstoreclient.responses.addPet Set sc = ##class(petstoreproduction.Utils).invokeHostSync("petstoreproduction.bp.SyncProcess", messageRequest, "petstoreproduction.bs.ProxyService", , .messageResponse) Write !, "Take a look in visual trace (management portal)" If $$$ISERR(sc) Do $SYSTEM.Status.DisplayError(sc) Write !,"Http Status code : ", messageResponse.httpStatusCode,! Do messageResponse.Pet.%JSONExport() Agora, você pode abrir o rastreamento visual para ver os detalhes: As classes geradas nos pacotes model, requests e responses são bem semelhantes ao código gerado para um cliente HTTP simples. As classes do pacote requests herdam de Ens.Request, e as classes do pacote responses herdam de Ens.Response. A implementação padrão da operação de negócio é muito simples, veja este trecho de código: Class petstoreproduction.bo.Operation Extends Ens.BusinessOperation [ ProcedureBlock ] { Parameter ADAPTER = "EnsLib.HTTP.OutboundAdapter"; Property Adapter As EnsLib.HTTP.OutboundAdapter; /// Implementar operationId : addPet /// post /pet Method addPet(requestMessage As petstoreproduction.requests.addPet, Output responseMessage As petstoreproduction.responses.addPet) As %Status { Set sc = $$$OK, pHttpRequestIn = ##class(%Net.HttpRequest).%New(), responseMessage = ##class(petstoreproduction.responses.addPet).%New() $$$QuitOnError(requestMessage.LoadHttpRequestObject(pHttpRequestIn)) $$$QuitOnError(..Adapter.SendFormDataArray(.pHttpResponse, "post", pHttpRequestIn, , , ..Adapter.URL_requestMessage.%URL)) $$$QuitOnError(responseMessage.LoadFromResponse(pHttpResponse, "addPet")) Quit sc } ... } } Serviço REST HTTP do lado do servidor Set sc = ##class(dc.openapi.server.ServerAppGenerator).Generate("petstoreserver", "https://petstore3.swagger.io/api/v3/openapi.json", "/petstore/api") O primeiro argumento é o nome do pacote para gerar as classes. O segundo segue as mesmas regras do cliente HTTP. O terceiro argumento não é obrigatório, mas se presente, uma aplicação web será criada com o nome fornecido (tenha cuidado ao fornecer um nome de aplicação web válido). A classe petstoreserver.disp (dispatch, despacho, %CSP.REST class) parece um código gerado por ^%REST, realizando muitas verificações para aceitar ou rejeitar a requisição e chamando a implementação do ClassMethod de serviço correspondente em petstoreserver.impl. A principal diferença é o argumento passado para o método de implementação, que é um objeto petstoreserver.requests. Exemplo: Class petstoreserver.disp Extends %CSP.REST [ ProcedureBlock ] { Parameter CHARSET = "utf-8"; Parameter CONVERTINPUTSTREAM = 1; Parameter IgnoreWrites = 1; Parameter SpecificationClass = "petstoreserver.Spec"; /// Processar request post /pet ClassMethod addPet() As %Status { Set sc = $$$OK Try{ Set acceptedMedia = $ListFromString("application/json,application/xml,application/x-www-form-urlencoded") If '$ListFind(acceptedMedia,$$$LOWER(%request.ContentType)) { Do ##class(%REST.Impl).%ReportRESTError(..#HTTP415UNSUPPORTEDMEDIATYPE,$$$ERROR($$$RESTContentType,%request.ContentType)) Quit } Do ##class(%REST.Impl).%SetContentType($Get(%request.CgiEnvs("HTTP_ACCEPT"))) If '##class(%REST.Impl).%CheckAccepts("application/xml,application/json") Do ##class(%REST.Impl).%ReportRESTError(..#HTTP406NOTACCEPTABLE,$$$ERROR($$$RESTBadAccepts)) Quit If '$isobject(%request.Content) Do ##class(%REST.Impl).%ReportRESTError(..#HTTP400BADREQUEST,$$$ERROR($$$RESTRequired,"body")) Quit Set requestMessage = ##class(petstoreserver.requests.addPet).%New() Do requestMessage.LoadFromRequest(%request) Set scValidateRequest = requestMessage.RequestValidate() If $$$ISERR(scValidateRequest) Do ##class(%REST.Impl).%ReportRESTError(..#HTTP400BADREQUEST,$$$ERROR(5001,"Invalid requestMessage object.")) Quit Set response = ##class(petstoreserver.impl).addPet(requestMessage) Do ##class(petstoreserver.impl).%WriteResponse(response) } Catch(ex) { Do ##class(%REST.Impl).%ReportRESTError(..#HTTP500INTERNALSERVERERROR,ex.AsStatus(),$parameter("petstoreserver.impl","ExposeServerExceptions")) } Quit sc } ... } Como você pode ver, a classe de despacho chama “LoadFromRequest” e “RequestValidate” antes de invocar o método de implementação. Esses métodos possuem uma implementação padrão, mas o gerador de código não consegue cobrir todos os casos. Atualmente, os casos mais comuns são tratados automaticamente como parâmetros em "query" (consulta), "headers" (cabeçalhos), "path" (caminho) e no corpo (body) com os tipos de conteúdo “application/json”, “application/octet-stream” ou “multipart/form-data”. O desenvolvedor precisa verificar a implementação para checar/completar se necessário (por padrão, o gerador de código define $$$ThrowStatus($$$ERROR($$$NotImplemented)) para casos não suportados). Exemplo de classe de requisição: Class petstoreserver.requests.addPet Extends %RegisteredObject [ ProcedureBlock ] { Parameter METHOD = "post"; Parameter URL = "/pet"; Property %Consume As %String; Property %ContentType As %String; Property %URL As %String [ InitialExpression = {..#URL} ]; /// Use essa propriedade para conteúdo de corpo com content-type = application/json.<br/> /// Use essa propriedade para conteúdo de corpo com content-type = application/xml.<br/> /// Use essa propriedade para conteúdo de corpo com content-type = application/x-www-form-urlencoded. Property Pet As petstoreserver.model.Pet; /// Carregue propriedades de objeto do objeto %CSP.Request. Method LoadFromRequest(request As %CSP.Request = {%request}) As %Status { Set sc = $$$OK Set ..%ContentType = $Piece(request.ContentType, ";", 1) If ..%ContentType = "application/json"{ Do ..PetNewObject().%JSONImport(request.Content) } If ..%ContentType = "application/xml" { ; A implementar. Não há geração de código ainda para este caso. $$$ThrowStatus($$$ERROR($$$NotImplemented)) } If ..%ContentType = "application/x-www-form-urlencoded" { ; A implementar. Não há geração de código ainda para este caso. $$$ThrowStatus($$$ERROR($$$NotImplemented)) } Quit sc } /// Carregue propriedades de objeto do objeto %CSP.Request. Method RequestValidate() As %Status { Set sc = $$$OK $$$QuitOnError(..%ValidateObject()) If ''$ListFind($ListFromString("application/json,application/xml,application/x-www-form-urlencoded"), ..%ContentType) { Quit:..Pet="" $$$ERROR(5659, "Pet") } If $IsObject(..Pet) $$$QuitOnError(..Pet.%ValidateObject()) Quit sc } } Assim como no uso de ^%REST, a classe "petstoreserver.impl" contém todos os métodos relacionados aos serviços que o desenvolvedor precisa implementar. Class petstoreserver.impl Extends %REST.Impl [ ProcedureBlock ] { Parameter ExposeServerExceptions = 1; /// Implementação do serviço para post /pet ClassMethod addPet(messageRequest As petstoreserver.requests.addPet) As %Status { ; Implemente seu serviço aqui ; Retorne {} $$$ThrowStatus($$$ERROR($$$NotImplemented)) } ... } Breve descrição dos pacotes gerados: Nome do Pacote \ Nome da Classe Tipo Descrição petstoreclient.model petstoreproduction.model Client-side e server-side Ele contém todos os modelos. Essas classes estendem %JSON.Adaptor para facilitar o carregamento de objetos a partir de JSON. Se uma produção for gerada, essas classes também estenderão %Persistent. petstoreclient.requests petstoreproduction.requests Client-side e server-side Objeto usado para inicializar facilmente %Net.HttpRequest. Existe uma classe por operação definida na especificação. Se a produção for gerada, essas classes estenderão Ens.Request. Nota: A implementação desta classe é diferente se for gerada para propósitos do lado do servidor ou do lado do cliente. No caso do lado do cliente, todas as classes contêm um método "LoadHttpRequestObject" permitindo carregar um "%Net.HttpRequest" a partir das propriedades desta classe. Se as classes forem geradas para propósitos do lado do servidor, cada classe contém um método "LoadFromRequest" para carregar a instância a partir do objeto "%request". petstoreclient.responses petstoreproduction.responses Client-side e server-side É o oposto de petstoreclient.requests. Ele permite manipular a resposta de um %Net.HttpRequest. Se a produção for gerada, essas classes estenderão Ens.Response. petstoreclient.HttpClient Client-side Contém todos os métodos para executar requisições HTTP; existe um método por operação definida na especificação OpenAPI. petstoreproduction. bo.Operation Client-side A classe de Operação possui um método por operação definida na especificação OpenAPI. petstoreproduction.bp Client-side Dois processos de negócio padrão são definidos: síncrono e assíncrono. petstoreproduction.bs Client-side Contém todos os serviços de negócio vazios para implementar. petstoreproduction.Production Client-side Configuração de produção. petstoreserver.disp Server-side Classe de despacho %CSP.REST. petstoreserver.Spec Server-side Esta classe contém a especificação OpenAPI em um bloco XData. petstoreserver.impl Server-side Ele contém todos os métodos vazios relacionados às operações definidas na especificação OpenAPI. Esta é a classe (que estende %REST.Impl) onde os desenvolvedores precisam implementar os serviços. Status de desenvolvimento O OpenAPI-Suite ainda é um produto muito novo e precisa ser mais testado e então aprimorado. O suporte ao OpenAPI 3 é parcial, mais possibilidades poderiam ser suportadas. Os testes foram realizados com a especificação públicahttps://petstore3.swagger.io/api/v3/openapi.json e outras duas relativamente simples. Obviamente, isso não é suficiente para cobrir todos os casos. Se você tiver alguma especificação para compartilhar, ficaria feliz em usá-las para meus testes. Acredito que a base do projeto é boa e ele pode evoluir facilmente, por exemplo, ser estendido para suportar AsyncAPI. Não hesite em deixar feedback. Espero que você goste desta aplicação e que ela mereça seu apoio para o concurso de ferramentas para desenvolvedores. Obrigado por ler.