TS-47380 Improve DX

.github/workflows/actions.yml

@@ -55,7 +55,7 @@ jobs:
       - name: Publish to Maven Central
         if: startsWith(github.ref, 'refs/tags/v')
         run: |
-          ./gradlew publishMavenPublicationToSonatypeRepository closeAndReleaseSonatypeStagingRepository \
+          ./gradlew publishAggregationToCentralPortal \
             -Psigning.secretKeyRingFile=${{ github.workspace }}/.gnupg/secring.gpg \
             -PgpgDirectory=${{ github.workspace }}/.gnupg \
             -Psigning.password=${{ secrets.MAVEN_CENTRAL_GPG_SIGNATURE }} \

.gitignore

@@ -11,5 +11,7 @@ report-generator/test-coverage-*.xml
 **/maven-wrapper.jar
 **/logTest/**
 **/jacoco.exec
+# local profiler configuration containing Teamscale credentials, see docs/DEBUGGING.md
+java-profiler.local.properties
 **/target/**
 .claude/settings.local.json

CHANGELOG.md

@@ -5,6 +5,7 @@ We use [semantic versioning](http://semver.org/):
 - PATCH version when you make backwards compatible bug fixes.
 
 # Next version
+- [breaking] _agent_: Log lines now show the simple class name (`INFO Agent - ...`) instead of the fully qualified one.
 
 # 37.0.2
 - [fix] _agent_: In some cases the hostname was wrongly added to the PID when sending it to Teamscale.

README.md

@@ -107,43 +107,11 @@ git config --local core.hooksPath .githooks
 
 ### Debug locally
 
-For IntelliJ, there is a run config `SampleApp` which profiles the included `sample-debugging-app` and can be used to 
-debug the agent. This run config omits relocating packages in the shadow jar because with relocating, the package 
-names in the jar would not match with the ones IntelliJ knows from the code and so debugging would not work. 
-The agent is configured in the config file `sample-debugging-app/jacocoagent.properties`. By default, no upload 
-is configured but the file includes all required options to upload to Teamscale, they are just commented out. 
-Feel free to adapt it to your needs.
-If you get an `IllegalStateException: Cannot process instrumented class com/example/Main`, make sure that you use 
-the built-in IntelliJ functionality for building and running instead of 
-gradle (IntelliJ Settings -> Build, Execution, Deployment -> Build Tools -> Gradle -> Build and run using: IntelliJ IDEA).
-
-### Debugging the Gradle plugin
-
-* increase the plugin version (=`appVersion`) in [build.gradle.kts](build.gradle.kts)
-* `./gradlew publishToMavenLocal` will deploy your checked out version to your local m2 cache
-* then you can import this version into any other gradle project by
-  * adding the following to the `settings.gradle.kts`
-```kotlin
-pluginManagement {
-    repositories {
-		mavenLocal()
-		gradlePluginPortal()
-    }
-}
-
-dependencyResolutionManagement {
-    repositories {
-		mavenLocal()
-        mavenCentral()
-    }
-}
-```
-  * declaring a plugin dependency on the incremented version of the teamscale plugin
-* to debug a build that uses the plugin, run `./gradlew` with `--no-daemon -Dorg.gradle.debug=true`.
-  The build will pause and wait for you to attach a debugger, via IntelliJ's `Run > Attach to Process`.
-* to debug the impacted test engine during a build, run `./gradlew` with `--no-daemon --debug-jvm` and wait for the test phase to start.
-  The build will pause and wait for you to attach a debugger, via IntelliJ's `Run > Attach to Process`.
-* These two debug flags can also be combined. The build will then pause twice.
+Debug the `SampleApp` run configuration in IntelliJ to debug the included `sample-app` with breakpoints in the agent working.
+
+**[docs/DEBUGGING.md](docs/DEBUGGING.md) is the full guide**: setting up end-to-end communication with a real Teamscale
+instance, how the agent's configuration is resolved from its five sources, where the profiler writes its logs, why a
+misconfigured profiler fails silently, and how to attach a debugger to system tests.
 
 ### Contributing
 

agent/build.gradle.kts

@@ -5,25 +5,33 @@ plugins {
 	com.teamscale.`java-convention`
 	application
 
-	// we don't want to cause conflicts between our dependencies and the target application
+	// we don't want to cause conflicts between the classes we ship and the target application
 	// since the agent will be loaded with the same class loader as the profiled application
-	// so we use the shadow plugin to relocate our dependencies
+	// so we use the shadow plugin to relocate our dependencies and our own classes
 	com.teamscale.`shadow-convention`
 	com.teamscale.coverage
 	com.teamscale.publish
 	com.teamscale.`logger-patch`
 	alias(libs.plugins.oci)
 }
 
-evaluationDependsOn(":installer")
+// The jlink runtime image of the installer, which the distribution below ships alongside the agent.
+val installerImageDependency = configurations.dependencyScope("installerImage")
+val installerImage = configurations.resolvable("installerImagePath") {
+	extendsFrom(installerImageDependency.get())
+}
+
+dependencies {
+	installerImageDependency(project(":installer", JLINK_IMAGE_CONFIGURATION))
+}
 
 publishAs {
 	artifactId = "teamscale-jacoco-agent"
 	readableName = "Teamscale Java Profiler"
 	description = "JVM profiler that simplifies various aspects around recording and uploading test coverage"
 }
 
-val appVersion = rootProject.extra["appVersion"].toString()
+val appVersion = extra["appVersion"].toString()
 val jacocoVersion = libs.versions.jacoco.get()
 val outputVersion = "$appVersion-jacoco-$jacocoVersion"
 
@@ -64,7 +72,7 @@ dependencies {
 }
 
 application {
-	mainClass = "com.teamscale.jacoco.agent.Main"
+	mainClass = "$AGENT_PACKAGE.Main"
 }
 
 tasks.shadowJar {
@@ -73,32 +81,57 @@ tasks.shadowJar {
 	// update
 	archiveFileName = "teamscale-jacoco-agent.jar"
 
+	// The shadow plugin's auto relocation only covers the dependencies, so the agent's own classes are
+	// relocated explicitly. The entry points below have to name them by their relocated names, and so do the
+	// logback configuration files, cf. ShadowedPackages.kt.
+	if (usesShadowedPackages.get()) {
+		relocate(AGENT_PACKAGE, "$SHADOW_PACKAGE_PREFIX.$AGENT_PACKAGE")
+	}
+
 	manifest {
-		attributes["Premain-Class"] = "com.teamscale.jacoco.agent.PreMain"
+		attributes["Premain-Class"] = shadowed("$AGENT_PACKAGE.PreMain")
+		attributes["Main-Class"] = shadowed("$AGENT_PACKAGE.Main")
 	}
 }
 
 tasks.startShadowScripts {
 	applicationName = "convert"
+	mainClass = shadowed("$AGENT_PACKAGE.Main")
 }
 
+// Shares the shaded agent jar with the projects that attach the profiler to a JVM, cf. the
+// com.teamscale.agent-jar convention plugin.
+configurations.consumable(AGENT_JAR_CONFIGURATION)
+artifacts.add(AGENT_JAR_CONFIGURATION, tasks.shadowJar)
+
 distributions {
 	named("shadow") {
 		distributionBaseName = "teamscale-jacoco-agent"
 		contents {
-			from(project(":installer").tasks["jlink"]) {
+			from(installerImage.get()) {
 				into("installer")
 			}
 
+			// Captured in a local so the copy action does not reference the build script itself,
+			// which cannot be stored in the configuration cache.
+			val distributionVersion = outputVersion
 			filesMatching("**/VERSION.txt") {
 				filter {
-					it.replace("%APP_VERSION_TOKEN_REPLACED_DURING_BUILD%", outputVersion)
+					it.replace("%APP_VERSION_TOKEN_REPLACED_DURING_BUILD%", distributionVersion)
 				}
 			}
 		}
 	}
 }
 
