From cd57c83baef4051d47b9d76bea6293569b1de46a Mon Sep 17 00:00:00 2001 From: giloctopus Date: Sun, 21 Sep 2025 14:40:16 +0300 Subject: [PATCH 1/3] 1st version - need review --- _docs/kb/articles/retrieve-usage-data-api.md | 61 ++++++++++++++++++++ 1 file changed, 61 insertions(+) create mode 100644 _docs/kb/articles/retrieve-usage-data-api.md diff --git a/_docs/kb/articles/retrieve-usage-data-api.md b/_docs/kb/articles/retrieve-usage-data-api.md new file mode 100644 index 000000000..eeca373f1 --- /dev/null +++ b/_docs/kb/articles/retrieve-usage-data-api.md @@ -0,0 +1,61 @@ +--- +title: "How To: Trigger Codefresh pipeline from Datadog webhook" +description: +group: kb +sub-group: articles +toc: true +kb: false +ht: true +common: false +categories: [API, Pipelines] +support-reviewed: 2023-04-18 LG +--- + +## Overview + +You want to trigger the Codefresh pipeline from a Datadog alert. + +## Details + +1. Open the [Webhook integration management](https://app.datadoghq.com/account/settings#integrations/webhooks) page in Datadog: + + ![datadog]({{site.baseurl}}/images/troubleshooting/datadog.png) + + From here you will first need to add a variable with your Codefresh user API key ( you can generate one here: [User settings](https://g.codefresh.io/user/settings)) +2. Next, click the 'New' button in the Webhook section and fill in the required fields: + * **Name** - The Webhook name + * **URL** - The Run Pipeline API endpoint, example: + `https://g.codefresh.io/api/pipelines/run/%2F` + > **Note** : the '/' symbol in the pipeline name should be URL-encoded as '%2F' + * **Payload** - The parameters and options, for example: + + ```json + { + "branch": "main", + "variables": {"foo": "bar"}, + "options": { + "noCache": true, + "noCfCache": true, + "resetVolume": true, + "enableNotifications": true + } + } + ``` + + > The complete API call description is here: [Codefresh-run](https://g.codefresh.io/api/#operation/pipelines-run-yaml) + + * **Custom headers** - this will be used for Authentication. The headers in Datadog are accepted in JSON format only, for example: + + ```json + {"Authorization": "$APIKEY"} + ``` + + The APIKEY is a variable name containing the Codefresh API key you createdcearlier. + +3. Click **Save** to create a Webhook. + +Now you can refer to this Webhook by its name (`@webhook-`) on Monitor\Alert creation page in **Notify your Team** section, for example here: + +## Related Items + +* [Datadog Webhook Documentation](https://docs.datadoghq.com/integrations/webhooks/) From fa848260afc1b7ecb778adf118c62183ab86170b Mon Sep 17 00:00:00 2001 From: giloctopus Date: Sun, 21 Sep 2025 14:58:53 +0300 Subject: [PATCH 2/3] 1st ver - need review --- _docs/kb/articles/retrieve-usage-data-api.md | 113 +++++++++++++------ 1 file changed, 78 insertions(+), 35 deletions(-) diff --git a/_docs/kb/articles/retrieve-usage-data-api.md b/_docs/kb/articles/retrieve-usage-data-api.md index eeca373f1..4d7b5043b 100644 --- a/_docs/kb/articles/retrieve-usage-data-api.md +++ b/_docs/kb/articles/retrieve-usage-data-api.md @@ -1,5 +1,5 @@ --- -title: "How To: Trigger Codefresh pipeline from Datadog webhook" +title: "How To: Retrieve Usage Data via the Analytics API" description: group: kb sub-group: articles @@ -7,55 +7,98 @@ toc: true kb: false ht: true common: false -categories: [API, Pipelines] -support-reviewed: 2023-04-18 LG +categories: [API] +support-reviewed: --- ## Overview -You want to trigger the Codefresh pipeline from a Datadog alert. +This guide shows how to programmatically access usage-related analytics through the **Codefresh Analytics API**. You'll learn the key endpoints, available reports, supported query parameters, and see a script you can adapt for your own reporting needs. + +> **Goal:** Pull usage metrics (e.g., credit consumption, pipeline credit consumption, active committers) for monitoring or reporting. + +## Prerequisites + +- A Codefresh **API key** with permission to access Analytics. +- Date range values in `YYYY-MM-DD` format for queries. +- Optional: `jq` for pretty-printing JSON responses when using shell examples. ## Details -1. Open the [Webhook integration management](https://app.datadoghq.com/account/settings#integrations/webhooks) page in Datadog: +### Endpoints + +**Reports** +``` +GET https://g.codefresh.io/api/analytics/reports/{reportName} +``` +Replace `{reportName}` with the specific report you want to query. Examples: +``` +GET https://g.codefresh.io/api/analytics/reports/creditConsumption +GET https://g.codefresh.io/api/analytics/reports/pipelineCreditConsumption +GET https://g.codefresh.io/api/analytics/reports/activeCommiters +``` + +**Discover reports and parameters** +``` +GET https://g.codefresh.io/api/analytics/metadata +``` + +> **Notes** +> - Not all reports and query parameters are publicly documented. +> - Different reports support different time ranges and granularities. +> - Use the **metadata** endpoint to discover available reports and their parameters. + +### Query parameters & time dimensions + +**creditConsumption** and **pipelineCreditConsumption** support: +- **No granularity (aggregated):** 1 day – 1 year + `?dateRange=YYYY-MM-DD&dateRange=YYYY-MM-DD` +- **Monthly granularity:** 1 day – 1 year + `?granularity=month&dateRange=YYYY-MM-DD&dateRange=YYYY-MM-DD` +- **Daily granularity:** 2 days – 45 days + `?granularity=day&dateRange=YYYY-MM-DD&dateRange=YYYY-MM-DD` - ![datadog]({{site.baseurl}}/images/troubleshooting/datadog.png) +**activeCommiters** supports: +- **Monthly granularity:** 3 months – 1 year + `?granularity=month&dateRange=YYYY-MM-DD&dateRange=YYYY-MM-DD` - From here you will first need to add a variable with your Codefresh user API key ( you can generate one here: [User settings](https://g.codefresh.io/user/settings)) -2. Next, click the 'New' button in the Webhook section and fill in the required fields: - * **Name** - The Webhook name - * **URL** - The Run Pipeline API endpoint, example: - `https://g.codefresh.io/api/pipelines/run/%2F` - > **Note** : the '/' symbol in the pipeline name should be URL-encoded as '%2F' - * **Payload** - The parameters and options, for example: +### Examples - ```json - { - "branch": "main", - "variables": {"foo": "bar"}, - "options": { - "noCache": true, - "noCfCache": true, - "resetVolume": true, - "enableNotifications": true - } - } - ``` +**Credit consumption (monthly)** +``` +curl -s -H "Authorization: $API_KEY" "https://g.codefresh.io/api/analytics/reports/creditConsumption?granularity=month&dateRange=${START_DATE}&dateRange=${END_DATE}" | jq . +``` - > The complete API call description is here: [Codefresh-run](https://g.codefresh.io/api/#operation/pipelines-run-yaml) +**Pipeline credit consumption (daily within 45 days)** +``` +curl -s -H "Authorization: $API_KEY" "https://g.codefresh.io/api/analytics/reports/pipelineCreditConsumption?granularity=day&dateRange=${START_DATE}&dateRange=${END_DATE}" | jq . +``` - * **Custom headers** - this will be used for Authentication. The headers in Datadog are accepted in JSON format only, for example: +**Active committers (monthly)** +``` +curl -s -H "Authorization: $API_KEY" "https://g.codefresh.io/api/analytics/reports/activeCommiters?granularity=month&dateRange=${START_DATE}&dateRange=${END_DATE}" | jq . +``` - ```json - {"Authorization": "$APIKEY"} - ``` +### Suggested script - The APIKEY is a variable name containing the Codefresh API key you createdcearlier. +```bash +#!/bin/bash +# Expects these env vars: +# API_KEY -> Codefresh API key +# START_DATE -> "YYYY-MM-DD" +# END_DATE -> "YYYY-MM-DD" -3. Click **Save** to create a Webhook. +: "${API_KEY:?Set API_KEY}" +: "${START_DATE:?Set START_DATE}" +: "${END_DATE:?Set END_DATE}" -Now you can refer to this Webhook by its name (`@webhook-`) on Monitor\Alert creation page in **Notify your Team** section, for example here: +# Example: fetch credit consumption (monthly) +curl -s -H "Authorization: $API_KEY" "https://g.codefresh.io/api/analytics/reports/creditConsumption?granularity=month&dateRange=${START_DATE}&dateRange=${END_DATE}" | jq . +# Adapt the endpoint for pipelineCreditConsumption or activeCommiters as needed. +``` -## Related Items +## Best practices -* [Datadog Webhook Documentation](https://docs.datadoghq.com/integrations/webhooks/) +- Use the **metadata** endpoint to confirm available reports and supported query parameters. +- Select a date range and **granularity** appropriate for your reporting needs. +- Automate data collection (cron, pipeline) to regularly sync usage data into your BI/monitoring systems. From b2aef89bb76b9e2866951d35da2c31310fe5c6f0 Mon Sep 17 00:00:00 2001 From: giloctopus Date: Sun, 21 Sep 2025 15:09:38 +0300 Subject: [PATCH 3/3] 2nd ver - need review --- _docs/kb/articles/retrieve-usage-data-api.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/_docs/kb/articles/retrieve-usage-data-api.md b/_docs/kb/articles/retrieve-usage-data-api.md index 4d7b5043b..5ab1a6468 100644 --- a/_docs/kb/articles/retrieve-usage-data-api.md +++ b/_docs/kb/articles/retrieve-usage-data-api.md @@ -81,7 +81,7 @@ curl -s -H "Authorization: $API_KEY" "https://g.codefresh.io/api/analytics/repor ### Suggested script -```bash +``` #!/bin/bash # Expects these env vars: # API_KEY -> Codefresh API key