Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/jenkinsci/influxdb-plugin

Jenkins plugin to send build metrics into InfluxDB
https://github.com/jenkinsci/influxdb-plugin

hacktoberfest

Last synced: about 1 month ago
JSON representation

Jenkins plugin to send build metrics into InfluxDB

Awesome Lists containing this project

README

        

# InfluxDB Plugin for Jenkins

[![Jenkins Plugin](https://img.shields.io/jenkins/plugin/v/influxdb.svg)](https://plugins.jenkins.io/influxdb)
[![Jenkins.io Build Status](https://ci.jenkins.io/buildStatus/icon?job=Plugins%2Finfluxdb-plugin%2Fmaster)](https://ci.jenkins.io/job/Plugins/job/influxdb-plugin/job/master/)
[![Jenkins Plugin Installs](https://img.shields.io/jenkins/plugin/i/influxdb.svg?color=blue)](https://plugins.jenkins.io/influxdb)

## Description

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

## Breaking Changes

Support for InfluxDB 1.7 and lower was dropped in plugin release 3.0.

You can find all breaking changes for each version in the [breaking changes documentation](doc/breaking_changes.md).

## Configuration

### Configuration as Code

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

```yaml
unclassified:
influxDbGlobalConfig:
targets:
- credentialsId: "some_id"
database: "some_database"
description: "some description"
exposeExceptions: true
globalListener: true
globalListenerFilter: "some filter"
jobScheduledTimeAsPointsTimestamp: true
retentionPolicy: "some_policy"
url: "http://some/url"
usingJenkinsProxy: true
```

> :warning: Prior 3.0, `credentialsId` needs to swapped to `username` and `password`.

### 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.

> :warning: When you are using InfluxDB 1.x targets, **leave the Organization blank**. InfluxDB 2.x
> uses organizations and buckets instead of databases and retention policies, so `organization` field is
> used as an identifier whether the target is InfluxDB 1.x or 2.x.

![Jenkins Configuration](doc/img/jenkins-configuration.png)

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

![Post build menu](doc/img/post-build-action.png)

### 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'

// Not supported >= 3.0
target.username = 'my-username'

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

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

// Version >= 3.0
target.credentialsId = 'my-id'

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()
```

### Credentials

- InfluxDB 1.8 targets support only `Username with password`.
- InfluxDB 2.x supports `Username with password` for basic authentication and `Secret Text` for authentication
token authentication.

## 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](https://javadoc.jenkins.io/hudson/model/EnvironmentContributingAction.html).

### Freestyle Jobs

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

![Select Target](doc/img/select-influxdb-target.png)

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.

![Advanced Options](doc/img/advanced-options.png)

### 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.

``` syntaxhighlighter-pre
influxDbPublisher(selectedTarget: 'my-target')
```

``` syntaxhighlighter-pre
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.

> :heavy_exclamation_mark: NOTE! Up to release 1.10.3, pipeline was configured with using the url and database.
>
>``` syntaxhighlighter-pre
>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](https://wiki.jenkins-ci.org/display/JENKINS/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.

``` syntaxhighlighter-pre
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

See all available metrics from the [available metrics documentation](doc/available_metrics.md).

## 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.

For feature requests and bug reports,
please use the [Jenkins issue tracker](https://issues.jenkins-ci.org/issues/?jql=project%20%3D%20JENKINS%20AND%20component%20%3D%20influxdb-plugin).

## Acknowledgements

This plugin was inspired by [Jouni Rajala](https://github.com/jrajala-eficode/jenkins-ci.influxdb-plugin)
and [Christoph Burmeister](http://christoph-burmeister.eu/?p=2906).