Package io.jenkins.plugins.dorametrics.store

Class MetricsStore

java.lang.Object

io.jenkins.plugins.dorametrics.store.MetricsStore

public class MetricsStore
extends Object

SQLite embedded database for storing build metrics. Located at JENKINS_HOME/pipeline-dora-metrics/metrics.db

Nested Class Summary

Nested Classes

Modifier and Type	Class	Description
static class	MetricsStore.BuildRecord
static final class	MetricsStore.CommitRow	A commit to write alongside its build.
static class	MetricsStore.JobStats
static class	MetricsStore.StageRecord
static final class	MetricsStore.StageRow	A stage to write alongside its build.
static class	MetricsStore.StageStats

Field Summary

Fields

Modifier and Type	Field	Description
static final String	DELETED_MARKER	Marks records of a deleted job.

Method Summary

Modifier and Type	Method	Description
double	avgLeadTimeMs(long fromMs, long toMs, String jobPattern)
double	avgLeadTimeMs(long fromMs, long toMs, String jobPattern, Set<String> excludedJobs)
double	avgLeadTimeMs(long fromMs, long toMs, String jobPattern, Set<String> excludedJobs, String branchPattern)	Average lead time of the successful builds in the window, as the time from the earliest commit that build deployed until it finished.
void	cleanup(long retainAfterTimestamp)
long	countDeployments(long fromMs, long toMs, String jobPattern, Set<String> excludedJobs, String branchPattern)	Builds that ran as a deployment, successfully or not: SUCCESS, UNSTABLE or FAILURE.
long	countFailedBuilds(long fromMs, long toMs, String jobPattern)
long	countFailedBuilds(long fromMs, long toMs, String jobPattern, Set<String> excludedJobs)
long	countFailedBuilds(long fromMs, long toMs, String jobPattern, Set<String> excludedJobs, String branchPattern)	As above, counting only builds on a branch matching branchPattern, or all when it is null.
long	countSuccessfulBuilds(long fromMs, long toMs, String jobPattern)
long	countSuccessfulBuilds(long fromMs, long toMs, String jobPattern, Set<String> excludedJobs)
long	countSuccessfulBuilds(long fromMs, long toMs, String jobPattern, Set<String> excludedJobs, String branchPattern)	As above, counting only builds on a branch matching branchPattern, or all when it is null.
long	countTotalBuilds(long fromMs, long toMs, String jobPattern)
long	countTotalBuilds(long fromMs, long toMs, String jobPattern, Set<String> excludedJobs)
long	countTotalBuilds(long fromMs, long toMs, String jobPattern, Set<String> excludedJobs, String branchPattern)	As above, counting only builds on a branch matching branchPattern, or all when it is null.
void	detachDeletedJob(String fullName, long deletedAtMs)	Detaches the records of a deleted job, and of everything below it when it was a folder, from the job name.
Map<String,Long>	failureStreaksOpenAt(long beforeMs, Set<String> excludedJobs, String branchPattern)	For every job whose failures had not been fixed yet at beforeMs, when its run of failures began: the earliest FAILURE after that job's last SUCCESS before that moment.
List<MetricsStore.BuildRecord>	getAllBuilds(long fromTimestamp, long toTimestamp)
List<MetricsStore.BuildRecord>	getAllBuilds(long fromTimestamp, long toTimestamp, Set<String> excludedJobs)	All builds in the window, leaving out the given job names.
List<String>	getAllJobNames()
List<MetricsStore.BuildRecord>	getBuilds(String jobName, long fromTimestamp, long toTimestamp)
List<MetricsStore.BuildRecord>	getBuildsFinishedBetween(long afterMs, long untilMs, Set<String> excludedJobs)	Builds that finished after afterMs and no later than untilMs, leaving out the given job names.
long	getEarliestCommitTimestamp(long buildId)
static MetricsStore	getInstance()
List<MetricsStore.JobStats>	getJobStats(long fromMs, long toMs, int limit, String orderBy)
List<MetricsStore.JobStats>	getJobStats(long fromMs, long toMs, int limit, String orderBy, Set<String> excludedJobs)
List<MetricsStore.StageRecord>	getStages(long buildId)
Map<Long,List<MetricsStore.StageRecord>>	getStagesByBuild(Collection<Long> buildIds)	The stages of many builds at once, keyed by build id, each list in recorded order.
List<MetricsStore.StageStats>	getStageStats(long fromMs, long toMs, int limit, String orderBy)
List<MetricsStore.StageStats>	getStageStats(long fromMs, long toMs, int limit, String orderBy, Set<String> excludedJobs)
long	insertBuild(String jobName, int buildNumber, long timestamp, long durationMs, String result, String triggerType, String branch)	Upserts the build row and clears the stages and commits recorded against it, returning its id so they can be written back.
void	insertCommit(long buildId, String sha, String author, long timestamp)
void	insertStage(long buildId, String stageName, long durationMs, String result)
static boolean	isOnBranch(MetricsStore.BuildRecord build, String branchPattern)	Whether a build's branch passes the same test as branchCondition(java.lang.String, java.lang.String), for the metrics that are worked out row by row.
List<long[]>	leadTimes(long fromMs, long toMs, String jobPattern, Set<String> excludedJobs, String branchPattern)	The lead time of each successful build in the window, as [build start, lead time], worked out as avgLeadTimeMs(long, long, String, Set, String) describes.
long	recordBuild(String jobName, int buildNumber, long timestamp, long durationMs, String result, String triggerType, String branch, List<MetricsStore.StageRow> stages, List<MetricsStore.CommitRow> commits)	Writes one build and the stages and commits belonging to it, in a single transaction.
void	renameJob(String oldName, String newName)	Moves a job's records to its new name.
static void	setInstance(MetricsStore store)	Reset singleton.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Details

