{"id":50286667,"url":"https://github.com/roebi/qf-fx-gui-lib-telemetry","last_synced_at":"2026-05-28T03:05:33.085Z","repository":{"id":357151791,"uuid":"1235589867","full_name":"roebi/qf-fx-gui-lib-telemetry","owner":"roebi","description":"OpenTelemetry instrumentation library for QFTest FX GUI Library performance measurement","archived":false,"fork":false,"pushed_at":"2026-05-23T07:42:31.000Z","size":439,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-05-23T09:30:53.528Z","etag":null,"topics":["fx","java","telemetry"],"latest_commit_sha":null,"homepage":"https://central.sonatype.com/artifact/io.github.roebi/qf-fx-gui-lib-telemetry","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/roebi.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,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-05-11T13:20:20.000Z","updated_at":"2026-05-23T07:42:29.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/roebi/qf-fx-gui-lib-telemetry","commit_stats":null,"previous_names":["roebi/qf-fx-gui-lib-telemetry"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/roebi/qf-fx-gui-lib-telemetry","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/roebi%2Fqf-fx-gui-lib-telemetry","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/roebi%2Fqf-fx-gui-lib-telemetry/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/roebi%2Fqf-fx-gui-lib-telemetry/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/roebi%2Fqf-fx-gui-lib-telemetry/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/roebi","download_url":"https://codeload.github.com/roebi/qf-fx-gui-lib-telemetry/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/roebi%2Fqf-fx-gui-lib-telemetry/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33592098,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-05-28T02:00:06.440Z","response_time":99,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"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":["fx","java","telemetry"],"created_at":"2026-05-28T03:05:32.983Z","updated_at":"2026-05-28T03:05:33.079Z","avatar_url":"https://github.com/roebi.png","language":"Java","funding_links":[],"categories":[],"sub_categories":[],"readme":"# qf-fx-gui-lib-telemetry\n\nOpenTelemetry instrumentation library for QFTest FX GUI Library performance measurement.\n\n## Architecture\n\n```Architecture\nQFTest Server JVM  (one per test run)\n  ServerTelemetry.init()  -\u003e  ServerSpans.*\n\n  \u003c-- agent protocol (black box) --\u003e\n\nClient JVM 1..N  (one per SUT instance)\n  ClientTelemetry.init(clientId)  -\u003e  ClientSpans.*\n```\n\n## The 5 Measurement Points\n\n| # | Span name | JVM | Class |\n| --- | --- | --- | --- |\n| 1 | `resolver.lookup` | Server | `ServerSpans.resolverLookup()` |\n| 2 | `agent.command.roundtrip` | Server | `ServerSpans.agentRoundTrip()` |\n| 3 | `fx.queue.wait` | Client | `ClientSpans.startQueueWait()` |\n| 4 | `fx.event.dispatch` | Client | `ClientSpans.fxEventDispatch()` |\n| 5 | `fx.verification.wait` | Client | `ClientSpans.verificationWait()` |\n\nCross-JVM correlation is done via the `qf.step.id` attribute (not W3C trace propagation,\nwhich cannot cross the QFTest agent protocol boundary).\n\n## Prerequisites\n\n- Java 21+\n- Jaeger running locally (see below)\n\n## Build\n\n```bash\n./gradlew build\n./gradlew test\n```\n\n## Run Jaeger locally\n\n```bash\npodman run --rm -d \\\n  --name jaeger \\\n  -p 16686:16686 \\\n  -p 4318:4318 \\\n  jaegertracing/all-in-one:latest\n```\n\nOpen [http://localhost:16686](http://localhost:16686) after the test run.\n\nNote: this library uses OTLP/HTTP (port 4318), not gRPC (port 4317),\nto keep the dependency tree simple.\n\n## Usage - Server JVM\n\nCall once during suite initialisation (resolver registration hook):\n\n```java\n// default endpoint: http://localhost:4318/v1/traces\nServerTelemetry.init();\n\n// or custom endpoint:\nServerTelemetry.init(\"http://my-otel-collector:4318/v1/traces\");\n```\n\nInstrument resolver lookup:\n\n```java\ntry (ActiveSpan s = ServerSpans.resolverLookup(clientId, componentId, stepId)) {\n    return resolverRegistry.resolve(componentId);\n} catch (Exception e) {\n    // s.recordException(e) is called automatically if you rethrow\n    throw e;\n}\n```\n\nInstrument agent round-trip:\n\n```java\ntry (ActiveSpan s = ServerSpans.agentRoundTrip(clientId, \"click\")) {\n    return agentChannel.sendAndAwaitAck(clientId, command);\n}\n```\n\nShutdown in suite teardown:\n\n```java\nServerTelemetry.shutdown();\n```\n\n## Usage - Client JVM\n\nCall once in your client-side init hook:\n\n```java\nClientTelemetry.init(qftestClientId);   // e.g. \"MyApp_1\"\n```\n\nInstrument Platform.runLater() queue wait + FX event dispatch:\n\n```java\nQueueWaitMark mark = ClientSpans.startQueueWait(componentId, stepId);\nPlatform.runLater(() -\u003e {\n    mark.arrived();    // records fx.queue.wait_ms, ends that span\n    try (ActiveSpan s = ClientSpans.fxEventDispatch(componentId, stepId, eventType)) {\n        node.fireEvent(event);\n    }\n});\n```\n\nInstrument verification / polling wait:\n\n```java\ntry (VerificationSpan vs = ClientSpans.verificationWait(componentId, stepId)) {\n    while (!stateCondition.isMet()) {\n        vs.incrementPollCount();\n        Thread.sleep(pollIntervalMs);\n    }\n}\n// fx.verification.polls is recorded automatically on close\n```\n\nShutdown when client is stopped:\n\n```java\nClientTelemetry.shutdown();\n```\n\n## Interpreting Results in Jaeger\n\nSearch by tag `qf.step.id=\u003cvalue\u003e` to correlate server and client spans for the same test step.\n\n| Finding | Likely cause | Fix |\n| --- | --- | --- |\n| `resolver.lookup` slow | Linear scan of resolver list | HashMap by component type |\n| `agent.command.roundtrip` slow | Serialization or IPC latency | Batch commands |\n| `fx.queue.wait_ms` high | FAT overloaded | Reduce `runLater` frequency |\n| `fx.event.dispatch` slow | Heavy scene graph traversal | Cache Node references |\n| `fx.verification.polls` high | Poll interval too short | Adaptive backoff |\n\n## Adding to Your Project\n\nAfter building, the jar is at `build/libs/qf-fx-gui-lib-telemetry-1.0.0.jar`.\n\nAdd to your GUI Library's build:\n\n```kotlin\n// build.gradle.kts\ndependencies {\n    implementation(files(\"libs/qf-fx-gui-lib-telemetry-1.0.0.jar\"))\n    // OTel SDK + exporter (transitive via the lib, or declare explicitly)\n}\n```\n\n## publish.yml Dependency audit gradlew dependencyCheckAnalyze\n\nThis product uses the NVD API but is not endorsed or certified by the NVD.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Froebi%2Fqf-fx-gui-lib-telemetry","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Froebi%2Fqf-fx-gui-lib-telemetry","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Froebi%2Fqf-fx-gui-lib-telemetry/lists"}