{"id":20207796,"url":"https://github.com/exasol/udf-debugging-java","last_synced_at":"2025-03-03T10:14:59.669Z","repository":{"id":37979680,"uuid":"302605573","full_name":"exasol/udf-debugging-java","owner":"exasol","description":"Utilities for debugging, profiling and code coverage measure for UDFs.","archived":false,"fork":false,"pushed_at":"2025-02-12T11:34:36.000Z","size":152,"stargazers_count":1,"open_issues_count":0,"forks_count":1,"subscribers_count":8,"default_branch":"main","last_synced_at":"2025-02-12T12:30:28.314Z","etag":null,"topics":["code-coverage","debugging","exasol","exasol-integration","java","profiling","udf","user-defined-function","virtual-schema"],"latest_commit_sha":null,"homepage":"","language":"Java","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/exasol.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2020-10-09T10:15:59.000Z","updated_at":"2025-02-12T11:34:40.000Z","dependencies_parsed_at":"2024-11-14T05:32:33.608Z","dependency_job_id":"009b6c00-1925-40cf-8983-62a91852faff","html_url":"https://github.com/exasol/udf-debugging-java","commit_stats":null,"previous_names":[],"tags_count":21,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/exasol%2Fudf-debugging-java","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/exasol%2Fudf-debugging-java/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/exasol%2Fudf-debugging-java/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/exasol%2Fudf-debugging-java/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/exasol","download_url":"https://codeload.github.com/exasol/udf-debugging-java/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":241644559,"owners_count":19996179,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["code-coverage","debugging","exasol","exasol-integration","java","profiling","udf","user-defined-function","virtual-schema"],"created_at":"2024-11-14T05:32:20.711Z","updated_at":"2025-03-03T10:14:59.646Z","avatar_url":"https://github.com/exasol.png","language":"Java","funding_links":[],"categories":[],"sub_categories":[],"readme":"# UDF Debugging Tools for Java\n\n[![Build Status](https://github.com/exasol/udf-debugging-java/actions/workflows/ci-build.yml/badge.svg)](https://github.com/exasol/udf-debugging-java/actions/workflows/ci-build.yml)\n[![Maven Central \u0026ndash; udf-debugging-java](https://img.shields.io/maven-central/v/com.exasol/udf-debugging-java)](https://search.maven.org/artifact/com.exasol/udf-debugging-java)\n\n[![Quality Gate Status](https://sonarcloud.io/api/project_badges/measure?project=com.exasol%3Audf-debugging-java\u0026metric=alert_status)](https://sonarcloud.io/dashboard?id=com.exasol%3Audf-debugging-java)\n\n[![Security Rating](https://sonarcloud.io/api/project_badges/measure?project=com.exasol%3Audf-debugging-java\u0026metric=security_rating)](https://sonarcloud.io/dashboard?id=com.exasol%3Audf-debugging-java)\n[![Reliability Rating](https://sonarcloud.io/api/project_badges/measure?project=com.exasol%3Audf-debugging-java\u0026metric=reliability_rating)](https://sonarcloud.io/dashboard?id=com.exasol%3Audf-debugging-java)\n[![Maintainability Rating](https://sonarcloud.io/api/project_badges/measure?project=com.exasol%3Audf-debugging-java\u0026metric=sqale_rating)](https://sonarcloud.io/dashboard?id=com.exasol%3Audf-debugging-java)\n[![Technical Debt](https://sonarcloud.io/api/project_badges/measure?project=com.exasol%3Audf-debugging-java\u0026metric=sqale_index)](https://sonarcloud.io/dashboard?id=com.exasol%3Audf-debugging-java)\n\n[![Code Smells](https://sonarcloud.io/api/project_badges/measure?project=com.exasol%3Audf-debugging-java\u0026metric=code_smells)](https://sonarcloud.io/dashboard?id=com.exasol%3Audf-debugging-java)\n[![Coverage](https://sonarcloud.io/api/project_badges/measure?project=com.exasol%3Audf-debugging-java\u0026metric=coverage)](https://sonarcloud.io/dashboard?id=com.exasol%3Audf-debugging-java)\n[![Duplicated Lines (%)](https://sonarcloud.io/api/project_badges/measure?project=com.exasol%3Audf-debugging-java\u0026metric=duplicated_lines_density)](https://sonarcloud.io/dashboard?id=com.exasol%3Audf-debugging-java)\n[![Lines of Code](https://sonarcloud.io/api/project_badges/measure?project=com.exasol%3Audf-debugging-java\u0026metric=ncloc)](https://sonarcloud.io/dashboard?id=com.exasol%3Audf-debugging-java)\n\nThis repository contains tools for debugging UDFs.\n\n## Installation\n\nInstall as maven dependency. You can get the dependency declaration by clicking the maven badge above.\n\n## Typical Usage\n\nTypically, you use this package together with [test-db-builder-java](https://github.com/exasol/test-db-builder-java) and [exasol-testcontainers](https://github.com/exasol/exasol-testcontainers) as follows:\n\n```java\n\nprivate static final ExasolContainer\u003c?extends ExasolContainer\u003c?\u003e\u003e EXASOL=new ExasolContainer\u003c\u003e();\nfinal UdfTestSetup udfTestSetup=new UdfTestSetup(getTestHostIp(),EXASOL.getDefaultBucket());\nfinal ExasolObjectFactory testDbBuilder=new ExasolObjectFactory(EXASOL.createConnection(),\n        ExasolObjectConfiguration.builder().withJvmOptions(udfTestSetup.getJvmOptions()).build());\n```\n\n## Modules\n\nThis package contains multiple modules that you can enable on runtime by setting the corresponding system property to `true`. Typically, you do so by appending `-D\u003cPROPERTY_NAME\u003e=\"true\"` to your JVM call.\n\n### Debugging\n\nSystem property: `test.debug`\n\nThis module instructs the UDF JVMs to connect to a Java debugger listening on the default port 8000 on you machine, running the tests.\n\n### Code Coverage\n\nSystem property: `test.coverage`\n\nThis module installs a jacoco agent to the UDF JVM and receives the execution data using a TCP socket.\n\nThis module requires additional maven configuration. Use  [project-keeper](https://github.com/exasol/project-keeper-maven-plugin) module `udf_coverage` to verify it.\n\nPlease note that using a [JaCoCo agent](https://www.jacoco.org/jacoco/trunk/doc/agent.html) fails when running on Windows using a [Docker image](https://docs.docker.com/glossary/#container-image) in a Linux virtual machine, see  known issue [Failing Integration Tests on Windows](#known-issue:-failing-integration-tests-on-windows).\n\n### JProfiler\n\nSystem property: `test.jprofiler`\n\nThis module allows you to profile UDF runs using [JProfiler](https://www.ej-technologies.com/products/jprofiler/overview.html). For that it uploads the JProfiler archive to BucketFs and adds the agent to the UDF command.\n\nSince JProfiler uses a forward TCP connection you can only profile one UDF instance at once. Make sure that you don't start multiple parallel instances.\n\n#### Usage\n\n* Install JProfiler on your system\n* Download JProfiler for Linux without JRE as `.tar.gz` (Also choose the Linux version if you're on a different operating system!)\n* Now you've two options:\n    * Store it as `jprofiler.tar.gz` in your home directory\n    * Store it somewhere and pass `-DjProfilerAgent=\u003cpath to the archive.tar.gz\u003e` to each test run\n* Run your tests with `-Dtest.jprofiler=true`\n* Find out the IPv4 address of your Exasol DB (for docker use `docker inspect`)\n* Start JProfiler GUI\n* Connect to `\u003cEXASOL_IP\u003e:11002`\n    * The UDF execution will wait until you connect the profiler\n    * Ensure that the port is reachable from your system (for AWS instances you can use an SSH tunnel from inside JProfiler)\n\n### UDF Logs\n\nSystem property: `test.udf-logs`\n\nThis module redirects the STDOUT from UDFs to files on the test host.\n\nYou can find the logs in `target/udf-logs/`. For each incoming stream (UDF instance) this module creates one file and logs its name:\n\n```\nCreated log file for UDF output: target/udf-logs/udf-log-2023-07-05T10:49:09.316547Z-576983159368731727.log\n```\n\n## Known Issue: Failing Integration Tests on Windows\n\nPlease note that integration tests fail when running on Windows using a Docker image in a Linux virtual machine due to JaCoCo agent obtaining the [Code Coverage](#code-coverage) in the UDF.\n\nSteps to reproduce\n\n* Use a virtual schema, e.g. https://github.com/exasol/mysql-virtual-schema\n* with Maven command `mvn clean verify -Dtest=MySQLSqlDialectIT`\n\nKnown workarounds\n\n* Either run integration tests from the Eclipse IDE\n* or remove `.withJvmOptions(udfTestSetup.getJvmOptions())` from `ExasolObjectConfiguration.builder()` \n* or run tests with JVM option `-Dtest.coverage=\"false\"`\n* or run integration tests inside the VM.\n\n## Additional Information\n\n* [Changelog](doc/changes/changelog.md)\n* [Dependencies](dependencies.md)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fexasol%2Fudf-debugging-java","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fexasol%2Fudf-debugging-java","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fexasol%2Fudf-debugging-java/lists"}