DELETED_MARKER

public static final String DELETED_MARKER

Marks records of a deleted job. '@' is not allowed in a Jenkins item name.

See Also:

• Constant Field Values

Method Details

getInstance

public static MetricsStore getInstance()

setInstance

public static void setInstance(MetricsStore store)

Reset singleton. Used by tests to reinitialize with fresh Jenkins home.

recordBuild

public long recordBuild(String jobName,
 int buildNumber,
 long timestamp,
 long durationMs,
 String result,
 String triggerType,
 String branch,
 List<MetricsStore.StageRow> stages,
 List<MetricsStore.CommitRow> commits)

Writes one build and the stages and commits belonging to it, in a single transaction.

The build row is upserted rather than replaced. INSERT OR REPLACE deletes the conflicting row and inserts a new one, which hands out a new id, and since the foreign keys on stages and commits are not enforced their old rows are left pointing at an id that no longer exists. Nothing deletes those afterwards, including retention, which looks its children up through their parent. Keeping the id and replacing the children explicitly is what stops them accumulating.

The id comes from RETURNING because getGeneratedKeys reports 0 after an upsert that updates rather than inserts.

Returns:

the build's id, or -1 if nothing was written

insertBuild

public long insertBuild(String jobName,
 int buildNumber,
 long timestamp,
 long durationMs,
 String result,
 String triggerType,
 String branch)

Upserts the build row and clears the stages and commits recorded against it, returning its id so they can be written back.

Prefer recordBuild(java.lang.String, int, long, long, java.lang.String, java.lang.String, java.lang.String, java.util.List<io.jenkins.plugins.dorametrics.store.MetricsStore.StageRow>, java.util.List<io.jenkins.plugins.dorametrics.store.MetricsStore.CommitRow>) where the stages and commits are already known: it writes all three in one transaction, so the build is never briefly left without them.

Returns:

the build's id, or -1 if nothing was written

insertStage

public void insertStage(long buildId,
 String stageName,
 long durationMs,
 String result)

insertCommit

public void insertCommit(long buildId,
 String sha,
 String author,
 long timestamp)

getBuilds

public List<MetricsStore.BuildRecord> getBuilds(String jobName,
 long fromTimestamp,
 long toTimestamp)

getAllBuilds

public List<MetricsStore.BuildRecord> getAllBuilds(long fromTimestamp,
 long toTimestamp)

getAllBuilds

public List<MetricsStore.BuildRecord> getAllBuilds(long fromTimestamp,
 long toTimestamp,
 Set<String> excludedJobs)

All builds in the window, leaving out the given job names.

failureStreaksOpenAt

public Map<String,Long> failureStreaksOpenAt(long beforeMs,
 Set<String> excludedJobs,
 String branchPattern)

For every job whose failures had not been fixed yet at beforeMs, when its run of failures began: the earliest FAILURE after that job's last SUCCESS before that moment. Lets a recovery inside a window be measured from a failure that started before it.

getBuildsFinishedBetween

public List<MetricsStore.BuildRecord> getBuildsFinishedBetween(long afterMs,
 long untilMs,
 Set<String> excludedJobs)

Builds that finished after afterMs and no later than untilMs, leaving out the given job names. A build is stored when it finishes, so this is what an export that ran at afterMs could not have seen yet, however long before that the build started.

getAllJobNames

public List<String> getAllJobNames()

getEarliestCommitTimestamp

public long getEarliestCommitTimestamp(long buildId)

getStages

public List<MetricsStore.StageRecord> getStages(long buildId)

