InfluxDB

Version: 2.5Minimum Jenkins requirement: 2.195ID: influxdb
Installs: 2158
Last released:
Maintainers
Aleksi Simell

Jenkins Plugin Jenkins.io Build Status Jenkins Plugin Installs

Description

Collects data from various other Jenkins plugins and sends metrics to InfluxDB. It's also possible to send custom data inside pipeline jobs.

⚠️ From version 1.13 onwards different plugins are listed as optional dependencies. In order to get rid of mandatory dependency errors, the InfluxDB plugin must be re-installed.

⚠️ Breaking changes in 2.0

  • From version 2.0 onwards selectedTarget is a mandatory parameter for pipelines and the target parameter is no longer supported.
  • Configuration As Code: the configuration needs to be changed from influxDbPublisher to influxDbGlobalConfig.
  • Might cause issues when creating new targets in pipelines. The InfluxDbPublisher instance is now under jenkinsci.plugins.influxdb.InfluxDbStep.DescriptorImpl.

Configuration

Configuration as Code

To configure InfluxDB plugin in Jenkins add the following to jenkins.yaml:

unclassified:
  influxDbGlobalConfig:
    targets:
    - database: "some_database"
      description: "some description"
      exposeExceptions: true
      globalListener: true
      globalListenerFilter: "some filter"
      jobScheduledTimeAsPointsTimestamp: true
      password: "some password"
      retentionPolicy: "some_policy"
      url: "http://some/url"
      username: "some username"
      usingJenkinsProxy: true

Via Jenkins UI

Create a database in InfluxDB and a user with access rights. In Jenkins, go to Manage Jenkins > Configure System > InfluxDB Targets and click "Add". Provide the database information. The "URL" parameter requires the whole URL of the InfluxDB database, including the http(s):// and the database port. Also, provide the retention policy you want the data to be stored in InfluxDB (e.g. 15m or 2d). By default, it is infinite. Exceptions generated by the InfluxDB plugin can also be ignored by deselecting the "Expose Exceptions" checkbox.

In your job, select "Publish build data to InfluxDB" from the post-build actions.

Via Jenkins Pipeline

From version 1.19 onwards, you can create and remove targets in pipelines directly.

// Get InfluxDB plugin descriptor (version < 2.0)
def influxdb = Jenkins.instance.getDescriptorByType(jenkinsci.plugins.influxdb.DescriptorImpl)

// version >= 2.0
def influxdb = Jenkins.instance.getDescriptorByType(jenkinsci.plugins.influxdb.InfluxDbStep.DescriptorImpl)

// Create target
def target = new jenkinsci.plugins.influxdb.models.Target()

// Set target details

// Mandatory fields
target.description = 'my-new-target'
target.url = 'http://influxdburl:8086'
target.username = 'my-username'

// version < 2.0
target.password = 'my-password'

// version >= 2.0
target.password = hudson.util.Secret.fromString('my-password')

target.database = 'my-database'

// Optional fields
target.retentionPolicy = '1d'                    // default = 'autogen'
target.jobScheduledTimeAsPointsTimestamp = true  // default = false
target.exposeExceptions = true                   // default = true
target.usingJenkinsProxy = true                  // default = false

// Add a target by using the created target object
influxdb.addTarget(target)
influxdb.save()

// Write stuff to InfluxDB
influxDbPublisher(selectedTarget: 'my-new-target')

// Remove a target by using the target description field value
influxdb.removeTarget('my-new-target')
influxdb.save()

Usage

Global Listener

When globalListener is set to true for a target in which no results were published during the build, it will automatically publish the result for this target when the build is completed.

To configure the global listener, you can use environment variables prefixed with INFLUXDB_PLUGIN. The following variables are supported and all correspond to an influxDbPublisher optional parameter.

  • INFLUXDB_PLUGIN_CUSTOM_PROJECT_NAME -> customProjectName
  • INFLUXDB_PLUGIN_CUSTOM_PREFIX -> customPrefix
  • INFLUXDB_PLUGIN_CUSTOM_FIELDS -> jenkinsEnvParameterField
  • INFLUXDB_PLUGIN_CUSTOM_TAGS -> jenkinsEnvParameterTag