+// The logging templates in src/dist are checked in without the shadow prefix so they also work when
+// relocation is disabled. Add the prefix while packaging them, since the distribution ships the shaded agent.
+listOf(tasks.shadowDistZip, tasks.shadowDistTar, tasks.installShadowDist).forEach { task ->
+	task { shadowLoggingPackages(usesShadowedPackages) }
+}
+
+verifyShadowedLoggingConfigs(tasks.shadowJar, tasks.shadowDistZip)
+
 tasks.shadowDistZip {
 	archiveFileName = "teamscale-jacoco-agent.zip"
 }

agent/src/dist/logging/logback.console.xml

@@ -1,15 +1,12 @@
 <?xml version="1.0" encoding="UTF-8"?>
 <configuration>
-  <appender name="CONSOLE" class="shadow.ch.qos.logback.core.ConsoleAppender">
+  <appender name="CONSOLE" class="ch.qos.logback.core.ConsoleAppender">
     <encoder>
-      <pattern>%date{yyyy-MM-dd HH:mm:ss} %-5level %logger{35} - %msg%n</pattern>
+      <pattern>%date{yyyy-MM-dd HH:mm:ss} %-5level %logger{0} - %msg%n</pattern>
     </encoder>
   </appender>
 
   <root level="INFO">
     <appender-ref ref="CONSOLE"/>
   </root>
-
-  <logger name="shadow.org.apache.spark" level="warn" />
-  <logger name="shadow.org.eclipse.jetty" level="warn" />
 </configuration>

agent/src/dist/logging/logback.debug.xml