getStagesByBuild

public Map<Long,List<MetricsStore.StageRecord>> getStagesByBuild(Collection<Long> buildIds)

The stages of many builds at once, keyed by build id, each list in recorded order. One query per few hundred builds instead of one per build, which is what made exporting a month of history slow.

countSuccessfulBuilds

public long countSuccessfulBuilds(long fromMs,
 long toMs,
 String jobPattern)

countSuccessfulBuilds

public long countSuccessfulBuilds(long fromMs,
 long toMs,
 String jobPattern,
 Set<String> excludedJobs)

countSuccessfulBuilds

public long countSuccessfulBuilds(long fromMs,
 long toMs,
 String jobPattern,
 Set<String> excludedJobs,
 String branchPattern)

As above, counting only builds on a branch matching branchPattern, or all when it is null.

countTotalBuilds

public long countTotalBuilds(long fromMs,
 long toMs,
 String jobPattern)

countTotalBuilds

public long countTotalBuilds(long fromMs,
 long toMs,
 String jobPattern,
 Set<String> excludedJobs)

countTotalBuilds

public long countTotalBuilds(long fromMs,
 long toMs,
 String jobPattern,
 Set<String> excludedJobs,
 String branchPattern)

As above, counting only builds on a branch matching branchPattern, or all when it is null.

countDeployments

public long countDeployments(long fromMs,
 long toMs,
 String jobPattern,
 Set<String> excludedJobs,
 String branchPattern)

Builds that ran as a deployment, successfully or not: SUCCESS, UNSTABLE or FAILURE. An aborted build, one that was never built, or one with no result deployed nothing.

countFailedBuilds

public long countFailedBuilds(long fromMs,
 long toMs,
 String jobPattern)

countFailedBuilds

public long countFailedBuilds(long fromMs,
 long toMs,
 String jobPattern,
 Set<String> excludedJobs)

countFailedBuilds

public long countFailedBuilds(long fromMs,
 long toMs,
 String jobPattern,
 Set<String> excludedJobs,
 String branchPattern)

As above, counting only builds on a branch matching branchPattern, or all when it is null.

avgLeadTimeMs

public double avgLeadTimeMs(long fromMs,
 long toMs,
 String jobPattern)

avgLeadTimeMs

public double avgLeadTimeMs(long fromMs,
 long toMs,
 String jobPattern,
 Set<String> excludedJobs)

avgLeadTimeMs

public double avgLeadTimeMs(long fromMs,
 long toMs,
 String jobPattern,
 Set<String> excludedJobs,
 String branchPattern)

Average lead time of the successful builds in the window, as the time from the earliest commit that build deployed until it finished. A changelog only lists what changed since the build before, so a commit first built by a build that failed or was aborted is in that build's changelog, not in the deploying one's. Every build since the job's previous success therefore counts toward the next success. Only builds on a production branch take part when branchPattern is set.

leadTimes

public List<long[]> leadTimes(long fromMs,
 long toMs,
 String jobPattern,
 Set<String> excludedJobs,
 String branchPattern)

The lead time of each successful build in the window, as [build start, lead time], worked out as avgLeadTimeMs(long, long, String, Set, String) describes.

getJobStats

public List<MetricsStore.JobStats> getJobStats(long fromMs,
 long toMs,
 int limit,
 String orderBy)

getJobStats

public List<MetricsStore.JobStats> getJobStats(long fromMs,
 long toMs,
 int limit,
 String orderBy,
 Set<String> excludedJobs)

getStageStats

public List<MetricsStore.StageStats> getStageStats(long fromMs,
 long toMs,
 int limit,
 String orderBy)

getStageStats

public List<MetricsStore.StageStats> getStageStats(long fromMs,
 long toMs,
 int limit,
 String orderBy,
 Set<String> excludedJobs)

isOnBranch

public static boolean isOnBranch(MetricsStore.BuildRecord build,
 String branchPattern)

Whether a build's branch passes the same test as branchCondition(java.lang.String, java.lang.String), for the metrics that are worked out row by row.

renameJob

public void renameJob(String oldName,
 String newName)

Moves a job's records to its new name. Rows already stored under the new name belong to a job that is gone, since the name was free until now, so they are detached first, in the same transaction, instead of being merged into this job's history or making the rename fail on the unique key.

detachDeletedJob

public void detachDeletedJob(String fullName,
 long deletedAtMs)

Detaches the records of a deleted job, and of everything below it when it was a folder, from the job name. The history stays in the totals that administrators and the scheduled export see, but a new job created under the same name starts empty instead of inheriting it.

cleanup

public void cleanup(long retainAfterTimestamp)