Added step withSpanAttributes to set the attributes also on child spans, added setSpanAttributes for setting the attribute only on the target

docs/job-traces.md

@@ -12,7 +12,10 @@ The attributes of the traces and spans are normalized in order
 
 ### Enriching pipeline build traces with custom span attributes
 
-[Attributes](https://opentelemetry.io/docs/reference/specification/common/#attribute) can be added to the spans associated with pipeline steps using the `withSpanAttribute(key, value[, type]) ` step.
+[Attributes](https://opentelemetry.io/docs/reference/specification/common/#attribute) can be added to the spans associated with pipeline steps using one of the following pipeline steps:
+* `withSpanAttribute(key, value[, type][, target])`
+* `setSpanAttributes([spanAttribute(key, value[, type][, target])])`
+* `withSpanAttributes([spanAttribute(key, value[, type][, target])])`
 
 Example:
 
@@ -21,6 +24,10 @@ withSpanAttribute(key: "pipeline_type", value: "release_pipeline", target: "PIPE
 ...
 stage ("build") {
     withSpanAttribute(key: "build.tool", value: "maven")
+    setSpanAttributes([spanAttribute(key: "build.tool", value: "maven")])
+    withSpanAttributes([spanAttribute(key: "test.tool", value: "junit")]) {
+        sh "./run-tests.sh"
+    }
 }
 ````
 
@@ -30,7 +37,26 @@ If not specified, the `type` of the attribute is inferred from the passed `value
    * `CURRENT_SPAN` (default value): the attribute is set on the span of the current pipeline phase (current node, stage, step...)
    * `PIPELINE_ROOT_SPAN`: the attribute is set on the root span of the pipeline (ie the "BUILD ..." span)
 
-Note that the `withSpanAttribute` doesn't create a span in the pipeline build trace.
+Note that none of the steps `setSpanAttributes`, `withSpanAttribute`, `withSpanAttributes` create a span in the pipeline build trace.
+
+`withSpanAttribute` and `setSpanAttributes` set the given attribute(s) on the target.
+
+`withSpanAttributes` sets the given attribute(s) on child spans.
+
+It's also possible to use `withSpanAttributes` in declarative pipelines:
+
+````groovy
+pipeline {
+    options {
+        withSpanAttributes([spanAttribute(key: 'pipeline.type', value: 'release', target: 'PIPELINE_ROOT_SPAN')])
+    }
+    stages {
+        stage('build') {
+            ...
+        }
+    }
+}
+````
 
 ### Pipeline, freestyle, and matrix project build spans
 

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

@@ -10,20 +10,28 @@
 import io.opentelemetry.api.common.AttributeKey;
 
 import edu.umd.cs.findbugs.annotations.NonNull;
+
+import java.io.Serializable;
 import java.util.HashMap;
+import java.util.HashSet;
 import java.util.Map;
+import java.util.Set;
 import java.util.logging.Logger;
 import java.util.stream.Collectors;
 
 /**
  * @see io.opentelemetry.api.common.AttributeKey
  * @see io.opentelemetry.api.common.AttributeType
  */
-public class OpenTelemetryAttributesAction extends InvisibleAction {
+public class OpenTelemetryAttributesAction extends InvisibleAction implements Serializable {
     private final static Logger LOGGER = Logger.getLogger(MonitoringAction.class.getName());
 
+    private static final long serialVersionUID = 5488506456727905116L;
+
     private transient Map<AttributeKey<?>, Object> attributes;
 
+    private transient Set<String> appliedToSpans;
+
     @NonNull
     public Map<AttributeKey<?>, Object> getAttributes() {
         if (attributes == null) {
@@ -32,6 +40,18 @@ public Map<AttributeKey<?>, Object> getAttributes() {
         return attributes;
     }
 
+    /**
+     * Remember a span to which these attributes are applied.
+     * @param spanId
+     * @return true iff a span did not previously have these attributes applied
+     */
+    public boolean isNotYetAppliedToSpan(String spanId) {
+        if (appliedToSpans == null) {
+            appliedToSpans = new HashSet<>();
+        }
+        return appliedToSpans.add(spanId);
+    }
+
     @Override
     public String toString() {
         return "OpenTelemetryAttributesAction{" +

src/main/java/io/jenkins/plugins/opentelemetry/job/MonitoringPipelineListener.java

@@ -18,8 +18,10 @@
 import io.jenkins.plugins.opentelemetry.OtelUtils;
 import io.jenkins.plugins.opentelemetry.job.jenkins.AbstractPipelineListener;
 import io.jenkins.plugins.opentelemetry.job.jenkins.PipelineListener;
+import io.jenkins.plugins.opentelemetry.job.step.SetSpanAttributesStep;
 import io.jenkins.plugins.opentelemetry.job.step.StepHandler;
 import io.jenkins.plugins.opentelemetry.job.step.WithSpanAttributeStep;
+import io.jenkins.plugins.opentelemetry.job.step.WithSpanAttributesStep;
 import io.jenkins.plugins.opentelemetry.semconv.JenkinsOtelSemanticAttributes;
 import io.opentelemetry.api.common.AttributeKey;
 import io.opentelemetry.api.events.EventEmitter;
@@ -106,7 +108,7 @@
 
             LOGGER.log(Level.FINE, () -> run.getFullDisplayName() + " - > " + JenkinsOtelSemanticAttributes.AGENT + "(" + agentLabel + ") - begin " + OtelUtils.toDebugString(agentSpan));
 
-            getTracerService().putSpan(run, agentSpan, stepStartNode);
+            getTracerService().putAgentSpan(run, agentSpan, stepStartNode);
 
             try (Scope allocateAgentSpanScope = agentSpan.makeCurrent()) {
                 SpanBuilder allocateAgentSpanBuilder = getTracer().spanBuilder(JenkinsOtelSemanticAttributes.AGENT_ALLOCATION_UI)
@@ -123,7 +125,7 @@
 
                 LOGGER.log(Level.FINE, () -> run.getFullDisplayName() + " - > " + JenkinsOtelSemanticAttributes.AGENT_ALLOCATE + "(" + agentLabel + ") - begin " + OtelUtils.toDebugString(allocateAgentSpan));
 
-                getTracerService().putSpan(run, allocateAgentSpan, stepStartNode);
+                getTracerService().putAgentSpan(run, allocateAgentSpan, stepStartNode);
             }
         }
     }
@@ -232,7 +234,10 @@
             return true;
         }
         String stepFunctionName = stepDescriptor.getFunctionName();
-        boolean ignoreStep = WithSpanAttributeStep.DescriptorImpl.FUNCTION_NAME.equals(stepFunctionName) || this.ignoredSteps.contains(stepFunctionName);
+        boolean ignoreStep = SetSpanAttributesStep.DescriptorImpl.FUNCTION_NAME.equals(stepFunctionName)
+            || WithSpanAttributeStep.DescriptorImpl.FUNCTION_NAME.equals(stepFunctionName)
+            || WithSpanAttributesStep.DescriptorImpl.FUNCTION_NAME.equals(stepFunctionName)
+            || this.ignoredSteps.contains(stepFunctionName);
         LOGGER.log(Level.FINER, ()-> "isIgnoreStep(" + stepDescriptor + "): " + ignoreStep);
         return ignoreStep;
     }
@@ -379,22 +384,38 @@
                 openTelemetryAttributesAction.getAttributes().put(AttributeKey.stringKey(JenkinsOtelSemanticAttributes.JENKINS_COMPUTER_NAME.getKey()), computer.getName());
                 computer.addAction(openTelemetryAttributesAction);
             }
-            OpenTelemetryAttributesAction openTelemetryAttributesAction = computer.getAction(OpenTelemetryAttributesAction.class);
+            OpenTelemetryAttributesAction otelComputerAttributesAction = computer.getAction(OpenTelemetryAttributesAction.class);
+            OpenTelemetryAttributesAction otelChildAttributesAction = context.get(OpenTelemetryAttributesAction.class);
 
             try (Scope ignored = setupContext(run, node)) {
                 Span currentSpan = Span.current();
-                LOGGER.log(Level.FINE, () -> "Add resource attributes to span " + OtelUtils.toDebugString(currentSpan) + " - " + openTelemetryAttributesAction);
-                for (Map.Entry<AttributeKey<?>, Object> entry : openTelemetryAttributesAction.getAttributes().entrySet()) {
-                    AttributeKey<?> attributeKey = entry.getKey();
-                    Object value = verifyNotNull(entry.getValue());
-                    currentSpan.setAttribute((AttributeKey<? super Object>) attributeKey, value);
-                }
+                LOGGER.log(Level.FINE, () -> "Add resource attributes to span " + OtelUtils.toDebugString(currentSpan) + " - " + otelComputerAttributesAction);
+                setAttributesToSpan(currentSpan, otelComputerAttributesAction);
+
+                LOGGER.log(Level.FINE, () -> "Add attributes to child span " + OtelUtils.toDebugString(currentSpan) + " - " + otelChildAttributesAction);
+                setAttributesToSpan(currentSpan, otelChildAttributesAction);
             }
         } catch (IOException | InterruptedException | RuntimeException e) {
             LOGGER.log(Level.WARNING,"Exception processing " + step + " - " + context, e);
         }
     }
 
+    private void setAttributesToSpan(@NonNull Span span, OpenTelemetryAttributesAction openTelemetryAttributesAction) {
+        if (openTelemetryAttributesAction == null) {
+            return;
+        }
+        if (!openTelemetryAttributesAction.isNotYetAppliedToSpan(span.getSpanContext().getSpanId())) {
+            // Do not reapply attributes, if previously applied.
+            // This is important for overriding of attributes to work in an intuitive manner.
+            return;
+        }
+        for (Map.Entry<AttributeKey<?>, Object> entry : openTelemetryAttributesAction.getAttributes().entrySet()) {
+            AttributeKey<?> attributeKey = entry.getKey();
+            Object value = verifyNotNull(entry.getValue());
+            span.setAttribute((AttributeKey<? super Object>) attributeKey, value);
+        }
+    }
+
     /**
      * @return {@code null} if no {@link Span} has been created for the {@link Run} of the given {@link FlowNode}
      */

src/main/java/io/jenkins/plugins/opentelemetry/job/OtelTraceService.java

@@ -14,12 +14,14 @@
 import hudson.model.AbstractBuild;
 import hudson.model.Run;
 import hudson.tasks.BuildStep;
+import io.jenkins.plugins.opentelemetry.OpenTelemetryAttributesAction;
 import io.jenkins.plugins.opentelemetry.OtelUtils;
 import io.jenkins.plugins.opentelemetry.job.action.BuildStepMonitoringAction;
 import io.jenkins.plugins.opentelemetry.job.action.FlowNodeMonitoringAction;
 import io.jenkins.plugins.opentelemetry.job.action.OtelMonitoringAction;
 import io.jenkins.plugins.opentelemetry.job.action.RunPhaseMonitoringAction;
 import io.jenkins.plugins.opentelemetry.semconv.JenkinsOtelSemanticAttributes;
+import io.opentelemetry.api.common.AttributeKey;
 import io.opentelemetry.api.trace.Span;
 import org.jenkinsci.plugins.workflow.cps.nodes.StepEndNode;
 import org.jenkinsci.plugins.workflow.cps.nodes.StepStartNode;
@@ -34,6 +36,7 @@
 import java.util.ArrayList;
 import java.util.Collections;
 import java.util.List;
+import java.util.Map;
 import java.util.Objects;
 import java.util.Optional;
 import java.util.function.Predicate;
@@ -42,6 +45,8 @@
 import java.util.stream.Collectors;
 import java.util.stream.StreamSupport;
 
+import static com.google.common.base.Verify.verifyNotNull;
+
 @Extension
 public class OtelTraceService {
     private static final Logger LOGGER = Logger.getLogger(OtelTraceService.class.getName());
@@ -233,9 +238,20 @@ public void putSpan(@NonNull Run run, @NonNull Span span) {
 
     public void putRunPhaseSpan(@NonNull Run run, @NonNull Span span) {
         run.addAction(new RunPhaseMonitoringAction(span));
+        // Phase spans do not get the attributes from the StepContext.
+        // To ensure that attributes of child spans of the root span are set correctly we read them from an OpenTelemetryAttributesAction set on the Run.
+        setAttributesToSpan(span, run.getAction(OpenTelemetryAttributesAction.class));
         LOGGER.log(Level.FINEST, () -> "putRunPhaseSpan(" + run.getFullDisplayName() + "," + OtelUtils.toDebugString(span) + ")");
     }
 
+    public void putAgentSpan(@NonNull Run run, @NonNull Span span, @NonNull FlowNode flowNode) {
+        // Agent spans do not get the attributes from the StepContext.
+        // To ensure that attributes of child spans of the root span are set correctly we read them from an OpenTelemetryAttributesAction set on the Run.
+        setAttributesToSpan(span, run.getAction(OpenTelemetryAttributesAction.class));
+        putSpan(run, span, flowNode);
+        LOGGER.log(Level.FINEST, () -> "putAgentSpan(" + run.getFullDisplayName() + "," + OtelUtils.toDebugString(span) + ")");
+    }
+
     public void putSpan(@NonNull Run run, @NonNull Span span, @NonNull FlowNode flowNode) {
         // FYI for agent allocation, we have 2 FlowNodeMonitoringAction to track the agent allocation duration
         flowNode.addAction(new FlowNodeMonitoringAction(span));
@@ -244,6 +260,17 @@ public void putSpan(@NonNull Run run, @NonNull Span span, @NonNull FlowNode flow
             OtelUtils.toDebugString(flowNode) + ", " + OtelUtils.toDebugString(span) + ")");
     }
 
+    private void setAttributesToSpan(@NonNull Span span, OpenTelemetryAttributesAction openTelemetryAttributesAction) {
+        if (openTelemetryAttributesAction == null) {
+            return;
+        }
+        for (Map.Entry<AttributeKey<?>, Object> entry : openTelemetryAttributesAction.getAttributes().entrySet()) {
+            AttributeKey<?> attributeKey = entry.getKey();
+            Object value = verifyNotNull(entry.getValue());
+            span.setAttribute((AttributeKey<? super Object>) attributeKey, value);
+        }
+    }
+
     static public OtelTraceService get() {
         return ExtensionList.lookupSingleton(OtelTraceService.class);
     }

src/main/java/io/jenkins/plugins/opentelemetry/job/jenkins/GraphListenerAdapterToPipelineListener.java

@@ -111,7 +111,7 @@ public void notifyOfNewStep(@NonNull Step step, @NonNull StepContext context) {
             Computer computer = context.get(Computer.class);
             String computerHostname = computer == null ? "#null#" : computer.getHostName();
             String computerActions = computer == null ? "#null#" :  computer.getAllActions().stream().map(action -> action.getClass().getSimpleName()).collect(Collectors.joining(", "));
-            String computerName= computer == null ? "#null#" : computer.getName() + "/" + computer.getDisplayName();
+            String computerName = computer == null ? "#null#" : computer.getName() + "/" + computer.getDisplayName();
             log(Level.FINE, () -> run.getFullDisplayName() + " - notifyOfNewStep - Process " + PipelineNodeUtil.getDetailedDebugString(flowNode) + " - computer[name: " + computerName + ", hostname: " + computerHostname + "," + computerActions + "]");
         } catch (IOException | InterruptedException | RuntimeException e) {
             e.printStackTrace();

src/main/java/io/jenkins/plugins/opentelemetry/job/step/SetSpanAttributesStep.java

@@ -0,0 +1,106 @@
+/*
+ * Copyright The Original Author or Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+package io.jenkins.plugins.opentelemetry.job.step;
+
+import edu.umd.cs.findbugs.annotations.CheckForNull;
+import edu.umd.cs.findbugs.annotations.NonNull;
+import hudson.Extension;
+import hudson.model.Item;
+import hudson.model.ItemGroup;
+import hudson.model.TaskListener;
+import hudson.util.ListBoxModel;
+import io.opentelemetry.api.common.AttributeType;
+import org.jenkinsci.plugins.workflow.steps.Step;
+import org.jenkinsci.plugins.workflow.steps.StepContext;
+import org.jenkinsci.plugins.workflow.steps.StepDescriptor;
+import org.jenkinsci.plugins.workflow.steps.StepExecution;
+import org.kohsuke.stapler.AncestorInPath;
+import org.kohsuke.stapler.DataBoundConstructor;
+import org.kohsuke.stapler.DataBoundSetter;
+
+import java.util.Arrays;
+import java.util.Collections;
+import java.util.List;
+import java.util.Optional;
+import java.util.Set;
+import java.util.function.Predicate;
+import java.util.logging.Logger;
+import java.util.stream.Collectors;
+
+public class SetSpanAttributesStep extends Step {
+    private final static Logger logger = Logger.getLogger(SetSpanAttributesStep.class.getName());
+
+    List<SpanAttribute> spanAttributes;
+
+    @DataBoundConstructor
+    public SetSpanAttributesStep(List<SpanAttribute> spanAttributes) {
+        this.spanAttributes = spanAttributes;
+    }
+
+    @Override
+    public StepExecution start(StepContext context) throws Exception {
+        if (spanAttributes == null) {
+            return new StepExecution(context) {
+                @Override
+                public boolean start() {
+                    getContext().onFailure(new IllegalArgumentException("setSpanAttributes requires the spanAttributes parameter"));
+                    return true;
+                }
+            };
+        }
+        List<SpanAttribute> noValueSet = spanAttributes.stream().filter(spanAttribute -> spanAttribute.getValue() == null).collect(Collectors.toList());
+        if (!noValueSet.isEmpty()) {
+            String keys = noValueSet.stream().map(SpanAttribute::getKey).reduce("", (accumulator, spanAttribute) -> {
+                if (accumulator.isEmpty()) {
+                    return spanAttribute;
+                }
+                return accumulator + ", " + spanAttribute;
+            });
+            // null attributes are NOT supported, log an error
+            return new StepExecution(context) {
+                @Override
+                public boolean start() {
+                    getContext().onFailure(new IllegalArgumentException("setSpanAttributes requires that all spanAttributes have a value set. The attribute(s) with the following keys violate this requirement: " + keys));
+                    return true;
+                }
+            };
+        }
+        spanAttributes.forEach(SpanAttribute::setDefaultType);
+        return new SpanAttributeStepExecution(spanAttributes, context.hasBody(), context);
+    }
+
+    @Extension
+    public static final class DescriptorImpl extends StepDescriptor {
+        public static final String FUNCTION_NAME = "setSpanAttributes";
+
+        @Override
+        public Set<? extends Class<?>> getRequiredContext() {
+            return Collections.singleton(TaskListener.class);
+        }
+
+        @Override
+        public String getFunctionName() {
+            return FUNCTION_NAME;
+        }
+
+        @NonNull
+        @Override
+        public String getDisplayName() {
+            return "Set Span Attributes";
+        }
+
+        public ListBoxModel doFillTypeItems(@AncestorInPath Item item, @AncestorInPath ItemGroup context) {
+            List<AttributeType> supportedAttributeTypes = Arrays.asList(AttributeType.STRING, AttributeType.LONG, AttributeType.BOOLEAN, AttributeType.DOUBLE);
+            return new ListBoxModel(supportedAttributeTypes.stream().map(t -> new ListBoxModel.Option(t.name(), t.name())).collect(Collectors.toList()));
+        }
+
+        public ListBoxModel doFillTargetItems(@AncestorInPath Item item, @AncestorInPath ItemGroup context) {
+            return new ListBoxModel(Arrays.stream(SpanAttributeTarget.values()).map(t -> new ListBoxModel.Option(t.name(), t.name())).collect(Collectors.toList()));
+        }
+
+    }
+
+}