@@ -2,37 +2,34 @@
 <configuration>
 	<define name="defaultLogDir" class="com.teamscale.jacoco.agent.logging.LogDirectoryPropertyDefiner" />
 
-	<appender name="CONSOLE" class="shadow.ch.qos.logback.core.ConsoleAppender">
+	<appender name="CONSOLE" class="ch.qos.logback.core.ConsoleAppender">
 		<encoder>
-			<pattern>%date{yyyy-MM-dd HH:mm:ss} %-5level %logger{35} - %msg%n</pattern>
+			<pattern>%date{yyyy-MM-dd HH:mm:ss} %-5level %logger{0} - %msg%n</pattern>
 		</encoder>
 	</appender>
 
-	<appender name="RollingFile" class="shadow.ch.qos.logback.core.rolling.RollingFileAppender">
+	<appender name="RollingFile" class="ch.qos.logback.core.rolling.RollingFileAppender">
 		<!-- TODO: adjust the path where the log file should be written -->
 		<file>${defaultLogDir}/teamscale-jacoco-agent.log</file>
 
-		<rollingPolicy class="shadow.ch.qos.logback.core.rolling.FixedWindowRollingPolicy">
+		<rollingPolicy class="ch.qos.logback.core.rolling.FixedWindowRollingPolicy">
 			<!-- TODO: adjust the path where the log file should be written -->
 			<fileNamePattern>${defaultLogDir}/teamscale-jacoco-agent-%i.log.zip</fileNamePattern>
 			<minIndex>1</minIndex>
 			<maxIndex>10</maxIndex>
 		</rollingPolicy>
 
-		<triggeringPolicy class="shadow.ch.qos.logback.core.rolling.SizeBasedTriggeringPolicy">
+		<triggeringPolicy class="ch.qos.logback.core.rolling.SizeBasedTriggeringPolicy">
 			<maxFileSize>1MB</maxFileSize>
 		</triggeringPolicy>
 
 		<encoder>
-			<pattern>%date{yyyy-MM-dd HH:mm:ss} %-5level %logger{35} - %msg%n</pattern>
+			<pattern>%date{yyyy-MM-dd HH:mm:ss} %-5level %logger{0} - %msg%n</pattern>
 		</encoder>
 	</appender>
 
 	<root level="DEBUG">
 		<appender-ref ref="RollingFile"/>
 		<appender-ref ref="CONSOLE"/>
 	</root>
-
-	<logger name="shadow.org.apache.spark" level="warn" />
-	<logger name="shadow.org.eclipse.jetty" level="warn" />
 </configuration>

agent/src/dist/logging/logback.rolling-file.xml

@@ -2,30 +2,27 @@
 <configuration>
     <define name="defaultLogDir" class="com.teamscale.jacoco.agent.logging.LogDirectoryPropertyDefiner"/>
 
-	<appender name="RollingFile" class="shadow.ch.qos.logback.core.rolling.RollingFileAppender">
+	<appender name="RollingFile" class="ch.qos.logback.core.rolling.RollingFileAppender">
 		<!-- TODO: adjust the path where the log file should be written -->
 		<file>${defaultLogDir}/teamscale-jacoco-agent.log</file>
 
-		<rollingPolicy class="shadow.ch.qos.logback.core.rolling.FixedWindowRollingPolicy">
+		<rollingPolicy class="ch.qos.logback.core.rolling.FixedWindowRollingPolicy">
 			<!-- TODO: adjust the path where the log file should be written -->
 			<fileNamePattern>${defaultLogDir}/teamscale-jacoco-agent-%i.log.zip</fileNamePattern>
 			<minIndex>1</minIndex>
 			<maxIndex>10</maxIndex>
 		</rollingPolicy>
 
-		<triggeringPolicy class="shadow.ch.qos.logback.core.rolling.SizeBasedTriggeringPolicy">
+		<triggeringPolicy class="ch.qos.logback.core.rolling.SizeBasedTriggeringPolicy">
 			<maxFileSize>1MB</maxFileSize>
 		</triggeringPolicy>
 
 		<encoder>
-			<pattern>%date{yyyy-MM-dd HH:mm:ss} %-5level %logger{35} - %msg%n</pattern>
+			<pattern>%date{yyyy-MM-dd HH:mm:ss} %-5level %logger{0} - %msg%n</pattern>
 		</encoder>
 	</appender>
 
 	<root level="INFO">
 		<appender-ref ref="RollingFile"/>
 	</root>
-
-	<logger name="shadow.org.apache.spark" level="warn" />
-	<logger name="shadow.org.eclipse.jetty" level="warn" />
 </configuration>

agent/src/main/kotlin/com/teamscale/jacoco/agent/Main.kt

