diff --git a/docs/README.md b/docs/README.md index 6723e239..f947d100 100644 --- a/docs/README.md +++ b/docs/README.md @@ -23,5 +23,6 @@ The following platforms are supported by Mend Renovate Community Edition and Ent 1. Migration ([Renovate On-Premises to Renovate Community](./migrating-to-renovate-ce.md)) 1. API Documentation - [Admin APIs](./api.md) + - [Job Logs APIs](./job-logs-apis.md) - [Reporting APIs](./reporting-apis.md) 1. [Advanced topics](./advanced.md) diff --git a/docs/job-logs-apis.md b/docs/job-logs-apis.md new file mode 100644 index 00000000..b9ebdbc0 --- /dev/null +++ b/docs/job-logs-apis.md @@ -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/ | | +| [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/ + +**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} +```