NOTE: The environment variables must be set on the final build object. If you are creating or updating these variables in a pipeline, you should make sure they are exported with an EnvironmentContributingAction.

Freestyle Jobs

Select the InfluxDB target you wish to publish the data to.

From the "Advanced" tab you can choose to set a custom prefix for your project_name field, a custom project name to be used instead of the default job name, custom fields for your jenkins_data metric, and custom tags for your all your metrics.

Pipelines

The plugin can be used by calling either the influxDbPublisher() or the step() function.

NOTE: The influxDbPublisher() function is only supported from version 1.21 onwards.

Pipeline syntax

The only mandatory parameter is selectedTarget, which is the "Description" for your target in the global configuration.

influxDbPublisher(selectedTarget: 'my-target')
step([$class: 'InfluxDbPublisher', selectedTarget: 'my-target'])

Optional parameters

  • customProjectName (String) - custom project name
  • customPrefix (String) - custom prefix for project name
  • customData (Map) - custom fields in "jenkins_custom_data" measurement
  • customDataTags (Map) - custom tags in "jenkins_custom_data" measurement
  • customDataMap (Map) - custom fields in custom measurements
  • customDataMapTags (Map) - custom tags in custom measurements (map of tags for each custom measurements)
  • jenkinsEnvParameterField (String) - custom fields in "jenkins_data" measurement (newline-separated KEY=VALUE pairs)
  • jenkinsEnvParameterTag (String) - custom tags in all measurements (newline-separated KEY=VALUE pairs)
  • measurementName (String) - custom measurement name (replaces default "jenkins_data" and "jenkins_custom_data")

All customData* parameters contain custom data generated during the build and not by the plugin, so they are not available in the snippet generator.

NOTE! Up to release 1.10.3, pipeline was configured with using the url and database.

step([$class: 'InfluxDbPublisher',
       target: 'http://127.0.0.1:8086,jenkins_db',
       ...
   ])

This form of configuration is not supported from version 1.11 onwards.

Pipelines don't have post-build actions, so the build result, build ordinal, and the build success boolean will default to "?", 5, and false respectively, unless set manually before calling InfluxDbPublisher. Only the build result needs to be set manually, as the boolean value and ordinal are set based on build result. Also, the build status will appear as "?" and the build duration might be a little off, because the build is not actually finished. If you want to get those pieces of information you need to configure the plugin separately on each job as a post-build action. The jobs can be run with, for example, the Build Pipeline Plugin to get data from all jobs to InfluxDB. Alternatively, you can insert the information in your build manually inside your Groovy script.

try {
    // Build things here
    if (currentBuild.result == null) {
        currentBuild.result = 'SUCCESS' // sets the ordinal as 0 and boolean to true
    }
} catch (err) {
    if (currentBuild.result == null) {
        currentBuild.result = 'FAILURE' // sets the ordinal as 4 and boolean to false
    }
    throw err
} finally {
    influxDbPublisher(selectedTarget: 'my-target')
}

Custom Data

You can write custom data to InfluxDB like this:

def myFields = [:]
myFields['field_a'] = 11
myFields['field_b'] = 12
influxDbPublisher(selectedTarget: 'my-target', customData: myFields)

This adds the fields field_a and field_b with values 11 and 12 respectively to a measurement called jenkins_custom_data.

You can also add tags to this measurement with the customDataTags parameter.

Alternatively, you can write custom data to InfluxDB with a higher degree of customization like this:

