-
Notifications
You must be signed in to change notification settings - Fork 62
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
docs: add documentation for Job Logs APIs (#505)
* Added supported platform to the README * docs: added Job Logs APIs * docs: updated job logs docs * docs: updated job logs docs * docs: fix link in job logs docs * Update docs/job-logs-apis.md Co-authored-by: Marcus Griep <[email protected]> * Update docs/job-logs-apis.md Co-authored-by: Marcus Griep <[email protected]> * Update docs/job-logs-apis.md --------- Co-authored-by: Nabeel Saabna <[email protected]> Co-authored-by: Marcus Griep <[email protected]>
- Loading branch information
3 people
authored
May 19, 2024
1 parent
71015ed
commit a124034
Showing
2 changed files
with
145 additions
and
0 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,144 @@ | ||
| # Job Logs APIs | ||
|
|
||
| Job Logs APIs provide a summary of and content for the Job Logs generated by the Renovate CLI. | ||
|
|
||
| These APIs are available only on Mend Renovate instances running with a Postgres DB. | ||
|
|
||
| **Version**: This documentation reflects APIs available in Mend Renovate Enterprise v7.0.0 | ||
|
|
||
| > [!IMPORTANT] | ||
| > Reporting APIs are only supported for the following configuration: | ||
| > - Using PostgresDB for Renovate database | ||
| ## Available Job Logs APIs | ||
|
|
||
| The list below describes the available Job Logs APIs. Follow the links on the API names for full details. | ||
|
|
||
| - [List Jobs by Repo](#list-jobs-by-repo) ← Lists all jobs for a given repo | ||
| - [Get Job Logs by Repo](#get-job-logs-by-repo) ← Fetch job logs for a given repo (latest, or by JobID) | ||
| - [Get Job Logs by JobID](#get-job-logs-by-jobid) ← Fetch job logs by Job ID | ||
|
|
||
| ## Enable Job Logs APIs | ||
|
|
||
| Job Logs APIs are enabled with Renovate Admin APIs, which is off by default. | ||
|
|
||
| The APIs can be enabled by setting the `MEND_RNV_ADMIN_API_ENABLED` environment variable to `true`. | ||
| You must also configure an API secret by setting the `MEND_RNV_SERVER_API_SECRET` variable. | ||
|
|
||
| Authentication is done via HTTP Auth, using the API secret as the password. | ||
| For example if the secret is `renovateapi` then you would authenticate by adding the following request header: | ||
|
|
||
| ``` | ||
| Authorization: Bearer renovateapi | ||
| or | ||
| Authorization: renovateapi | ||
| ``` | ||
|
|
||
| ## Job Logs API URLs | ||
|
|
||
| See the table below for a list of Job Logs API URL formats. | ||
|
|
||
| | API | URL format | Query parameters | | ||
| |-------------------------------------------------|--------------------------------------------------------|---------------------------------| | ||
| | [List Jobs by Repo](#list-jobs-by-repo) | [GET] /api/repos/{org}/{repo}/-/jobs | limit (default=100, max=10,000) | | ||
| | [Get Job Logs by Repo](#get-job-logs-by-repo) | [GET] /api/repos/{org}/{repo}/-/jobs/<latest\|{jobId}> | | | ||
| | [Get Job Logs by JobID](#get-job-logs-by-jobid) | [GET] /api/job/logs/{jobId} | | | ||
|
|
||
| ## Details of Job Logs APIs | ||
|
|
||
| ### List Jobs by Repo | ||
|
|
||
| API: [GET] /api/repos/{org}/{repo}/-/jobs | ||
|
|
||
| query parameters: | ||
| - limit | ||
| - Max = 10,000 | ||
| - Default = 100 | ||
|
|
||
| Pagination is not supported. Results are sorted with most recent job first. | ||
|
|
||
| **Description:** Lists all known Job Logs for a given repo | ||
|
|
||
| **Example:** Fetch job list for repo `my-org/my-repo` | ||
|
|
||
| [GET] http://my.renovate.server.com/api/repos/my-org/my-repo/-/jobs (Note: no trailing slash!) | ||
|
|
||
| ```json | ||
| [ | ||
| { | ||
| "jobId": "5a3572bf-49fe-42bb-a066-ff1146fe83d1", | ||
| "reason": "api-request", | ||
| "addedAt": "2024-05-13 12:41:49.760008", | ||
| "startedAt": "2024-05-13 12:41:51.443102", | ||
| "completedAt": "2024-05-13 12:42:32.807422", | ||
| "logLocation": "S3://job-logs/my-org/my-repo/5a3572bf-49fe-42bb-a066-ff1146fe83d1.log.gz", | ||
| "status": "success" | ||
| }, | ||
| { | ||
| "jobId": "fccefbdc-de1e-49b7-bd9a-bfe530ee7547", | ||
| "reason": "repositories-added", | ||
| "addedAt": "2024-05-13 09:01:20.227617", | ||
| "startedAt": "2024-05-13 09:01:25.735557", | ||
| "completedAt": "2024-05-13 09:03:22.818254", | ||
| "logLocation": "S3://job-logs/my-org/my-repo/fccefbdc-de1e-49b7-bd9a-bfe530ee7547.log.gz", | ||
| "status": "success" | ||
| } | ||
| ] | ||
| ``` | ||
|
|
||
| ### Get Job Logs by Repo | ||
|
|
||
| API: [GET] /api/repos/{org}/{repo}/-/jobs/<latest|{jobId}> | ||
|
|
||
| **Description:** Get the contents of a single job log for a given repo | ||
|
|
||
| Options: | ||
| - "latest" - returns the most recent job logs for the given repo | ||
| - {jobId} - returns the job logs for the specified jobId | ||
| - Note: this variation returns the same as [Get Job Logs by JobID](#get-job-logs-by-jobid) | ||
|
|
||
| **Example 1:** Fetch latest job logs for repo `my-org/my-repo` | ||
|
|
||
| [GET] http://my.renovate.server.com/api/repos/my-org/my-repo/-/jobs/latest | ||
|
|
||
| **Example 2:** Fetch job logs for JobID `5a3572bf-49fe-42bb-a066-ff1146fe83d1` in repo `my-org/my-repo` | ||
|
|
||
| [GET] http://my.renovate.server.com/api/repos/my-org/my-repo/-/jobs/5a3572bf-49fe-42bb-a066-ff1146fe83d1 | ||
|
|
||
| **Sample output:** | ||
|
|
||
| ```json | ||
| {"name":"renovate","hostname":"271939e11491","pid":21,"level":20,"logContext":"5a3572bf-49fe-42bb-a066-ff1146fe83d1","config":{},"msg":"File config","time":"2024-05-13T12:41:58.139Z","v":0} | ||
| {"name":"renovate","hostname":"271939e11491","pid":21,"level":20,"logContext":"5a3572bf-49fe-42bb-a066-ff1146fe83d1","config":{},"msg":"CLI config","time":"2024-05-13T12:41:58.143Z","v":0} | ||
| {"name":"renovate","hostname":"271939e11491","pid":21,"level":20,"logContext":"5a3572bf-49fe-42bb-a066-ff1146fe83d1","config":{},"msg":"Env config","time":"2024-05-13T12:41:58.152Z","v":0} | ||
| {"......many rows removed......"} | ||
| {"name":"renovate","hostname":"271939e11491","pid":21,"level":20,"logContext":"5a3572bf-49fe-42bb-a066-ff1146fe83d1","repository":"my-org/my-repo","hosts":[],"msg":"dns cache","time":"2024-05-13T12:42:29.346Z","v":0} | ||
| {"name":"renovate","hostname":"271939e11491","pid":21,"level":30,"logContext":"5a3572bf-49fe-42bb-a066-ff1146fe83d1","repository":"my-org/my-repo","cloned":false,"durationMs":29063,"msg":"Repository finished","time":"2024-05-13T12:42:29.348Z","v":0} | ||
| {"name":"renovate","hostname":"271939e11491","pid":21,"level":20,"logContext":"5a3572bf-49fe-42bb-a066-ff1146fe83d1","msg":"Checking file package cache for expired items","time":"2024-05-13T12:42:29.351Z","v":0} | ||
| {"name":"renovate","hostname":"271939e11491","pid":21,"level":20,"logContext":"5a3572bf-49fe-42bb-a066-ff1146fe83d1","msg":"Verifying and cleaning cache: /tmp/renovate/cache/renovate/renovate-cache-v1","time":"2024-05-13T12:42:29.521Z","v":0} | ||
| {"name":"renovate","hostname":"271939e11491","pid":21,"level":20,"logContext":"5a3572bf-49fe-42bb-a066-ff1146fe83d1","msg":"Deleted 0 of 29 file cached entries in 840ms","time":"2024-05-13T12:42:30.193Z","v":0} | ||
| ``` | ||
|
|
||
| ### Get Job Logs by JobID | ||
|
|
||
| API: [GET] /api/job/logs/{jobId} | ||
|
|
||
| **Description:** Returns the job logs for the specified JobID | ||
|
|
||
| Note: This returns the same as [Get Job Logs by Repo](#get-job-logs-by-repo) with JobID variation, but conveniently does not require the {org}/{repo} in the API endpoint. | ||
|
|
||
| **Example:** Fetch job logs for JobID `5a3572bf-49fe-42bb-a066-ff1146fe83d1` | ||
|
|
||
| [GET] http://my.renovate.server.com/api/job/logs/5a3572bf-49fe-42bb-a066-ff1146fe83d1 | ||
|
|
||
| ```json | ||
| {"name":"renovate","hostname":"271939e11491","pid":21,"level":20,"logContext":"5a3572bf-49fe-42bb-a066-ff1146fe83d1","config":{},"msg":"File config","time":"2024-05-13T12:41:58.139Z","v":0} | ||
| {"name":"renovate","hostname":"271939e11491","pid":21,"level":20,"logContext":"5a3572bf-49fe-42bb-a066-ff1146fe83d1","config":{},"msg":"CLI config","time":"2024-05-13T12:41:58.143Z","v":0} | ||
| {"name":"renovate","hostname":"271939e11491","pid":21,"level":20,"logContext":"5a3572bf-49fe-42bb-a066-ff1146fe83d1","config":{},"msg":"Env config","time":"2024-05-13T12:41:58.152Z","v":0} | ||
| {"......many rows removed......"} | ||
| {"name":"renovate","hostname":"271939e11491","pid":21,"level":20,"logContext":"5a3572bf-49fe-42bb-a066-ff1146fe83d1","repository":"my-org/my-repo","hosts":[],"msg":"dns cache","time":"2024-05-13T12:42:29.346Z","v":0} | ||
| {"name":"renovate","hostname":"271939e11491","pid":21,"level":30,"logContext":"5a3572bf-49fe-42bb-a066-ff1146fe83d1","repository":"my-org/my-repo","cloned":false,"durationMs":29063,"msg":"Repository finished","time":"2024-05-13T12:42:29.348Z","v":0} | ||
| {"name":"renovate","hostname":"271939e11491","pid":21,"level":20,"logContext":"5a3572bf-49fe-42bb-a066-ff1146fe83d1","msg":"Checking file package cache for expired items","time":"2024-05-13T12:42:29.351Z","v":0} | ||
| {"name":"renovate","hostname":"271939e11491","pid":21,"level":20,"logContext":"5a3572bf-49fe-42bb-a066-ff1146fe83d1","msg":"Verifying and cleaning cache: /tmp/renovate/cache/renovate/renovate-cache-v1","time":"2024-05-13T12:42:29.521Z","v":0} | ||
| {"name":"renovate","hostname":"271939e11491","pid":21,"level":20,"logContext":"5a3572bf-49fe-42bb-a066-ff1146fe83d1","msg":"Deleted 0 of 29 file cached entries in 840ms","time":"2024-05-13T12:42:30.193Z","v":0} | ||
| ``` |