OpenTelemetry

ID: opentelemetry

Build Status Contributors Jenkins Plugin GitHub release Jenkins Plugin Installs

Introduction

Collect Jenkins monitoring data through OpenTelemetry.

Architecture

Using the OpenTelemetry Collector, you can use many monitoring backends to monitor Jenkins such as Jaeger, Zipkin, Prometheus, Elastic Observability and many others listed here.

Here are few examples of architecture:

Jenkins monitoring with Elastic Observability Jenkins monitoring with Jaeger and Prometheus

Features

Monitoring and troubleshooting Jenkins jobs using distributed tracing

  • Understand where time is spent, including time spent waiting to schedule the job (time spent in the build queue)
    • The time spent in the built queue waiting for a build agent is visualised with the span "Phase : Start"
  • Detect increasing time spent in steps like
    • Invocations of external systems (e.g. git checkout...)
  • Built in integration with Elastic Observability, Jaeger, and Zipkin. Other OpenTelemetry compatible distributed tracing solutions are also supported.

Attributes

Transactions
Attribute Description Type
ci.pipeline.id Job name String
ci.pipeline.name Job name (user friendly) String
ci.pipeline.type Job type Enum (freestyle, workflow, multibranch, unknown)
ci.pipeline.multibranch.type Multibranch type Enum (branch, tag, change_request)
ci.pipeline.node.id Name of the node String
ci.pipeline.run.completed Is this a complete build? Boolean
ci.pipeline.run.durationMillis Build duration Long
ci.pipeline.run.description Build description String
ci.pipeline.run.number Build number Long
ci.pipeline.run.result Build result Enum (aborted, success, failure, not_build and unstable)
ci.pipeline.run.url Build URL String
ci.pipeline.run.user Who triggered the build String
ci.pipeline.parameter.sensitive Whether the information contained in this parameter is sensitive or security related. Boolean
ci.pipeline.parameter.name Name of the parameter String
ci.pipeline.parameter.value Value of the parameter String
Spans
Attribute Description Type
jenkins.pipeline.step.name Step name (user friendly) String
jenkins.pipeline.step.type Step name String
jenkins.pipeline.step.id Step id String
jenkins.pipeline.step.node.label Labels attached to the node String
git.branch Git branch name String
git.repository Git repository String
git.username Git user String
jenkins.url Jenkins URL String
jenkins.computer.name Name of the node String

Metrics on Jenkins health indicators

Metrics Description
ci.pipeline.run.active Gauge of active jobs
ci.pipeline.run.launched Job launched
ci.pipeline.run.started Job started
ci.pipeline.run.completed Job completed
ci.pipeline.run.aborted Job aborted
jenkins.queue.waiting Number of waiting items in queue
jenkins.queue.blocked Number of blocked items in queue
jenkins.queue.buildable Number of buildable items in queue
jenkins.queue.left Total count of left items
jenkins.queue.time_spent_millis Total time spent in queue by items
jenkins.agents.total Number of agents
jenkins.agents.online Number of online agents
jenkins.agents.offline Number of offline agents

Jenkins metrics can be visualised with any OpenTelemetry compatible metrics solution such as Prometheus or Elastic Observability

Getting started

  • Setup an OpenTelemetry endpoint such as the OpenTelemetry Collector
  • Install the Jenkins OpenTelemetry plugin
  • Configure the Jenkins OpenTelemetry plugin navigating to the "Manage Jenkins / Configure System" screen
  • In the OpenTelemetry section define
    • "OTLP GRPC Endpoint": the hostname and port of the OpenTelemetry GRPC Protocol (OTLP GRPC) endpoint, typically an OpenTelemetry Collector or directly an Observability backend that supports the OTLP GRPC protocol
    • "Header Authentication" : name of the authentication header if header based authentication is used.
    • "Bearer Token Authentication": Bearer token when using header based authentication.
    • Visualization: the backend used to visualize job executions as traces.
      • Elastic Observability
      • Jaeger
      • Zipkin
      • Custom Observability backend for other visualisation solution

Sample Configuration

Screenshots

Sample of traces collected for various flavors of pipelines

Scripted Pipeline

Scripted pipeline status page

node {
    stage('Prepare') {
        echo("Prepare")
    }
    stage('Build') {
        git 'https://github.com/jglick/simple-maven-project-with-tests.git'
        sh "mvn -Dmaven.test.failure.ignore=true clean package"
    }
    stage('Post Build') {
        echo("this is the post build phase")
    }
}

Scripted pipeline status page with Elastic Observability link

Scripted pipeline visualized with Elastic Observability

Scripted pipeline visualised with Elastic Observability

Scripted pipeline visualized with Jaeger

Scripted pipeline visualised with Jaeger

Scripted pipeline visualized with Zipkin

Scripted pipeline visualised with Jaeger

Declarative Pipeline

Declarative pipeline visualised with Elastic Observability

pipeline {
    agent any

    stages {
        stage('Build') {
            steps {
                git 'https://github.com/jglick/simple-maven-project-with-tests.git'
                sh "mvn -Dmaven.test.failure.ignore=true clean package"
            }
            post {
                success {
                    echo "success"
                }
            }
        }
    }
}

Scripted Pipeline with Error

scripted-pipeline-with-error

node {
    stage('Prepare') {
        echo("Prepare")
    }
    stage('Build') {
        git 'https://github.com/jglick/simple-maven-project-with-tests.git'
        sh "mvn -Dmaven.test.failure.ignore=true clean package"
    }
    stage('Post Build') {
        error 'Fail'
    }
}

Scripted Pipeline with Parallel Step

scripted-pipeline-with-parallel-step

node {
    stage('Prepare') {
        echo("Prepare")
    }
    stage('Build') {
        git 'https://github.com/jglick/simple-maven-project-with-tests.git'
        sh "mvn -Dmaven.test.failure.ignore=true clean package"
    }
    stage('Parallel Post Build') {
        parallel parallBranch1: {
            echo("this is the post build parallel branch 1")
        } ,parallBranch2: {
            echo("this is the post build parallel branch 2")
            echo("this is the post build parallel branch 2")
        }
    }
}

Freestyle Job

freestyle-job

Ideas

  • Collect labels of build agents
  • Detect outages caused by upgrades. Report on the version of the plugin of each plugin being used as a step

Configuration as code

This plugin supports configuration as code. Add to your yaml file:

unclassified:
  openTelemetry:
    authentication: "noAuthentication"
    endpoint: "otel-collector-contrib:4317"
    exporterIntervalMillis: 60000
    exporterTimeoutMillis: 30000
    ignoredSteps: "dir,echo,isUnix,pwd,properties"
    observabilityBackends:
      - elastic:
          kibanaBaseUrl: "http://localhost:5601"
      - jaeger:
          jaegerBaseUrl: "http://localhost:16686"
      - customObservabilityBackend:
          metricsVisualisationUrlTemplate: "foo"
          traceVisualisationUrlTemplate: "http://example.com"
      - zipkin:
          zipkinBaseUrl: "http://localhost:9411/"

See the jcasc folder with various samples.

For more details see the configuration as code plugin documentation: https://github.com/jenkinsci/configuration-as-code-plugin#getting-started

Contributing

Refer to our contribution guidelines

LICENSE

Licensed under Apache Software License 2, see LICENSE

ArchivesGet past versions
Version: 0.9
Released:
Requires Jenkins 2.235.1
Installs: 15
Maintainers
Cyrille Le Clerc
Help us improve this page!
To propose a change submit a pull request to the plugin page on GitHub.