def myFields1 = [:]
def myFields2 = [:]
def myCustomMeasurementFields = [:]
myFields1['field_a'] = 11
myFields1['field_b'] = 12
myFields2['field_c'] = 21
myFields2['field_d'] = 22
myCustomMeasurementFields['series_1'] = myFields1
myCustomMeasurementFields['series_2'] = myFields2
myTags = ['series_1':['tag_a':'a','tag_b':'b'],'series_2':['tag_c':'c','tag_d':'d']]
influxDbPublisher(selectedTarget: 'my-target', customDataMap: myCustomMeasurementFields, customDataMapTags: myTags)

This creates 2 measurements, series_1 and series_2. It adds the fields field_a and field_b with values 11 and 12 respectively to measurement series_1. It adds the fields field_c and field_d with values 21 and 22 respectively to measurement series_2.

You can also add tags to your custom measurements with the customDataMapTags parameter. You must use the same map keys as measurement names as in customDataMap.

Supported Metrics

All measurements share the following metrics:

Metric Type Description Introduced in
build_number integer Build number
project_name string Build name
project_path string Build path 1.15

All measurements share the following tags:

Tag Description Introduced in
project_name Build name
project_path Build path 2.0
* All values from JenkinsEnvParameterTag 2.1

No extra plugin needed

jenkins_data

