Capability to manually create spans

[cyrille-leclerc]

Problem description

I want to manually create spans in my pipeline, similar to manually creating spans when instrumenting applications with distributed tracing.

Example use cases

• Create a "grouping span" to group multiple atomic actions together.
  • Example: Get code from a complex Git repository incl fetching submodules
• Add events to the trace typically to add "logs"
  • Probably better solved using the concept of "span events" in OpenTelemetry API
• Add informations on shell steps to indicate the purpose of the shell step (e.g. an sh 'docker login -u $user -p $pass my.docker.registry')
  • May be better solved solving Capability to manually add attributes to spans #91

Example with the OpenTelemetry APIs for Java

Tracer tracer = null;
tracer.spanBuilder("Get code from Git (incl fetching sub modules)")
    .setAttribute("my.attribute", "my value")
    .startSpan();

See other problem statements

• Capability to manually add attributes to spans #91
• Capability to add "logs" to spans #92

Proposed solutions

createSpan pipeline step

pipeline {
    agent any
    stages {
        stage('Checkout') {
            steps {
                createSpan(name:'my-span', attributes:[TODO 'command':'git']) {
                    // TODO sequence of shell steps to `git`+ fetch git submodules
                    // Get some code from a GitHub repository
                    // git credentialsId: 'my-user-git', url: 'https://github.com/jglick/simple-maven-project-with-tests.git'
                }
            }
        }
        stage('Build') {
            steps {
                ...
            }
        }
    }
}

[ipleten]

It also might be beneficial to get id of span and of traceID to enrich trace with data from other tools. Like we have deployment tool being triggered within pipeline which we can update to send spans to current trace therefore we could track deployment status linked to pipeline.

[kuisathaverat]

Does the following pipeline code do the same? I think so

def my_span(List spanAttributes, Closure body) {
    withSpanAttributes(spanAttributes) {
        body()
    }
}

pipeline {
    agent any
    stages {
        stage('Checkout') {
            steps {
                my_span([spanAttribute(key: "test.tool", value: "junit")]) {
                    // TODO sequence of shell steps to `git`+ fetch git submodules
                    // Get some code from a GitHub repository
                    // git credentialsId: 'my-user-git', url: 'https://github.com/jglick/simple-maven-project-with-tests.git'
                }
            }
        }
        stage('Build') {
            steps {
                ...
            }
        }
    }
}

[kuisathaverat]

I am wrong; the functions and shared library steps do not create a new span. I will review if it is possible to generate a span there.

[roeycarmi]

Hello, I am really looking forward the ability to create my own spans while still being part of the auto genrated trace created by the plugin.

I followed the #84 PR for a long time and I don't understand why is it closed? Would mean a lot to my team, and thanks for everyone involved :)

[xBis7]

Hi @cyrille-leclerc @v1v, I would like to pick up PR #84 if it's ok with you.

I see that the PR was based on an older version of the plugin and that the implementation needs to be updated. I don't know if there has been an issue with the PR approach.

I have some suggestions and questions

• The step could be named withNewSpan to be consistent with withSpanAttributes and withSpanAttribute
• The new step can reuse the SpanAttributeStepExecution
• Attributes will be specified by the user, in the same way as in withSpanAttributes, do you agree?
• Should a new span be allowed without attributes being specified?

[kuisathaverat]

Feel free to open the PR, we will review it ñ.

[xBis7]

@kuisathaverat Thanks! I'll create a PR and tag you, once the code is ready for review.

[xBis7]

PR https://github.com/jenkinsci/opentelemetry-plugin/pull/956 is ready for review. @cyrille-leclerc @kuisathaverat could you please take a look?

[tabathad]

Our organization is keen to have this capability and we're happy to assist in moving it forward. Let us know if there's anything specific we can help with to get this across the finish line.

[kuisathaverat]

Our organization is keen to have this capability and we're happy to assist in moving it forward. Let us know if there's anything specific we can help with to get this across the finish line.

Nothing blocks you from using it; you can use the incremental version from the PR.

[kuisathaverat]

released as https://github.com/jenkinsci/opentelemetry-plugin/releases/tag/3.1419.v3b_27ca_911066

[roeycarmi]

Should add documentation to: https://www.jenkins.io/doc/pipeline/steps/opentelemetry/

[kuisathaverat]

Should add documentation to: https://www.jenkins.io/doc/pipeline/steps/opentelemetry/

IFAIR that documentation is generated from the plugin classes, so at some point, it will be updated.