Measurements V1 (Deprecated)

Deprecation Oct 1st 2023

The LinearB measurements V1 API will be officially deprecated, and it will no longer be supported. We recommend completing the migration to the V2 API before this date to ensure uninterrupted service.

Customers of LinearB have the option to export Metrics data that has already been processed by the platform and leverage this information to:

Create custom reports
Export to other data visualization tools

Limitations

LinearB measurements API is currently limited to Git metrics
PM metrics like Velocity/Investment Profile/Time Distribution are not supported at this point.

Usage

The Measurements API is designed to operate in two steps.

In the first step, the request trigger the system to generate a report and provides the user back with a request ID. The system in the meanwhile generates a report and drops it as a CSV file in Amazon S3 bucket.
In the second step, the CSV file will be returned by submitting a request with the request ID from the first request

Info

If the request filter provided end up with no data, then also the system will not generate a report and provide a response with the code 204 (No Content).

The request is still in queue and the report not generated yet. You will get a RESPONSE CODE : 202 Accepted. The user/automation can try again to see if the response is 200 Ok, since that will indicate that a report is generated.

The request is processed and the system responds with the link for the generated report document.

The user/client can use the link from the second API call response and open that to get the JSON data, which they can then utilize in whichever way they want

Create measurements report

Will initialize measurements report creation flow, which will upload report to S3 bucket. Processing is on background, so user, who call this API will receive in the response status code, if the initialization process was started successfully and also a unique request ID, that will be used later to get S3 URL to download the report.

HTTP request

POST  https://public-api.linearb.io/api/v1/exporter/measurements

Body parameter

Property name	Value	Description
requested_metrics (required)	Array of strings	The list of metrics to export Valid values are: supported metrics
add_context	boolean	Add context
group_by	string	Field to group by Valid values are: "contributor", "repository", "team", "organization"
order_by	string	Field to order by
contributor_ids	Array of integers	The list of contributors This parameter must be passed if grouping by "contributor"
repository_ids	Array of integers	The list of repositories This parameter must be passed if grouping by "repository"
team_ids	Array of integers	The list of teams This parameter must be passed if grouping by "team"
service_ids	Array of integers	The list of services This parameter must be passed if grouping by "service"
before	string (timestamp ISO 8601 format)	Return measurements that occurred before this specific time Before should not be passed if time_ranges is passed. After should be passed with before
after	string (timestamp ISO 8601 format)	Return measurements that occurred after this specific time After should not be passed if time_ranges is passed. Before should be passed with after
time_ranges	Array of objects	Should not be passed if before and after are defined. Each time range should contain before and after. Example: [{"after": "2022-05-27", "before": "2022-05-29"},...]
limit	integer	Max amount of objects in the response. When request for multiple contributors, teams or repositories, limit should be more or equal of amount of passed ids (or data will be returned partially)
offset	integer	Used for pagination, defines the offset for the query
return_no_data	boolean	If true, then will return nullable values, otherwise,will drop them.
file_format	string	Defines the format of the output file Valid values are: "json" and "csv" (Default: "json")

Supported metrics

Name	Description	Units
branch.computed.cycle_time	Full cycle time (Coding time + Pickup time + Review time + Time to production)	min.
branch.time_to_pr	Coding time (Time to PR)	min.
branch.time_to_review	Pickup time (Time to review)	min.
branch.review_time	Review time	min.
branch.time_to_prod	Time to production (Time to deploy)	min.
pr.merged.size	The sum of PR sizes of merged PRs	lines of code
pr.merged	The number of PRs that got merged	count
pr.review_depth	The sum of comments divided by the sum of PRs	lines of comments
commit.activity.new_work.count	The total new lines of code	count
commit.total_changes	The total lines of code that have been replaced	lines of code
commit.activity.refactor.count	The total lines of code that have been replaced that are older then 25 days	lines of code
commit.activity.rework.count	The total lines of code that have replaced code written within the last 25 days, but outside this branch	lines of code
pr.merged.without.review.count	The number of PRs that got merged without review	count
commit.total.count	The sum of commits	count
pr.new	The number of opened PRs	count
pr.reviews	The number of reviews on all PRs	count
releases.count	The number of releases	count
commit.activity_days	The amount of day of developer activity (commit/comment/PR/merge/review)	days
branch.state.computed.done	Number of branches that reached state done	count
branch.state.active	Number of active branches	count
pm.issues.done	The number of issues (Jira/Shortcut) that reached a done state	count
pm.mttr	Mean time to repair	mim.
pm.issues.done.story_points	The total amount of story point of all done issues	count
pm.cfr.issues.done	The sum of issues that are considered as incidents that reached a done state	count

Examples

Create measurements report with time ranges