@@ -68,7 +68,7 @@ object Main {
 
 	/** Creates a builder for a [com.beust.jcommander.JCommander] object.  */
 	private fun createJCommanderBuilder() =
-		JCommander.newBuilder().programName(Main::class.java.getName())
+		JCommander.newBuilder().programName("convert")
 			.addObject(defaultArguments)
 			.addObject(command)
 

agent/src/main/resources/com/teamscale/jacoco/agent/logback-default-debugging.xml

@@ -2,37 +2,34 @@
 <configuration>
 	<define name="defaultLogDir" class="com.teamscale.jacoco.agent.logging.DebugLogDirectoryPropertyDefiner" />
 
-	<appender name="CONSOLE" class="shadow.ch.qos.logback.core.ConsoleAppender">
+	<appender name="CONSOLE" class="ch.qos.logback.core.ConsoleAppender">
 		<encoder>
-			<pattern>%date{yyyy-MM-dd HH:mm:ss} %-5level %logger{35} - %msg%n</pattern>
+			<pattern>%date{yyyy-MM-dd HH:mm:ss} %-5level %logger{0} - %msg%n</pattern>
 		</encoder>
 	</appender>
 
-	<appender name="RollingFile" class="shadow.ch.qos.logback.core.rolling.RollingFileAppender">
+	<appender name="RollingFile" class="ch.qos.logback.core.rolling.RollingFileAppender">
 		<!-- TODO: adjust the path where the log file should be written -->
 		<file>${defaultLogDir}/teamscale-jacoco-agent.log</file>
 
-		<rollingPolicy class="shadow.ch.qos.logback.core.rolling.FixedWindowRollingPolicy">
+		<rollingPolicy class="ch.qos.logback.core.rolling.FixedWindowRollingPolicy">
 			<!-- TODO: adjust the path where the log file should be written -->
 			<fileNamePattern>${defaultLogDir}/teamscale-jacoco-agent-%i.log.zip</fileNamePattern>
 			<minIndex>1</minIndex>
 			<maxIndex>10</maxIndex>
 		</rollingPolicy>
 
-		<triggeringPolicy class="shadow.ch.qos.logback.core.rolling.SizeBasedTriggeringPolicy">
+		<triggeringPolicy class="ch.qos.logback.core.rolling.SizeBasedTriggeringPolicy">
 			<maxFileSize>1MB</maxFileSize>
 		</triggeringPolicy>
 
 		<encoder>
-			<pattern>%date{yyyy-MM-dd HH:mm:ss} %-5level %logger{35} - %msg%n</pattern>
+			<pattern>%date{yyyy-MM-dd HH:mm:ss} %-5level %logger{0} - %msg%n</pattern>
 		</encoder>
 	</appender>
 
 	<root level="DEBUG">
 		<appender-ref ref="RollingFile"/>
 		<appender-ref ref="CONSOLE"/>
 	</root>
-
-	<logger name="shadow.org.apache.spark" level="warn" />
-	<logger name="shadow.org.eclipse.jetty" level="warn" />
 </configuration>

agent/src/main/resources/com/teamscale/jacoco/agent/logback-default.xml

@@ -2,29 +2,26 @@
 <configuration>
     <define name="defaultLogDir" class="com.teamscale.jacoco.agent.logging.LogDirectoryPropertyDefiner" />
 
-    <appender name="RollingFile" class="shadow.ch.qos.logback.core.rolling.RollingFileAppender">
+    <appender name="RollingFile" class="ch.qos.logback.core.rolling.RollingFileAppender">
         <!-- We write to a file that is located in a folder provided via the context -->
         <file>${defaultLogDir}/teamscale-jacoco-agent.log</file>
 
-        <rollingPolicy class="shadow.ch.qos.logback.core.rolling.FixedWindowRollingPolicy">
+        <rollingPolicy class="ch.qos.logback.core.rolling.FixedWindowRollingPolicy">
             <fileNamePattern>${defaultLogDir}/teamscale-jacoco-agent-%i.log.zip</fileNamePattern>
             <minIndex>1</minIndex>
             <maxIndex>10</maxIndex>
         </rollingPolicy>
 
-        <triggeringPolicy class="shadow.ch.qos.logback.core.rolling.SizeBasedTriggeringPolicy">
+        <triggeringPolicy class="ch.qos.logback.core.rolling.SizeBasedTriggeringPolicy">
             <maxFileSize>1MB</maxFileSize>
         </triggeringPolicy>
 
         <encoder>
-            <pattern>%date{yyyy-MM-dd HH:mm:ss} %-5level %logger{35} - %msg%n</pattern>
+            <pattern>%date{yyyy-MM-dd HH:mm:ss} %-5level %logger{0} - %msg%n</pattern>
         </encoder>
     </appender>
 
     <root level="INFO">
         <appender-ref ref="RollingFile"/>
     </root>
-
-    <logger name="shadow.org.apache.spark" level="warn" />
-    <logger name="shadow.org.eclipse.jetty" level="warn" />
 </configuration>