Telemetry
|
This site is the new docs site currently being tested. For the actual docs in use please go to https://www.jenkins.io/doc. |
Overview
Jenkins is exclusively distributed to users for installation on their own infrastructure. This presents challenges when evolving Jenkins, as we typically only learn about problems after a change has been delivered. JEP-214 defines infrastructure for gathering usage telemetry.
| Telemetry needs to be suitable for a given information need. We do not want to collect just everything we can think of, instead, data collection is limited both in duration (typically a few months) and scope (collecting very specific, limited, bits of data). See JEP-214 for more details about these considerations. |
Telemetry Development
Implementation
In Jenkins core or a plugin, implement the jenkins.telemetry.Telemetry extension point and annotate your implementation @Extension.
Make sure to add a description.jelly view that documents the information need.
Existing implementations in Jenkins core (and their resources) can be used as a guideline.
Local Testing
You can inspect telemetry data locally by calling ExtensionList.lookupSingleton(package.to.YourTelemetry.class).createContent() in the script console (careful, as this typically will modify state).
Alternatively, you can set the jenkins.telemetry.Telemetry.endpoint Java system property on startup (or set jenkins.telemetry.Telemetry.ENDPOINT in the script console) to a test HTTP server that lets you inspect HTTP requests and their POST bodies.
To trigger telemetry submission, you can call ExtensionList.lookupSingleton(jenkins.telemetry.Telemetry.TelemetryReporter.class).run() in the script console.
Uplink Access
Request access to Uplink in the INFRA Jira project. This should best be done before the telemetry change is released or even merged, as the collected data and other parameters will be reviewed (if the telemetry collection is in a plugin).
Backporting (Jenkins core)
As telemetry is time-sensitive, and the majority of users use LTS releases, telemetry implementations in core should generally be backported freely into LTS releases to ensure data is collected from as many up-to-date Jenkins instances as possible. The general LTS backporting rules are relaxed for telemetry-related changes.