{
  "group_by": "organization",
  "roll_up": "custom",
  "requested_metrics": [
    "branch.computed.cycle_time",
    "releases.count"
  ],
  "time_ranges": [
    {
      "after": "2022-05-27",
      "before": "2022-05-29"
    },
    {
      "after": "2022-05-30",
      "before": "2022-06-05"
    },
    {
      "after": "2022-06-06",
      "before": "2022-06-12"
    },
    {
      "after": "2022-06-13",
      "before": "2022-06-19"
    }
  ],
  "limit": 1,
  "offset": 0,
  "return_no_data": true
}

Create measurements report before and after

{
  "group_by": "organization",
  "roll_up": "custom",
  "requested_metrics": [
    "branch.computed.cycle_time",
    "releases.count"
  ],
  "after": "2022-05-27",
  "before": "2022-05-29",
  "limit": 1,
  "offset": 0,
  "return_no_data": true
}

Create measurements report for specific repositories

{
  "group_by": "repository",
  "roll_up": "custom",
  "repository_ids": [
    456801317,
    1235235
  ],
  "requested_metrics": [
    "branch.computed.cycle_time",
    "branch.time_to_pr",
    "branch.time_to_review",
    "branch.review_time",
    "branch.time_to_prod",
    "pr.merged.size",
    "pr.merged",
    "pr.review_depth",
    "commit.activity.new_work.count",
    "commit.total_changes",
    "commit.activity.refactor.count",
    "commit.activity.rework.count",
    "pr.merged.without.review.count",
    "commit.total.count",
    "pr.new",
    "pr.reviews",
    "releases.count",
    "commit.activity_days",
    "branch.state.computed.done",
    "branch.state.active",
    "pm.issues.done",
    "pm.mttr",
    "pm.issues.done.story_points",
    "pm.cfr.issues.done"
  ],
  "after": "2022-05-27",
  "before": "2022-05-29",
  "limit": 1,
  "offset": 0,
  "return_no_data": true
}

Create measurements report for specific teams

{
  "group_by": "team",
  "roll_up": "custom",
  "team_ids": [
    5273,
    58
  ],
  "requested_metrics": [
    "branch.computed.cycle_time",
    "branch.time_to_pr",
    "branch.time_to_review",
    "branch.review_time",
    "branch.time_to_prod",
    "pr.merged.size",
    "pr.merged",
    "pr.review_depth"
  ],
  "after": "2022-05-27",
  "before": "2022-05-29",
  "limit": 1,
  "offset": 0,
  "return_no_data": true
}

Create measurements report for specific contributors

{
  "group_by": "contributor",
  "roll_up": "custom",
  "contributor_ids": [
    236266256,
    32525235
  ],
  "requested_metrics": [
    "branch.computed.cycle_time",
    "branch.time_to_pr",
    "branch.time_to_review",
    "branch.review_time",
    "branch.time_to_prod",
    "pr.merged.size",
    "pr.merged",
    "pr.review_depth"
  ],
  "after": "2022-05-27",
  "before": "2022-05-29",
  "limit": 4,
  "offset": 0,
  "return_no_data": true
}

Create measurements report for specific teams in CSV format

{
  "group_by": "contributor",
  "roll_up": "custom",
  "contributor_ids": [
    236266256,
    32525235
  ],
  "requested_metrics": [
    "branch.computed.cycle_time",
    "branch.time_to_pr",
    "branch.time_to_review",
    "branch.review_time",
    "branch.time_to_prod",
    "pr.merged.size",
    "pr.merged",
    "pr.review_depth"
  ],
  "after": "2022-05-27",
  "before": "2022-05-29",
  "limit": 4,
  "offset": 0,
  "return_no_data": true,
  "file_format": "csv"
}

Responses

200 - Successful Response

{
  "request_id": "string"
}

400 - Bad Request

401 - Unauthorized

405 - Method Not Allowed

422 - Validation Error

500 - Internal Server Error

Get measurements

Will return status of the report(if it's ready or not) and since the report is ready, will add S3 URL in the response. Each file uploaded to S3 will be stored with expiration period policy, so it will be deleted after will reach the threshold. Use the received unique request ID value from the POST request to get the required report.

HTTP request

GET  https://public-api.linearb.io/api/v1/exporter/measurements/{request_id}

Query parameter

Parameter name	Value	Description
request_id	integer	The request id that was received when creating the report

Responses

200 - Successful Response

{
  "report_url": "string",
  "detail": "string"
}

202 - Request to create report is accepted, but not ready yet

204 - No Content. Does not exist or has expired

400 - Bad Request

401 - Unauthorized

405 - Method Not Allowed

422 - Validation Error

500 - Internal Server Error

504 - Gateway Timeout