Metric Type Description Introduced in
build_agent_name string Name of the executor node 1.15
build_branch_name string Branch name of multibranch pipeline 2.4
build_causer string Short description of build causer 2.4
build_exec_time integer Start time of the build 1.17
build_measured_time integer Time when InfluxDB plugin is called 1.17
build_result string SUCCESS, FAILURE, NOT BUILT, UNSTABLE, ABORTED, ? 1.10
build_result_ordinal integer 0-5 in order of build_result. 5 is only for pipelines if build result is not set manually. 1.10
build_scheduled_time integer Time when build was scheduled to run 1.17
build_status_message string Status message (stable, back to normal, broken since #50, etc.)
build_successful boolean Boolean whether build succeeded 1.10
build_time integer Build execution time
last_stable_build integer Build number of the last stable build (0 if never) 1.10
last_successful_build integer Build number of the last successful build (0 if never) 1.10
project_build_health integer Health score from build
tests_failed integer Amount of failed unit tests (from JUnit plugin)
tests_skipped integer Amount of skipped unit tests (from JUnit plugin)
tests_total integer total amount of unit tests (from JUnit plugin)
time_in_queue integer Time build was in queue (from Metrics plugin 1.16

Tags specific for this measurement:

Tag Description Introduced in
build_result Build result 1.15

changelog_data (since 1.12)

Metric Type Description Introduced in
affected_paths string Comma-separated list of changed files
commit_count integer Amount of commits since last change set
commit_messages string Comma-separated list of commit messages
culprits string Comma-separated list of commit authors

junit_data (since 2.3)

In order to publish data for this measurement, your job needs to set an environment variable LOG_JUNIT_RESULTS to true.

Metric Type Description Introduced in
suite_name string Testsuite name
test_name string Test name
test_status string PASSED, SKIPPED, FAILED, FIXED, REGRESSION
test_status_ordinal integer 0-4 in order of test_status
test_duration float test duration in seconds

Tags specific for this measurement:

Tag Description Introduced in
suite_name Testsuite name
test_name Test name
test_status Test result

sonarqube_data (since 1.11)

Metric Type Description Introduced in
alert_status string State of the Quality Gate 2.4
blocker_issues float Total amount of blocker issues
branch_coverage float Branch coverage 2.2
bugs float Total amount of bugs 2.2
code_smells float Total amount of code smells 2.2
complexity float Total amount of complexity 2.2
coverage float Overall coverage 2.2
critical_issues float Total amount of critical issues
display_name string Build display name
duplicated_lines_density float Percentage of duplicated lines 2.2
info_issues float Total amount of info issues
line_coverage float Line coverage 2.2
lines_of_code float (integer until 2.2) Total amount of lines (including comments)
lines_to_cover float Total amount of lines to cover (excluding comments) 2.2
major_issues float Total amount of major issues
minor_issues float Total amount of minor issues
vulnerabilities float Total amount of vulnerabilities 2.2
sqale_index float Technical Debt 2.4
sqale_debt_ratio float Technical Debt Ratio 2.4

Cobertura plugin

cobertura_data

Metric Type Description Introduced in
cobertura_branch_coverage_rate float Branch coverage percentage
cobertura_class_coverage_rate float Class coverage percentage
cobertura_line_coverage_rate float Line coverage percentage
cobertura_number_of_classes float Amount of classes
cobertura_number_of_packages float Amount of packages
cobertura_number_of_sourcefiles float Amount of source files
cobertura_package_coverage_rate float Package coverage percentage

JaCoCo plugin

jacoco_data (since 1.7)

Metric Type Description Introduced in
jacoco_brach_coverage_rage float Branch coverage percentage
jacoco_brach_covered integer Amount of branches covered 2.1
jacoco_brach_missed integer Amount of branches missed 2.1
jacoco_class_coverage_rage float Class coverage percentage
jacoco_class_covered integer Amount of classes covered 2.1
jacoco_class_missed integer Amount of classes missed 2.1
jacoco_complexity_coverage_rage float Complexity coverage percentage
jacoco_complexity_covered integer Amount of complexity covered 2.1
jacoco_complexity_missed integer Amount of complexity missed 2.1
jacoco_instruction_coverage_rage float Instruction coverage percentage
jacoco_instruction_covered integer Amount of instructions covered 2.1
jacoco_instruction_missed integer Amount of instructions missed 2.1
jacoco_line_coverage_rage float Line coverage percentage
jacoco_line_covered integer Amount of lines covered 2.1
jacoco_line_missed integer Amount of lines missed 2.1
jacoco_method_coverage_rage float Method coverage percentage
jacoco_method_covered integer Amount of methods covered 2.1
jacoco_method_missed integer Amount of methods missed 2.1

Performance plugin

performance_data (since 1.10.1)

Metric Type Description Introduced in
90percentile integer Point when 90 percentile was reached 1.12
average float Average performance (total duration / size)
error_count integer Amount of failed samples
error_percent integer Percentage of failed samples
max integer Maximum duration
median integer Median duration 1.12
min integer Minimum duration
size integer Amount of samples
total_traffic integer Total traffic in KB

Performance publisher plugin

perfpublisher_metric (since 1.13)

Metric Type Description Introduced in
average float Average value
best float Best value
metric_name string Metric name
worst float Worst value

perfpublisher_summary (since 1.13)

Metric Type Description Introduced in
average_compile_time float Average compilation test time
average_execution_time float Average execution test time
average_performance_time float Average performance test time
best_compile_time_test_name string Best compilation time test name
best_compile_time_test_value float Best compilation time test value
best_performance_time_test_name string Best performance time test name
best_performance_test_value float Best performance test value
best_execution_time_test_name string Best execution time test name
best_execution_time_test_value float Best execution time test value
number_of_executed_tests integer Amount of executed tests
number_of_failed_tests integer Amount of failed tests
number_of_not_executed_tests integer Amount of not executed tests
number_of_passed_tests integer Amount of passed tests
number_of_success_tests integer Amount of succeeded tests
number_of_tests integer Total amount of tests
number_of_true_false_tests integer Amount of true-false tests
worst_compile_time_test_name string Worst compilation time test name
worst_compile_time_test_value float Worst compilation time test value
worst_performance_time_test_name string Worst performance time test name
worst_performance_time_test_value float Worst performance time test value
worst_execution_time_test_name string Worst execution time test name
worst_execution_time_test_value float Worst execution time test value

perfpublisher_test (since 1.13)

Metric Type Description Introduced in
executed boolean Was test executed
execution_time float Test execution time
compile_time float Test compilation time
message boolean Test message
performance float Test performance
successful boolean Was test successful
test_name string Test name

Tags specific for this measurement:

Tag Description Introduced in
test_name Test name

perfpublisher_test_metric (since 1.13)

Metric Type Description Introduced in
metric_name string Test metric name
relevant boolean Is metric relevant
test_name string Test name
value float Metric value
unit string Metric unit

Tags specific for this measurement:

Tag Description Introduced in
test_name Test name

Robot Framework plugin

rf_results

Metric Type Description Introduced in
rf_critical_failed integer Amount of failed critical tests
rf_critical_pass_percentage float Percentage of passed critical tests
rf_critical_passed integer Amount of passed critical tests
rf_critical_total integer Total amount of critical tests
rf_duration integer Test execution duration
rf_failed integer Amount of failed tests
rf_pass_percentage float Percentage of passed tests
rf_passed integer Amount of passed tests
rf_suites integer Amount of test suites
rf_total integer Total amount of tests

suite_result

Metric Type Description Introduced in
rf_critical_failed integer Amount of failed critical tests
rf_critical_passed integer Amount of passed critical tests
rf_critical_total integer Total amount of critical tests
rf_duration integer Test execution duration
rf_failed integer Amount of failed tests
rf_passed integer Amount of passed tests
rf_suite_name string Name of the test suite
rf_testcases integer Total amount of tests (including child suites)
rf_total integer Amount of tests in this suite

Tags specific for this measurement:

Tag Description Introduced in
rf_suite_name Name of the test suite 1.20.1

tag_point

Metric Type Description Introduced in
rf_critical_failed integer Amount of failed critical tests
rf_critical_passed integer Amount of passed critical tests
rf_critical_total integer Total amount of critical tests
rf_duration integer Test execution duration
rf_failed integer Amount of failed tests
rf_passed integer Amount of passed tests
rf_total integer Total amount of tests
rf_tag_name string Test tag name 1.20.1

Tags specific for this measurement:

Tag Description Introduced in
rf_tag_name Tag name 1.20.1

testcase_point

Metric Type Description Introduced in
rf_critical_failed integer 0 or 1
rf_critical_passed integer 0 or 1
rf_duration integer Test case execution duration
rf_failed integer 0 or 1
rf_name string Name of the test case
rf_passed integer 0 or 1
rf_suite_name string Name of the suite of the test case

Tags specific for this measurement:

Tag Description Introduced in
rf_name Name of the test case 1.20.1

Serenity plugin

serenity_data (since 2.1)

Metric Type Description Introduced in
serenity_results_average_test_duration integer Maximum average duration in milliseconds
serenity_results_counts_compromised integer Amount of compromised results
serenity_results_counts_error integer Amount of error results
serenity_results_counts_failure integer Amount of failed results
serenity_results_counts_ignored integer Amount of ignored results
serenity_results_counts_pending integer Amount of pending results
serenity_results_counts_skipped integer Amount of skipped results
serenity_results_counts_success integer Amount of success results
serenity_results_counts_total integer Total amount of results
serenity_results_max_test_duration integer Maximum test duration in milliseconds
serenity_results_min_test_duration integer Minimum test duration in milliseconds
serenity_results_percentages_compromised integer Percentage of compromised results
serenity_results_percentages_error integer Percentage of error results
serenity_results_percentages_failure integer Percentage of failure results
serenity_results_percentages_ignored integer Percentage of ignored results
serenity_results_percentages_pending integer Percentage of pending results
serenity_results_percentages_skipped integer Percentage of skipped results
serenity_results_percentages_success integer Percentage of success results
serenity_results_total_clock_duration integer Total test clock duration in milliseconds
serenity_results_total_test_duration integer Total test duration in milliseconds
serenity_tags_* integer Amount of tests for each tag

Contribution

Create a pull request to the development branch. No pull requests are merged directly to master. Comment your changes sufficiently and create appropriate tests.

If you have an idea for a new feature or you want to report a bug, please use the Jenkins issue tracker.

ArchivesGet past versions
Links
Labels

Previous Security Warnings