diff --git a/_data/nav.yml b/_data/nav.yml index dd74ed84c..8a84f7210 100644 --- a/_data/nav.yml +++ b/_data/nav.yml @@ -593,6 +593,15 @@ - title: Managing Git PATs url: "/manage-pats" + +- title: API + url: "/api-examples" + pages: + - title: Analytics API + url: "/analytics-api-examples" + +- title: Reference + url: "/reference" - title: Security url: "/security" pages: @@ -605,6 +614,7 @@ - title: Verify authenticity of artifacts signed with Codefresh pipelines url: "/pipelines-verify-cf-artifacts" + - title: What's new url: "/whats-new" pages: diff --git a/_docs/api-examples/analytics-api-examples.md b/_docs/api-examples/analytics-api-examples.md new file mode 100644 index 000000000..d4365dc25 --- /dev/null +++ b/_docs/api-examples/analytics-api-examples.md @@ -0,0 +1,458 @@ +--- +title: "Analytics API" +description: "" +group: api +toc: true +--- + +The Analytics API is a REST API that allows programmatic access to pipeline performance metrics, enabling you to generate custom reports and insights. +It leverages HTTP GET requests and returns data in JSON format, for seamless integration with your existing tools and systems. + +The API enables you to extract KPI data on pipelines and pipeline builds at different levels. + +Whether you're automating the collection of metrics for external dashboards or conducting in-depth analysis on pipeline efficiency, +the API offers granular access to performance data. +This ensures you can optimize pipeline configurations, identify bottlenecks, and drive continuous improvement within your workflows. + + + + +## Authorization +To make calls to the Analytics API, you need authorization through an API key passed in the header of the API request. + +>**NOTE** +The user who generates the API token must be an account administrator. +Currently, you do not need to select specific scopes for the API key. + +##### How to get the API key +1. From your avatar dropdown in the Codefresh toolbar, select **User Settings**. +1. Do one of the following: + * If you have an existing API key you have saved, use that key. + * To generate a new API key, click **Generate**. + 1. In **Key Name**, type a new name for the API key. + This name is displayed in the UI with random numbers and letters. + 1. Click **Create**. + 1. Copy the API key to a handy location. + + + + +## Get all pipelines/pipelines by name + +Retrieves a list of all pipelines in your account, or filters pipelines based on a specific name or partial name. +Filtering by name returns pipelines whose names match or contain the specified text string. + + + + +### Endpoint + +`GET https://g.codefresh.io/api/analytics/reports/pipelinesDropdown&filters={"name":[array]}` + + + + +### Query parameters + + +{: .table .table-bordered .table-hover} +| Parameter | Description | Data Type | Required/Optional | +| ------------ | -------------- | ------ | ------------------| +| `filters`| `name`: The name of the pipeline or a part of the name by which to filter the pipelines.
For example, filtering by `name`=`e-to-e` retrieves all pipelines that include `e-to-e` in their names. | [array] | Optional | + + +### Request examples + +##### For all pipelines + +`GET https://g.codefresh.io/api/analytics/reports/pipelinesDropdown` + +##### For pipeline by name + +`GET https://g.codefresh.io/api/analytics/reports/pipelinesDropdown&filters={"name":[array]}` + + +### Response +Here's an example of the response for a successful request. + +For each pipeline, the response includes the following data: +* `id`: The ID of the pipeline, generated when the pipeline was created. +* `pipelineName`: The full name of the pipeline, including the project name, in the format `"/"`. +* `shortName`: The name of the pipeline, without the project name. +* `isDeleted`: Indicates if the pipeline has been deleted from the account (`true`), or not (`false`). + +```json +{ + "data": [ + { + "id": "61a893f69ff69e2cf086f12d", + "pipelineName": "NimaCFProject/BasicPipeline", + "shortName": "basicpipeline", + "isDeleted": false + }, + { + "id": "632afb121899584bf3ec14f8", + "pipelineName": "default/NimaCronLink", + "shortName": "nimacronlink", + "isDeleted": false + }, + { + "id": "6372180f39b06e632745555d", + "pipelineName": "test", + "shortName": "test", + "isDeleted": true + }, + { + "id": "639ede86ec4d257410904ba7", + "pipelineName": "NimaCFProject/StepTest", + "shortName": "steptest", + "isDeleted": false + }, + { + "id": "63b58656e8dad136b2a74927", + "pipelineName": "my-first-project/My Pipeline", + "shortName": "my pipeline", + "isDeleted": true + }, + { + "id": "641fe3c0ba826b3e53d3bbbd", + "pipelineName": "TestTags", + "shortName": "testtags", + "isDeleted": false + }, + { + "id": "641fe485ba826b8fe8d3bbbe", + "pipelineName": "MyPipelines", + "shortName": "mypipelines", + "isDeleted": false + }, + { + "id": "6423edc4dbc27269e2693bb6", + "pipelineName": "NimaCFProject/Restart", + "shortName": "restart", + "isDeleted": false + }, + { + "id": "642578967afcb3664998231a", + "pipelineName": "AnnotatePipeline", + "shortName": "annotatepipeline", + "isDeleted": false + }, + { + "id": "64cb4160795de76fcd8b5b29", + "pipelineName": "MyPipelines template", + "shortName": "mypipelines template", + "isDeleted": false + }, + { + "id": "66f246ff58c8309825491a5a", + "pipelineName": "Marvel/smoke-tests", + "shortName": "smoke-tests", + "isDeleted": false + } + ] + }, + + "timeDimensions": {} +``` + +### Failure +Here's an example of the + +``` +{"statusCode":400,"message":"no changes found between source and destination applications","error":"Bad Request"} +``` + +## Get average build duration +Retrieves the average execution duration of pipeline builds for the specified time frame. +The average (mean) duration is calculated by dividing the total execution time by the number of builds, providing an overall measure of pipeline performance. + +You can filter build data by either a project, a specific pipeline, status, or by the favorites tag. + +### Endpoint +`GET https://g.codefresh.io/api/analytics/reports/buildAvgDuration?dateRange=granularity=?filters={"filter-type":[array]}` + + + +### Query parameters + +{: .table .table-bordered .table-hover} +| Setting | Description | Data Type | Required/Optional| +| -----------|-----------------|-----------|------------------| +| `dateRange` | The time frame for which to generate the report, from a minimum of one day to a maximum of six months. The start and end dates must be in `yyyy-mm-dd` (ISO 8601) formats. For example, `dateRange=2024-09-05dateRange=2024-09-01`. | string | Required | +| `granularity` | The level of detail or resolution at which to present the data in the report. The `granularity` levels depend on the `dateRange` defined. {::nomarkdown}
  • 0 days to 6 months: No granularity.
  • 1 to 4 days: hour.
  • 1 day to 3 months: day
  • Up to 6 months: week or month.
{:/} | string | Optional | +| `filters` | The filters by which to narrow the scope of the build data. Can be any of the following: +| | `projectId`: The ID/IDs of the project(s) with the pipeline builds for which to include data. To include data for specific pipelines, omit this filter and use `pipelineId` instead. | array | Optional | +| | `pipelineId`: The ID/IDs of the pipeline(s) for which to include data. To include data for all pipeline builds in a project, omit this filter, and use `projectId` instead. | array | Optional | +| | `status`: The build statuses by which to filter pipelines.
Can be one of the following: {::nomarkdown}
  • error: Pipelines with builds that failed due to errors in the pipeline specifications or with failed steps.
  • succeeded: Pipelines with builds that completed successfully.
  • terminated: TPipelines with builds terminated by the system according to the policy defined in the pipeline's settings. See Build termination in pipeline policies.
{:/} | array | Optional | +| | `isFavorites`: Include only project or pipelines that have been starred as favorites. (NIMA: what is the default)| boolean | Optional | + + +### Request examples + +##### With date range + +`GET https://g.codefresh.io/api/analytics/reports/buildAvgDuration?dateRange=2024-09-01&dateRange=2024-09-05` + + + +#### With date range filtered by project ID + + + +#### With date range filtered by pipeline ID + + +##### With date range filtered by build status + +GET `https://g.codefresh.io/api/analytics/reports/buildAvgDuration?dateRange=2024-09-01:2024-09-05&filters={"pipelineId":["648821e8bb1ff22b3e31f64c"]}` + +##### With date range and all filters + + +### Response + +Here's an example of a successful response. + + +```json +{ + "data": [ + { + "totalBuilds": "4", + "successfulBuilds": "4", + "successRate": 100, + "totalDuration": 72922, + "initializingDuration": 19224, + "runningDuration": 53698, + "pendingApprovalDuration": 0, + "pendingConcurrencyDuration": 0, + "delayDuration": 0 + } + ], + "timeDimensions": { + "dateRange": [ + "2024-09-01T00:00:00.000", + "2024-09-20T23:59:59.999" + ] + } +} +``` + + +The report includes the following fields: +* `totalBuilds`: The total number of pipeline builds that match the date range, the granularity, and other filters defined. +* `successfulBuilds`: The total number of pipeline builds that match the `status` filter if defined. When no `status` filters are defined, the report includes the number of successful builds. . +* `totalDuration`: The average time, in seconds, for a pipeline build to complete execution, calculated from the total number of builds that match the date range, the granularity, and other filters defined. +* `initializingDuration`: The average time, in seconds, for a pipeline build to complete the initialization phase of its execution. +* `runningDuration`: The average time, in seconds, that a pipeline build was in phase running. +* `pendingApprovalDuration`: The average time, in seconds, that a pipeline build was pending approval, meaning that execution was suspended until manual approval. +* `pendingConcurrencyDuration`: The average time, in seconds, that a pipeline build was pending execution due to the concurrency limits configured for the pipelines. Builds with concurrency limits at the pipeline, trigger, and branch levels are included in the calculation. +* `delayDuration`: The average time, in seconds, that a pipeline build was delayed from execution due to concurrency or license limits configured for the pipelines. +* `timeDimensions.dateRange`: The start and end dates for which the report was generated. + + + + + +#### Failure +Here's an example of the + +``` +{"statusCode":400,"message":"no changes found between source and destination applications","error":"Bad Request"} +``` + + +## Get build duration by median percentile (P50) +Retrieves the median (P50) success rate and execution duration for pipeline builds. +The median, or 50th percentile, is a key measure for understanding typical build times, as it represents the middle value of all build durations. + +This metric helps you assess the overall performance without being skewed by outliers, such as exceptionally fast or slow builds. + + + +### Endpoint + +`GET https://g.codefresh.io/api/analytics/reports/buildP50Duration&dateRange=` + + + +### Query parameters +{: .table .table-bordered .table-hover} +| Setting | Description | Data Type | Required/Optional| +|`dateRange` | The time frame for which to generate the report, from a minimum of one day to a maximum of six months. The start and end dates must be in `yyyy-mm-dd` (ISO 8601) formats. For example, `dateRange=2024-09-05dateRange=2024-09-01`. | string | Required | +|`granularity` | The level of detail or resolution at which to present the data in the report. The `granularity` levels depend on the `dateRange` defined. {::nomarkdown}
  • Up to 6 months: No granularity.
  • 1 to 4 days: hour.
  • 1 day to 3 months: day
  • Up to 6 months: week or month.
    When omitted, the default granularity of ???? is used.
{:/} | string | Optional | +| `filters` | The filters by which to narrow the scope of the build data. Can be any of the following: +| | `projectId`: The ID/IDs of the project(s) with the pipeline builds for which to include data. To include data for specific pipelines, omit this filter and use `pipelineId` instead. | array | Optional | +| | `pipelineId`: The ID/IDs of the pipeline(s) for which to include data. To include data for all pipeline builds in a project, omit this filter, and use `projectId` instead. | array | Optional | +| | `status`: The build statuses by which to filter pipelines.
Can be one of the following: {::nomarkdown}
  • error: Pipelines with builds that failed due to errors in the pipeline specifications or with failed steps.
  • succeeded: Pipelines with builds that completed successfully.
  • terminated: TPipelines with builds terminated by the system according to the policy defined in the pipeline's settings. See Build termination in pipeline policies.
{:/} | array | Optional | +| | `isFavorites`: Include only project or pipelines that have been starred as favorites. (NIMA: what is the default)| boolean | Optional | + + +### Request examples + +##### With date range + +`GET https://g.codefresh.io/api/analytics/reports/buildAvgDuration?dateRange=2024-09-01&dateRange=2024-09-05` + + + +##### With date range filtered by project ID + + + +##### With date range filtered by pipeline ID + + +##### With date range filtered by build status + +GET `https://g.codefresh.io/api/analytics/reports/buildAvgDuration?dateRange=2024-09-01:2024-09-05&filters={"pipelineId":["648821e8bb1ff22b3e31f64c"]}` + +##### With date range and all filters + + +### Response + +Here's an example of a successful response. + + +TBD + + + +The report includes the following fields: +* `time`: The granularity defined for the report according to the date range defined. +* `totalBuilds`: The total number of pipeline builds that match the specified date range, granularity, and any additional filters defined. +* `successfulBuilds`: The total number of pipeline builds that match the `status` filter if defined. If a `status` filter is not defined, this represents the total number of successful builds. +* `successRate`: The percentage of builds that completed successfully, out of the total number of builds. +* `totalDuration`: The average duration, in seconds, for 50% of the pipeline builds to complete, calculated from the total number of builds that match the date range, granularity, and any additional filters defined. +* `initializingDuration`: The average time, in seconds, for 50% of the pipeline builds to complete the initialization phase of execution. +* `runningDuration`: The average time, in seconds, for which 50% of the pipeline builds were in the running phase. +* `pendingApprovalDuration`: The average time, in seconds, during which 50% of the pipeline builds were pending manual approval, suspending execution. +* `pendingConcurrencyDuration`: The average time, in seconds, during which 50% of the pipeline builds were suspended specifically due to the concurrency limits configured for the pipelines +at the pipeline, trigger, and branch levels. +* `delayDuration`: The average time, in seconds, for which 50% of the pipeline builds were delayed due to concurrency or license limits configured for the pipelines. +* `timeDimensions.dateRange`: The start and end dates defining the time frame for which the report is generated. + + + + + +#### Failure +Here's an example of the + +``` + +``` + + +## Get build duration by 90th percentile (P90) + +Retrieves the success rate and execution duration for the 90th percentile (P90) of pipeline builds. +The 90th percentile indicates the upper limit within which 90% of builds are completed. + +This metric is useful for identifying performance issues that affect the slowest 10% of builds, enabling you to focus on optimizing these outliers. + + + +### Endpoint + +`GET https://g.codefresh.io/api/analytics/reports/buildP90Duration&dateRange=` + + + +### Query parameters +{: .table .table-bordered .table-hover} +| Setting | Description | Data Type | Required/Optional| +|`dateRange` | The time frame for which to generate the report, from a minimum of one day to a maximum of six months. The start and end dates must be in `yyyy-mm-dd` (ISO 8601) formats. For example, `dateRange=2024-09-05dateRange=2024-09-01`. | string | Required | +|`granularity` | The level of detail or resolution at which to present the data in the report. The `granularity` levels depend on the `dateRange` defined. {::nomarkdown}
  • Up to 6 months: No granularity.
  • 1 to 4 days: hour.
  • 1 day to 3 months: day
  • Up to 6 months: week or month.
    When omitted, the default granularity of ???? is used.
{:/} | string | Optional | +| `filters` | The filters by which to narrow the scope of the build data. Can be any of the following: +| | `projectId`: The ID/IDs of the project(s) with the pipeline builds for which to include data. To include data for specific pipelines, omit this filter and use `pipelineId` instead. | array | Optional | +| | `pipelineId`: The ID/IDs of the pipeline(s) for which to include data. To include data for all pipeline builds in a project, omit this filter, and use `projectId` instead. | array | Optional | +| | `status`: The build statuses by which to filter pipelines.
Can be one of the following: {::nomarkdown}
  • error: Pipelines with builds that failed due to errors in the pipeline specifications or with failed steps.
  • succeeded: Pipelines with builds that completed successfully.
  • terminated: TPipelines with builds terminated by the system according to the policy defined in the pipeline's settings. See Build termination in pipeline policies.
{:/} | array | Optional | +| | `isFavorites`: Include only project or pipelines that have been starred as favorites. (NIMA: what is the default)| boolean | Optional | + +### Request examples + +##### With date range + +`GET https://g.codefresh.io/api/analytics/reports/buildP90Duration?dateRange=2024-09-01&dateRange=2024-09-05` + + + +##### With date range filtered by project ID + + + +##### With date range filtered by pipeline ID + + +##### With date range filtered by build status + +GET `https://g.codefresh.io/api/analytics/reports/buildAvgDuration?dateRange=2024-09-01:2024-09-05&filters={"pipelineId":["648821e8bb1ff22b3e31f64c"]}` + +##### With date range and all filters + + +### Response + +Here's an example of a successful response. + + +TBD + + + +The report includes the following fields: +* `time`: The granularity defined for the report according to the date range defined. +* `totalBuilds`: The total number of pipeline builds that match the specified date range, granularity, and any additional filters defined. +* `successfulBuilds`: The total number of pipeline builds that match the `status` filter if defined. If a `status` filter is not defined, this represents the total number of successful builds. +* `successRate`: The percentage of builds that completed successfully, out of the total number of builds. +* `totalDuration`: The average duration, in seconds, for 50% of the pipeline builds to complete, calculated from the total number of builds that match the date range, granularity, and any additional filters defined. +* `initializingDuration`: The average time, in seconds, for 50% of the pipeline builds to complete the initialization phase of execution. +* `runningDuration`: The average time, in seconds, for which 50% of the pipeline builds were in the running phase. +* `pendingApprovalDuration`: The average time, in seconds, during which 50% of the pipeline builds were pending manual approval, suspending execution. +* `pendingConcurrencyDuration`: The average time, in seconds, during which 50% of the pipeline builds were suspended specifically due to the concurrency limits configured for the pipelines +at the pipeline, trigger, and branch levels. +* `delayDuration`: The average time, in seconds, for which 50% of the pipeline builds were delayed due to concurrency or license limits configured for the pipelines. +* `timeDimensions.dateRange`: The start and end dates defining the time frame for which the report is generated. + + + + + +#### Failure + + + +## Get average duration of pipelines +Retrieves a list of pipelines along with their average execution duration. +The average (mean) duration is calculated by dividing the total execution time by the number of pipeline runs, providing an overall assessment of pipeline performance. + + + +## Get pipelines with median (P50) duration +Retrieves a list of pipelines based on their median (P50) execution duration. +The P50 duration represents the time within which 50% of pipeline executions are completed, highlighting typical pipeline performance. + +This metrics is useful to analyze typical pipeline performance while excluding extreme outliers. + + + +## Get pipelines with 90th percentitle (P90) median duration +Retrieves a list of pipelines based on their 90th percentile (P90) execution duration. +The P90 represents the time within which 90% of pipeline executions are completed, highlighting the upper range of build durations while excluding the slowest 10%. + +This metric is useful for identifying and addressing performance issues that affect a small minority of pipeline executions. + + +