Adopt OTel cicd.* semantic conventions incl cicd.* metrics

src/main/java/io/jenkins/plugins/opentelemetry/job/runhandler/DefaultRunHandler.java

@@ -9,9 +9,6 @@
 import edu.umd.cs.findbugs.annotations.NonNull;
 import hudson.Extension;
 import hudson.model.Run;
-import io.jenkins.plugins.opentelemetry.semconv.ExtendedJenkinsAttributes;
-import io.opentelemetry.api.trace.SpanBuilder;
-import io.opentelemetry.api.trace.Tracer;
 import java.util.Arrays;
 import java.util.Collections;
 import java.util.List;
@@ -21,8 +18,8 @@
 import jenkins.scm.api.mixin.ChangeRequestSCMHead;
 
 /**
- * Use same root span name for all pull change request pipelines (pull request, merge request)
- * Use different span names for different branches.
+ * Use same short pipeline name for all change request pipelines (pull request, merge request)
+ * Use different short pipeline name for different branches.
  */
 @Extension
 public class DefaultRunHandler implements RunHandler {
@@ -32,21 +29,21 @@
             "-" + ChangeRequestCheckoutStrategy.MERGE.name().toLowerCase(Locale.ENGLISH)));
 
     @Override
-    public boolean canCreateSpanBuilder(@NonNull Run<?, ?> run) {
+    public boolean matches(@NonNull Run<?, ?> run) {
         return true;
     }
 
     @NonNull
     @Override
-    public SpanBuilder createSpanBuilder(@NonNull Run<?, ?> run, @NonNull Tracer tracer) {
+    public String getPipelineShortName(@NonNull Run<?, ?> run) {
         SCMHead head = SCMHead.HeadByItem.findHead(run.getParent());
-        String spanName;
+        String pipelineShortName;
         if (head instanceof ChangeRequestSCMHead) {
-            spanName = getChangeRequestRootSpanName(run.getParent().getFullName());
+            pipelineShortName = getChangeRequestRootSpanName(run.getParent().getFullName());
         } else {
-            spanName = run.getParent().getFullName();
+            pipelineShortName = run.getParent().getFullName();
         }
-        return tracer.spanBuilder(ExtendedJenkinsAttributes.CI_PIPELINE_RUN_ROOT_SPAN_NAME_PREFIX + spanName);
+        return pipelineShortName;
     }
 
     @VisibleForTesting

src/main/java/io/jenkins/plugins/opentelemetry/job/runhandler/JobDslRunHandler.java

@@ -13,9 +13,9 @@
 import hudson.model.Run;
 import io.jenkins.plugins.opentelemetry.semconv.ExtendedJenkinsAttributes;
 import io.opentelemetry.api.trace.SpanBuilder;
-import io.opentelemetry.api.trace.Tracer;
 import io.opentelemetry.sdk.autoconfigure.spi.ConfigProperties;
 import java.util.Collection;
+import java.util.Optional;
 import javaposse.jobdsl.plugin.actions.SeedJobAction;
 import javaposse.jobdsl.plugin.actions.SeedJobTransientActionFactory;
 import javax.inject.Inject;
@@ -34,7 +34,7 @@
     }
 
     @Override
-    public boolean canCreateSpanBuilder(@NonNull Run<?, ?> run) {
+    public boolean matches(@NonNull Run<?, ?> run) {
         Job<?, ?> job = run.getParent();
         // perf optimization: directly lookup up in the SeedJobTransientActionFactory over
         // `job.getAction(SeedJobAction.class)`
@@ -44,7 +44,7 @@
 
     @NonNull
     @Override
-    public SpanBuilder createSpanBuilder(@NonNull Run<?, ?> run, @NonNull Tracer tracer) {
+    public String getPipelineShortName(@NonNull Run<?, ?> run) {
         Job<?, ?> job = run.getParent();
         // perf optimization: directly lookup up in the SeedJobTransientActionFactory over
         // `job.getAction(SeedJobAction.class)`
@@ -56,30 +56,36 @@
                 .orElseThrow(IllegalStateException::new);
 
         // TODO understand the difference between seedJobAction.getTemplateJob() and seedJobAction.getSeedJob()
-        Item seedJob = seedJobAction.getSeedJob();
-
-        String templateFullName;
-        String templateUrl;
-        String spanName;
-        if (seedJob == null) {
-            templateFullName = null;
-            templateUrl = null;
-            spanName = job.getFullName();
-        } else {
-            templateFullName = seedJob.getFullName();
-            templateUrl = seedJob.getUrl();
-            spanName = collapseJobName ? "Job from seed '" + templateFullName + "'" : job.getFullName();
-        }
-
-        SpanBuilder spanBuilder =
-                tracer.spanBuilder(ExtendedJenkinsAttributes.CI_PIPELINE_RUN_ROOT_SPAN_NAME_PREFIX + spanName);
-        if (templateFullName != null) {
-            spanBuilder.setAttribute(ExtendedJenkinsAttributes.CI_PIPELINE_TEMPLATE_ID, templateFullName);
-        }
-        if (templateUrl != null) {
-            spanBuilder.setAttribute(ExtendedJenkinsAttributes.CI_PIPELINE_TEMPLATE_URL, templateUrl);
-        }
-        return spanBuilder;
+        Optional<Item> seedJob = Optional.ofNullable(seedJobAction.getSeedJob());
+
+        return collapseJobName
+                ? job.getFullName()
+                : seedJob.map(Item::getFullName)
+                        .map(fn -> "Job from seed '" + fn + "'")
+                        .orElse(job.getFullName());
+    }
+
+    @Override
+    public void enrichPipelineRunSpan(@NonNull Run<?, ?> run, @NonNull SpanBuilder spanBuilder) {
+        Job<?, ?> job = run.getParent();
+        // perf optimization: directly lookup up in the SeedJobTransientActionFactory over
+        // `job.getAction(SeedJobAction.class)`
+        Collection<? extends Action> actions = seedJobTransientActionFactory.createFor(job);
+
+        SeedJobAction seedJobAction = (SeedJobAction) actions.stream()
+                .filter(action -> action instanceof SeedJobAction)
+                .findFirst()
+                .orElseThrow(IllegalStateException::new);
+
+        // TODO understand the difference between seedJobAction.getTemplateJob() and seedJobAction.getSeedJob()
+        Optional<Item> seedJob = Optional.ofNullable(seedJobAction.getSeedJob());
+
+        seedJob.map(Item::getFullName)
+                .ifPresent(templateFullName ->
+                        spanBuilder.setAttribute(ExtendedJenkinsAttributes.CI_PIPELINE_TEMPLATE_ID, templateFullName));
+        seedJob.map(Item::getUrl)
+                .ifPresent(templateUrl ->
+                        spanBuilder.setAttribute(ExtendedJenkinsAttributes.CI_PIPELINE_TEMPLATE_URL, templateUrl));
     }
 
     @Override

src/main/java/io/jenkins/plugins/opentelemetry/job/runhandler/MatrixRunHandler.java

@@ -15,7 +15,6 @@
 import hudson.model.Run;
 import io.jenkins.plugins.opentelemetry.semconv.ExtendedJenkinsAttributes;
 import io.opentelemetry.api.trace.SpanBuilder;
-import io.opentelemetry.api.trace.Tracer;
 import io.opentelemetry.sdk.autoconfigure.spi.ConfigProperties;
 import java.util.ArrayList;
 import java.util.List;
@@ -32,22 +31,29 @@
     }
 
     @Override
-    public boolean canCreateSpanBuilder(@NonNull Run<?, ?> run) {
+    public boolean matches(@NonNull Run<?, ?> run) {
         return run instanceof MatrixRun || run instanceof MatrixBuild;
     }
 
     @NonNull
     @Override
-    public SpanBuilder createSpanBuilder(@NonNull Run<?, ?> run, @NonNull Tracer tracer) {
+    public String getPipelineShortName(@NonNull Run<?, ?> run) {
         if (run instanceof MatrixRun matrixRun) {
             MatrixConfiguration matrixConfiguration = matrixRun.getParent();
-
             MatrixProject matrixProject = matrixConfiguration.getParent();
-            String spanName =
-                    expandJobName ? run.getParent().getFullName() : matrixProject.getFullName() + "/execution";
-            SpanBuilder spanBuilder =
-                    tracer.spanBuilder(ExtendedJenkinsAttributes.CI_PIPELINE_RUN_ROOT_SPAN_NAME_PREFIX + spanName);
-            Combination combination = matrixConfiguration.getCombination();
+            return expandJobName ? run.getParent().getFullName() : matrixProject.getFullName() + "/execution";
+        } else if (run instanceof MatrixBuild matrixBuild) {
+            return matrixBuild.getParent().getFullName();
+        } else {
+            throw new IllegalStateException("Unsupported run type " + run);
+        }
+    }
+
+    @Override
+    public void enrichPipelineRunSpan(@NonNull Run<?, ?> run, @NonNull SpanBuilder spanBuilder) {
+        if (run instanceof MatrixRun matrixRun) {
+
+            Combination combination = matrixRun.getParent().getCombination();
             List<String> axisNames = new ArrayList<>();
             List<String> axisValues = new ArrayList<>();
 
@@ -57,13 +63,6 @@
             });
             spanBuilder.setAttribute(ExtendedJenkinsAttributes.CI_PIPELINE_RUN_AXIS_NAMES, axisNames);
             spanBuilder.setAttribute(ExtendedJenkinsAttributes.CI_PIPELINE_RUN_AXIS_VALUES, axisValues);
-
-            return spanBuilder;
-        } else if (run instanceof MatrixBuild matrixBuild) {
-            return tracer.spanBuilder(ExtendedJenkinsAttributes.CI_PIPELINE_RUN_ROOT_SPAN_NAME_PREFIX
-                    + matrixBuild.getParent().getFullName());
-        } else {
-            throw new IllegalStateException("Unsupported run type " + run);
         }
     }
 

src/main/java/io/jenkins/plugins/opentelemetry/job/runhandler/RunHandler.java

@@ -8,17 +8,24 @@
 import edu.umd.cs.findbugs.annotations.NonNull;
 import hudson.model.Run;
 import io.opentelemetry.api.trace.SpanBuilder;
-import io.opentelemetry.api.trace.Tracer;
 import io.opentelemetry.sdk.autoconfigure.spi.ConfigProperties;
 
 public interface RunHandler extends Comparable<RunHandler> {
 
     default void configure(ConfigProperties config) {}
 
-    boolean canCreateSpanBuilder(@NonNull Run<?, ?> run);
+    boolean matches(@NonNull Run<?, ?> run);
 
+    /**
+     * Low cardinality pipeline name that fits with
+     * {@link io.opentelemetry.semconv.incubating.CicdIncubatingAttributes#CICD_PIPELINE_NAME}.
+     * High cardinality elements like the SCM pull request names of a Jenkins multibranch pipeline
+     * should be excluded from the pipeline short name.
+     */
     @NonNull
-    SpanBuilder createSpanBuilder(@NonNull Run<?, ?> run, @NonNull Tracer tracer);
+    String getPipelineShortName(@NonNull Run<?, ?> run);
+
+    default void enrichPipelineRunSpan(@NonNull Run<?, ?> run, @NonNull SpanBuilder spanBuilder) {}
 
     /**
      * @return the ordinal of this handler to execute run handlers in predictable order. The smallest ordinal is executed first.

src/main/java/io/jenkins/plugins/opentelemetry/opentelemetry/SemconvStability.java

@@ -0,0 +1,80 @@
+package io.jenkins.plugins.opentelemetry.opentelemetry;
+
+import hudson.Extension;
+import io.jenkins.plugins.opentelemetry.api.OpenTelemetryLifecycleListener;
+import io.opentelemetry.sdk.autoconfigure.spi.ConfigProperties;
+import java.util.Arrays;
+import java.util.HashSet;
+import java.util.Set;
+import java.util.concurrent.atomic.AtomicInteger;
+import java.util.logging.Level;
+import java.util.logging.Logger;
+import jenkins.YesNoMaybe;
+
+/**
+ * Manages the configuration for semantic convention stability opt-in.
+ * Users can configure which version of the CI/CD semantic conventions to emit.
+ * TODO support hot config changes or document the need to restart Jenkins on config change.
+ */
+@Extension(dynamicLoadable = YesNoMaybe.MAYBE, optional = true)
+public class SemconvStability implements OpenTelemetryLifecycleListener {
+
+    private static final Logger logger = Logger.getLogger(SemconvStability.class.getName());
+
+    private final AtomicInteger configurationCounter = new AtomicInteger(0);
+
+    private boolean emitOldCicdSemconv = true;
+    private boolean emitStableCicdSemconv = true;
+
+    public boolean emitOldCicdSemconv() {
+        return emitOldCicdSemconv;
+    }
+
+    public boolean emitStableCicdSemconv() {
+        return emitStableCicdSemconv;
+    }
+
+    @Override
+    public void afterConfiguration(ConfigProperties configProperties) {
+        boolean oldCicd = true;
+        boolean stableCicd = true;
+
+        // default to just emitting the old style metrics
+        String value = configProperties.getString("otel.semconv-stability.opt-in", "cicd/old");
+        if (value != null) {
+            Set<String> values = new HashSet<>(Arrays.asList(value.split(",")));
+
+            // technically it's possible to set "cicd,cicd/dup" or "cicd,cicd/old"
+            if (values.contains("cicd/dup")) {
+                oldCicd = true;
+                stableCicd = true;
+            } else if (values.contains("cicd/old")) {
+                oldCicd = true;
+                stableCicd = false;
+            } else if (values.contains("cicd")) {
+                oldCicd = false;
+                stableCicd = true;
+            }
+        }
+        if (configurationCounter.get() > 0 && (emitOldCicdSemconv != oldCicd || emitStableCicdSemconv != stableCicd)) {
+            logger.log(
+                    Level.INFO,
+                    "SemconvStability: configuration changes from " + "emitOldCicdSemconv="
+                            + emitOldCicdSemconv + " to " + oldCicd + ", emitStableCicdSemconv="
+                            + emitStableCicdSemconv + " to " + stableCicd
+                            + " may not support hot reload and may require restart");
+        }
+        emitOldCicdSemconv = oldCicd;
+        emitStableCicdSemconv = stableCicd;
+        configurationCounter.incrementAndGet();
+        logger.log(
+                Level.FINE,
+                () -> "SemconvStability: emitOldCicdSemconv=" + emitOldCicdSemconv + ", emitStableCicdSemconv="
+                        + emitStableCicdSemconv);
+    }
+
+    @Override
+    public int ordinal() {
+        return Integer.MIN_VALUE;
+    }
+}