diff --git a/api/swagger.json b/api/swagger.json index d233fe4..13502b8 100644 --- a/api/swagger.json +++ b/api/swagger.json @@ -1,12 +1,12 @@ { "swagger": "2.0", "info": { - "description": "Array of tag-objects for request payload", + "description": "Defines a tag using name and type.", "title": "ClusterCockpit REST API", - "termsOfService": "TODO", + "termsOfService": "https://monitoring.nhr.fau.de/imprint", "contact": { - "name": "ClusterCockpit project", - "url": "TODO", + "name": "ClusterCockpit Project", + "url": "https://github.com/ClusterCockpit", "email": "support@clustercockpit.org" }, "license": { @@ -15,7 +15,7 @@ }, "version": "0.1.0" }, - "host": "localhost:8080", + "host": "clustercockpit.localhost:8082", "basePath": "/api", "paths": { "/jobs/": { @@ -32,17 +32,14 @@ "produces": [ "application/json" ], - "tags": [ - "jobs" - ], - "summary": "List all jobs", + "summary": "Lists all jobs", "parameters": [ { "enum": [ "running", "completed", "failed", - "canceled", + "cancelled", "stopped", "timeout" ], @@ -59,7 +56,7 @@ }, { "type": "string", - "description": "Syntax: \u003cfrom\u003e-\u003cto\u003e, where \u003cfrom\u003e and \u003cto\u003e are unix timestamps in seconds", + "description": "Syntax: '$from-$to', as unix epoch timestamps in seconds", "name": "start-time", "in": "query" }, @@ -108,17 +105,14 @@ "ApiKeyAuth": [] } ], - "description": "A new job started. The body should be in the `meta.json` format\nbut some fields required there are optional here (e.g. `jobState` defaults to \"running\").", + "description": "Job specified in request body will be saved to database as \"running\" with new DB ID.\nJob specifications follow the 'JobMeta' scheme, API will fail to execute if requirements are not met.", "consumes": [ "application/json" ], "produces": [ "application/json" ], - "tags": [ - "jobs" - ], - "summary": "Add a newly started job", + "summary": "Adds a new job as \"running\"", "parameters": [ { "description": "Job to add", @@ -159,17 +153,11 @@ "ApiKeyAuth": [] } ], - "description": "Job to stop is specified by request body.\nAll fields are required in request body.", - "consumes": [ - "application/json" - ], + "description": "Job to stop is specified by request body. All fields are required in this case.\nReturns full job resource information according to 'JobMeta' scheme.", "produces": [ "application/json" ], - "tags": [ - "jobs" - ], - "summary": "Mark job as stopped and trigger archiving", + "summary": "Marks job as completed and triggers archiving", "parameters": [ { "description": "All fields required", @@ -210,17 +198,14 @@ "ApiKeyAuth": [] } ], - "description": "Job to stop is specified by database ID.\nOnly stopTime and final state are required in request body.", + "description": "Job to stop is specified by database ID. Only stopTime and final state are required in request body.\nReturns full job resource information according to 'JobMeta' scheme.", "consumes": [ "application/json" ], "produces": [ "application/json" ], - "tags": [ - "jobs" - ], - "summary": "Mark job as stopped and trigger archiving", + "summary": "Marks job as completed and triggers archiving", "parameters": [ { "type": "integer", @@ -230,7 +215,7 @@ "required": true }, { - "description": "Required fields: [stopTime, state]", + "description": "stopTime and final state in request body", "name": "request", "in": "body", "required": true, @@ -243,7 +228,7 @@ "201": { "description": "Job resource", "schema": { - "$ref": "#/definitions/schema.Job" + "$ref": "#/definitions/schema.JobMeta" } }, "400": { @@ -268,17 +253,14 @@ "ApiKeyAuth": [] } ], - "description": "Add one or more tags as array in request body to job specified by DB ID.", + "description": "Adds tag(s) to a job specified by DB ID. Name and Type of Tag(s) can be chosen freely.\nIf tagged job is already finished: Tag will be written directly to respective archive files.", "consumes": [ "application/json" ], "produces": [ "application/json" ], - "tags": [ - "jobs" - ], - "summary": "Add one or more tags to a job", + "summary": "Adds one or more tags to a job", "parameters": [ { "type": "integer", @@ -293,7 +275,6 @@ "in": "body", "required": true, "schema": { - "description": "Array of tag-objects for request payload", "type": "array", "items": { "$ref": "#/definitions/api.Tag" @@ -326,7 +307,7 @@ }, "definitions": { "api.ErrorResponse": { - "description": "Error Response when using API.", + "description": "Error message as returned from backend.", "type": "object", "properties": { "error": { @@ -350,236 +331,380 @@ } }, "api.StopJobApiRequest": { - "description": "Request to stop running job using stop time and state. Optional fields: JobId, ClusterId and StartTime. They are only used if no database id was provided.", + "description": "Request to stop running job using stoptime and final state. They are only required if no database id was provided with endpoint.", "type": "object", + "required": [ + "jobState", + "stopTime" + ], "properties": { "cluster": { - "description": "Cluster of job (Optional)", - "type": "string" + "description": "Cluster of job", + "type": "string", + "example": "fritz" }, "jobId": { - "description": "Job ID of job (Optional)", - "type": "integer" + "description": "Cluster Job ID of job", + "type": "integer", + "example": 123000 }, "jobState": { - "description": "Final job state", - "type": "string" + "description": "Final state of job", + "type": "string", + "enum": [ + "completed", + "failed", + "cancelled", + "stopped", + "timeout" + ], + "example": "completed" }, "startTime": { - "description": "Start Time of job (Optional)", - "type": "integer" + "description": "Start Time of job as epoch", + "type": "integer", + "example": 1649723812 }, "stopTime": { - "description": "Stop Time as Epoch", - "type": "integer" + "description": "Stop Time of job as epoch", + "type": "integer", + "example": 1649763839 } } }, "api.Tag": { + "description": "Defines a tag using name and type.", "type": "object", "properties": { "name": { - "type": "string" + "description": "Tag Name", + "type": "string", + "example": "Testjob" }, "type": { - "type": "string" + "description": "Tag Type", + "type": "string", + "example": "Debug" } } }, "schema.Job": { + "description": "Meta data information of a HPC job.", "type": "object", "properties": { "arrayJobId": { - "type": "integer" + "description": "The unique identifier of an array job", + "type": "integer", + "example": 123000 }, "cluster": { - "type": "string" + "description": "The unique identifier of a cluster", + "type": "string", + "example": "fritz" }, "duration": { - "type": "integer" + "description": "Duration of job in seconds", + "type": "integer", + "minimum": 0, + "example": 43200 }, "exclusive": { - "type": "integer" + "description": "Specifies how nodes are shared. 0 - Shared among multiple jobs of multiple users, 1 - Job exclusive, 2 - Shared among multiple jobs of same user", + "type": "integer", + "maximum": 2, + "minimum": 0, + "example": 2 }, "id": { + "description": "The unique identifier of a job in the database", "type": "integer" }, "jobId": { - "type": "integer" + "description": "The unique identifier of a job", + "type": "integer", + "example": 123000 }, "jobState": { - "type": "string" + "description": "Final state of job", + "type": "string", + "enum": [ + "completed", + "failed", + "cancelled", + "stopped", + "timeout", + "out_of_memory" + ], + "example": "completed" }, "metaData": { + "description": "Additional information about the job", "type": "object", "additionalProperties": { "type": "string" } }, "monitoringStatus": { - "type": "integer" + "description": "State of monitoring system during job run", + "type": "integer", + "example": 1 }, "numAcc": { - "type": "integer" + "description": "Number of accelerators used", + "type": "integer", + "minimum": 0, + "example": 2 }, "numHwthreads": { - "type": "integer" + "description": "Number of HWThreads used", + "type": "integer", + "minimum": 0, + "example": 20 }, "numNodes": { - "type": "integer" + "description": "Number of nodes used", + "type": "integer", + "minimum": 0, + "example": 2 }, "partition": { - "type": "string" + "description": "The Slurm partition to which the job was submitted", + "type": "string", + "example": "main" }, "project": { - "type": "string" + "description": "The unique identifier of a project", + "type": "string", + "example": "abcd200" }, "resources": { + "description": "Resources used by job", "type": "array", "items": { "$ref": "#/definitions/schema.Resource" } }, "smt": { - "type": "integer" + "description": "SMT threads used by job", + "type": "integer", + "example": 4 }, "startTime": { + "description": "Start time as 'time.Time' data type", "type": "string" }, "subCluster": { - "type": "string" + "description": "The unique identifier of a sub cluster", + "type": "string", + "example": "main" }, "tags": { + "description": "List of tags", "type": "array", "items": { "$ref": "#/definitions/schema.Tag" } }, "user": { - "type": "string" + "description": "The unique identifier of a user", + "type": "string", + "example": "abcd100h" }, "walltime": { - "type": "integer" + "description": "Requested walltime of job in seconds", + "type": "integer", + "example": 86400 } } }, "schema.JobMeta": { + "description": "Meta data information of a HPC job.", "type": "object", "properties": { "arrayJobId": { - "type": "integer" + "description": "The unique identifier of an array job", + "type": "integer", + "example": 123000 }, "cluster": { - "type": "string" + "description": "The unique identifier of a cluster", + "type": "string", + "example": "fritz" }, "duration": { - "type": "integer" + "description": "Duration of job in seconds", + "type": "integer", + "minimum": 0, + "example": 43200 }, "exclusive": { - "type": "integer" + "description": "Specifies how nodes are shared. 0 - Shared among multiple jobs of multiple users, 1 - Job exclusive, 2 - Shared among multiple jobs of same user", + "type": "integer", + "maximum": 2, + "minimum": 0, + "example": 2 }, "id": { - "description": "never used in the job-archive, only available via REST-API", + "description": "The unique identifier of a job in the database", "type": "integer" }, "jobId": { - "type": "integer" + "description": "The unique identifier of a job", + "type": "integer", + "example": 123000 }, "jobState": { - "type": "string" + "description": "Final state of job", + "type": "string", + "enum": [ + "completed", + "failed", + "cancelled", + "stopped", + "timeout", + "out_of_memory" + ], + "example": "completed" }, "metaData": { + "description": "Additional information about the job", "type": "object", "additionalProperties": { "type": "string" } }, "monitoringStatus": { - "type": "integer" + "description": "State of monitoring system during job run", + "type": "integer", + "example": 1 }, "numAcc": { - "type": "integer" + "description": "Number of accelerators used", + "type": "integer", + "minimum": 0, + "example": 2 }, "numHwthreads": { - "type": "integer" + "description": "Number of HWThreads used", + "type": "integer", + "minimum": 0, + "example": 20 }, "numNodes": { - "type": "integer" + "description": "Number of nodes used", + "type": "integer", + "minimum": 0, + "example": 2 }, "partition": { - "type": "string" + "description": "The Slurm partition to which the job was submitted", + "type": "string", + "example": "main" }, "project": { - "type": "string" + "description": "The unique identifier of a project", + "type": "string", + "example": "abcd200" }, "resources": { + "description": "Resources used by job", "type": "array", "items": { "$ref": "#/definitions/schema.Resource" } }, "smt": { - "type": "integer" + "description": "SMT threads used by job", + "type": "integer", + "example": 4 }, "startTime": { - "type": "integer" + "description": "Start epoch time stamp in seconds", + "type": "integer", + "minimum": 0, + "example": 1649723812 }, "statistics": { + "description": "Metric statistics of job", "type": "object", "additionalProperties": { "$ref": "#/definitions/schema.JobStatistics" } }, "subCluster": { - "type": "string" + "description": "The unique identifier of a sub cluster", + "type": "string", + "example": "main" }, "tags": { + "description": "List of tags", "type": "array", "items": { "$ref": "#/definitions/schema.Tag" } }, "user": { - "type": "string" + "description": "The unique identifier of a user", + "type": "string", + "example": "abcd100h" }, "walltime": { - "type": "integer" + "description": "Requested walltime of job in seconds", + "type": "integer", + "example": 86400 } } }, "schema.JobStatistics": { + "description": "Specification for job metric statistics.", "type": "object", "properties": { "avg": { - "type": "number" + "description": "Job metric average", + "type": "number", + "minimum": 0, + "example": 2500 }, "max": { - "type": "number" + "description": "Job metric maximum", + "type": "number", + "minimum": 0, + "example": 3000 }, "min": { - "type": "number" + "description": "Job metric minimum", + "type": "number", + "minimum": 0, + "example": 2000 }, "unit": { - "type": "string" + "description": "Metric unit (see schema/unit.schema.json)", + "type": "string", + "example": "GHz" } } }, "schema.Resource": { + "description": "A resource used by a job", "type": "object", "properties": { "accelerators": { + "description": "List of of accelerator device ids", "type": "array", "items": { "type": "string" } }, "configuration": { + "description": "The configuration options of the node", "type": "string" }, "hostname": { + "description": "Name of the host (= node)", "type": "string" }, "hwthreads": { + "description": "List of OS processor ids", "type": "array", "items": { "type": "integer" @@ -588,16 +713,22 @@ } }, "schema.Tag": { + "description": "Defines a tag using name and type.", "type": "object", "properties": { "id": { + "description": "The unique DB identifier of a tag", "type": "integer" }, "name": { - "type": "string" + "description": "Tag Name", + "type": "string", + "example": "Testjob" }, "type": { - "type": "string" + "description": "Tag Type", + "type": "string", + "example": "Debug" } } } diff --git a/api/swagger.yaml b/api/swagger.yaml index 09d86ba..cd1d0ff 100644 --- a/api/swagger.yaml +++ b/api/swagger.yaml @@ -1,7 +1,7 @@ basePath: /api definitions: api.ErrorResponse: - description: Error Response when using API. + description: Error message as returned from backend. properties: error: description: Error Message @@ -18,186 +18,335 @@ definitions: type: integer type: object api.StopJobApiRequest: - description: 'Request to stop running job using stop time and state. Optional - fields: JobId, ClusterId and StartTime. They are only used if no database id - was provided.' + description: Request to stop running job using stoptime and final state. They + are only required if no database id was provided with endpoint. properties: cluster: - description: Cluster of job (Optional) + description: Cluster of job + example: fritz type: string jobId: - description: Job ID of job (Optional) + description: Cluster Job ID of job + example: 123000 type: integer jobState: - description: Final job state + description: Final state of job + enum: + - completed + - failed + - cancelled + - stopped + - timeout + example: completed type: string startTime: - description: Start Time of job (Optional) + description: Start Time of job as epoch + example: 1649723812 type: integer stopTime: - description: Stop Time as Epoch + description: Stop Time of job as epoch + example: 1649763839 type: integer + required: + - jobState + - stopTime type: object api.Tag: + description: Defines a tag using name and type. properties: name: + description: Tag Name + example: Testjob type: string type: + description: Tag Type + example: Debug type: string type: object schema.Job: + description: Meta data information of a HPC job. properties: arrayJobId: + description: The unique identifier of an array job + example: 123000 type: integer cluster: + description: The unique identifier of a cluster + example: fritz type: string duration: + description: Duration of job in seconds + example: 43200 + minimum: 0 type: integer exclusive: + description: Specifies how nodes are shared. 0 - Shared among multiple jobs + of multiple users, 1 - Job exclusive, 2 - Shared among multiple jobs of + same user + example: 2 + maximum: 2 + minimum: 0 type: integer id: + description: The unique identifier of a job in the database type: integer jobId: + description: The unique identifier of a job + example: 123000 type: integer jobState: + description: Final state of job + enum: + - completed + - failed + - cancelled + - stopped + - timeout + - out_of_memory + example: completed type: string metaData: additionalProperties: type: string + description: Additional information about the job type: object monitoringStatus: + description: State of monitoring system during job run + example: 1 type: integer numAcc: + description: Number of accelerators used + example: 2 + minimum: 0 type: integer numHwthreads: + description: Number of HWThreads used + example: 20 + minimum: 0 type: integer numNodes: + description: Number of nodes used + example: 2 + minimum: 0 type: integer partition: + description: The Slurm partition to which the job was submitted + example: main type: string project: + description: The unique identifier of a project + example: abcd200 type: string resources: + description: Resources used by job items: $ref: '#/definitions/schema.Resource' type: array smt: + description: SMT threads used by job + example: 4 type: integer startTime: + description: Start time as 'time.Time' data type type: string subCluster: + description: The unique identifier of a sub cluster + example: main type: string tags: + description: List of tags items: $ref: '#/definitions/schema.Tag' type: array user: + description: The unique identifier of a user + example: abcd100h type: string walltime: + description: Requested walltime of job in seconds + example: 86400 type: integer type: object schema.JobMeta: + description: Meta data information of a HPC job. properties: arrayJobId: + description: The unique identifier of an array job + example: 123000 type: integer cluster: + description: The unique identifier of a cluster + example: fritz type: string duration: + description: Duration of job in seconds + example: 43200 + minimum: 0 type: integer exclusive: + description: Specifies how nodes are shared. 0 - Shared among multiple jobs + of multiple users, 1 - Job exclusive, 2 - Shared among multiple jobs of + same user + example: 2 + maximum: 2 + minimum: 0 type: integer id: - description: never used in the job-archive, only available via REST-API + description: The unique identifier of a job in the database type: integer jobId: + description: The unique identifier of a job + example: 123000 type: integer jobState: + description: Final state of job + enum: + - completed + - failed + - cancelled + - stopped + - timeout + - out_of_memory + example: completed type: string metaData: additionalProperties: type: string + description: Additional information about the job type: object monitoringStatus: + description: State of monitoring system during job run + example: 1 type: integer numAcc: + description: Number of accelerators used + example: 2 + minimum: 0 type: integer numHwthreads: + description: Number of HWThreads used + example: 20 + minimum: 0 type: integer numNodes: + description: Number of nodes used + example: 2 + minimum: 0 type: integer partition: + description: The Slurm partition to which the job was submitted + example: main type: string project: + description: The unique identifier of a project + example: abcd200 type: string resources: + description: Resources used by job items: $ref: '#/definitions/schema.Resource' type: array smt: + description: SMT threads used by job + example: 4 type: integer startTime: + description: Start epoch time stamp in seconds + example: 1649723812 + minimum: 0 type: integer statistics: additionalProperties: $ref: '#/definitions/schema.JobStatistics' + description: Metric statistics of job type: object subCluster: + description: The unique identifier of a sub cluster + example: main type: string tags: + description: List of tags items: $ref: '#/definitions/schema.Tag' type: array user: + description: The unique identifier of a user + example: abcd100h type: string walltime: + description: Requested walltime of job in seconds + example: 86400 type: integer type: object schema.JobStatistics: + description: Specification for job metric statistics. properties: avg: + description: Job metric average + example: 2500 + minimum: 0 type: number max: + description: Job metric maximum + example: 3000 + minimum: 0 type: number min: + description: Job metric minimum + example: 2000 + minimum: 0 type: number unit: + description: Metric unit (see schema/unit.schema.json) + example: GHz type: string type: object schema.Resource: + description: A resource used by a job properties: accelerators: + description: List of of accelerator device ids items: type: string type: array configuration: + description: The configuration options of the node type: string hostname: + description: Name of the host (= node) type: string hwthreads: + description: List of OS processor ids items: type: integer type: array type: object schema.Tag: + description: Defines a tag using name and type. properties: id: + description: The unique DB identifier of a tag type: integer name: + description: Tag Name + example: Testjob type: string type: + description: Tag Type + example: Debug type: string type: object -host: localhost:8080 +host: clustercockpit.localhost:8082 info: contact: email: support@clustercockpit.org - name: ClusterCockpit project - url: TODO - description: Array of tag-objects for request payload + name: ClusterCockpit Project + url: https://github.com/ClusterCockpit + description: Defines a tag using name and type. license: name: MIT License url: https://opensource.org/licenses/MIT - termsOfService: TODO + termsOfService: https://monitoring.nhr.fau.de/imprint title: ClusterCockpit REST API version: 0.1.0 paths: @@ -212,7 +361,7 @@ paths: - running - completed - failed - - canceled + - cancelled - stopped - timeout in: query @@ -222,8 +371,7 @@ paths: in: query name: cluster type: string - - description: 'Syntax: -, where and are unix timestamps - in seconds' + - description: 'Syntax: ''$from-$to'', as unix epoch timestamps in seconds' in: query name: start-time type: string @@ -254,16 +402,14 @@ paths: $ref: '#/definitions/api.ErrorResponse' security: - ApiKeyAuth: [] - summary: List all jobs - tags: - - jobs + summary: Lists all jobs /jobs/start_job/: post: consumes: - application/json description: |- - A new job started. The body should be in the `meta.json` format - but some fields required there are optional here (e.g. `jobState` defaults to "running"). + Job specified in request body will be saved to database as "running" with new DB ID. + Job specifications follow the 'JobMeta' scheme, API will fail to execute if requirements are not met. parameters: - description: Job to add in: body @@ -289,16 +435,12 @@ paths: $ref: '#/definitions/api.ErrorResponse' security: - ApiKeyAuth: [] - summary: Add a newly started job - tags: - - jobs + summary: Adds a new job as "running" /jobs/stop_job/: post: - consumes: - - application/json description: |- - Job to stop is specified by request body. - All fields are required in request body. + Job to stop is specified by request body. All fields are required in this case. + Returns full job resource information according to 'JobMeta' scheme. parameters: - description: All fields required in: body @@ -323,23 +465,21 @@ paths: $ref: '#/definitions/api.ErrorResponse' security: - ApiKeyAuth: [] - summary: Mark job as stopped and trigger archiving - tags: - - jobs + summary: Marks job as completed and triggers archiving /jobs/stop_job/{id}: post: consumes: - application/json description: |- - Job to stop is specified by database ID. - Only stopTime and final state are required in request body. + Job to stop is specified by database ID. Only stopTime and final state are required in request body. + Returns full job resource information according to 'JobMeta' scheme. parameters: - description: Database ID of Job in: path name: id required: true type: integer - - description: 'Required fields: [stopTime, state]' + - description: stopTime and final state in request body in: body name: request required: true @@ -351,7 +491,7 @@ paths: "201": description: Job resource schema: - $ref: '#/definitions/schema.Job' + $ref: '#/definitions/schema.JobMeta' "400": description: Bad Request schema: @@ -362,15 +502,14 @@ paths: $ref: '#/definitions/api.ErrorResponse' security: - ApiKeyAuth: [] - summary: Mark job as stopped and trigger archiving - tags: - - jobs + summary: Marks job as completed and triggers archiving /jobs/tag_job/{id}: post: consumes: - application/json - description: Add one or more tags as array in request body to job specified - by DB ID. + description: |- + Adds tag(s) to a job specified by DB ID. Name and Type of Tag(s) can be chosen freely. + If tagged job is already finished: Tag will be written directly to respective archive files. parameters: - description: Job Database ID in: path @@ -382,7 +521,6 @@ paths: name: request required: true schema: - description: Array of tag-objects for request payload items: $ref: '#/definitions/api.Tag' type: array @@ -403,9 +541,7 @@ paths: $ref: '#/definitions/api.ErrorResponse' security: - ApiKeyAuth: [] - summary: Add one or more tags to a job - tags: - - jobs + summary: Adds one or more tags to a job securityDefinitions: ApiKeyAuth: description: JWT based authentification for general API endpoint use. diff --git a/internal/api/docs.go b/internal/api/docs.go index a19c2d8..6922599 100644 --- a/internal/api/docs.go +++ b/internal/api/docs.go @@ -1,5 +1,6 @@ // Package api GENERATED BY SWAG; DO NOT EDIT -// This file was generated by swaggo/swag +// This file was generated by swaggo/swag at +// 2022-09-21 11:45:40.164979895 +0200 CEST m=+0.117799537 package api import "github.com/swaggo/swag" @@ -10,10 +11,10 @@ const docTemplate = `{ "info": { "description": "{{escape .Description}}", "title": "{{.Title}}", - "termsOfService": "TODO", + "termsOfService": "https://monitoring.nhr.fau.de/imprint", "contact": { - "name": "ClusterCockpit project", - "url": "TODO", + "name": "ClusterCockpit Project", + "url": "https://github.com/ClusterCockpit", "email": "support@clustercockpit.org" }, "license": { @@ -39,17 +40,14 @@ const docTemplate = `{ "produces": [ "application/json" ], - "tags": [ - "jobs" - ], - "summary": "List all jobs", + "summary": "Lists all jobs", "parameters": [ { "enum": [ "running", "completed", "failed", - "canceled", + "cancelled", "stopped", "timeout" ], @@ -66,7 +64,7 @@ const docTemplate = `{ }, { "type": "string", - "description": "Syntax: \u003cfrom\u003e-\u003cto\u003e, where \u003cfrom\u003e and \u003cto\u003e are unix timestamps in seconds", + "description": "Syntax: '$from-$to', as unix epoch timestamps in seconds", "name": "start-time", "in": "query" }, @@ -115,17 +113,14 @@ const docTemplate = `{ "ApiKeyAuth": [] } ], - "description": "A new job started. The body should be in the ` + "`" + `meta.json` + "`" + ` format\nbut some fields required there are optional here (e.g. ` + "`" + `jobState` + "`" + ` defaults to \"running\").", + "description": "Job specified in request body will be saved to database as \"running\" with new DB ID.\nJob specifications follow the 'JobMeta' scheme, API will fail to execute if requirements are not met.", "consumes": [ "application/json" ], "produces": [ "application/json" ], - "tags": [ - "jobs" - ], - "summary": "Add a newly started job", + "summary": "Adds a new job as \"running\"", "parameters": [ { "description": "Job to add", @@ -166,17 +161,11 @@ const docTemplate = `{ "ApiKeyAuth": [] } ], - "description": "Job to stop is specified by request body.\nAll fields are required in request body.", - "consumes": [ - "application/json" - ], + "description": "Job to stop is specified by request body. All fields are required in this case.\nReturns full job resource information according to 'JobMeta' scheme.", "produces": [ "application/json" ], - "tags": [ - "jobs" - ], - "summary": "Mark job as stopped and trigger archiving", + "summary": "Marks job as completed and triggers archiving", "parameters": [ { "description": "All fields required", @@ -217,17 +206,14 @@ const docTemplate = `{ "ApiKeyAuth": [] } ], - "description": "Job to stop is specified by database ID.\nOnly stopTime and final state are required in request body.", + "description": "Job to stop is specified by database ID. Only stopTime and final state are required in request body.\nReturns full job resource information according to 'JobMeta' scheme.", "consumes": [ "application/json" ], "produces": [ "application/json" ], - "tags": [ - "jobs" - ], - "summary": "Mark job as stopped and trigger archiving", + "summary": "Marks job as completed and triggers archiving", "parameters": [ { "type": "integer", @@ -237,7 +223,7 @@ const docTemplate = `{ "required": true }, { - "description": "Required fields: [stopTime, state]", + "description": "stopTime and final state in request body", "name": "request", "in": "body", "required": true, @@ -250,7 +236,7 @@ const docTemplate = `{ "201": { "description": "Job resource", "schema": { - "$ref": "#/definitions/schema.Job" + "$ref": "#/definitions/schema.JobMeta" } }, "400": { @@ -275,17 +261,14 @@ const docTemplate = `{ "ApiKeyAuth": [] } ], - "description": "Add one or more tags as array in request body to job specified by DB ID.", + "description": "Adds tag(s) to a job specified by DB ID. Name and Type of Tag(s) can be chosen freely.\nIf tagged job is already finished: Tag will be written directly to respective archive files.", "consumes": [ "application/json" ], "produces": [ "application/json" ], - "tags": [ - "jobs" - ], - "summary": "Add one or more tags to a job", + "summary": "Adds one or more tags to a job", "parameters": [ { "type": "integer", @@ -300,7 +283,6 @@ const docTemplate = `{ "in": "body", "required": true, "schema": { - "description": "Array of tag-objects for request payload", "type": "array", "items": { "$ref": "#/definitions/api.Tag" @@ -333,7 +315,7 @@ const docTemplate = `{ }, "definitions": { "api.ErrorResponse": { - "description": "Error Response when using API.", + "description": "Error message as returned from backend.", "type": "object", "properties": { "error": { @@ -357,236 +339,380 @@ const docTemplate = `{ } }, "api.StopJobApiRequest": { - "description": "Request to stop running job using stop time and state. Optional fields: JobId, ClusterId and StartTime. They are only used if no database id was provided.", + "description": "Request to stop running job using stoptime and final state. They are only required if no database id was provided with endpoint.", "type": "object", + "required": [ + "jobState", + "stopTime" + ], "properties": { "cluster": { - "description": "Cluster of job (Optional)", - "type": "string" + "description": "Cluster of job", + "type": "string", + "example": "fritz" }, "jobId": { - "description": "Job ID of job (Optional)", - "type": "integer" + "description": "Cluster Job ID of job", + "type": "integer", + "example": 123000 }, "jobState": { - "description": "Final job state", - "type": "string" + "description": "Final state of job", + "type": "string", + "enum": [ + "completed", + "failed", + "cancelled", + "stopped", + "timeout" + ], + "example": "completed" }, "startTime": { - "description": "Start Time of job (Optional)", - "type": "integer" + "description": "Start Time of job as epoch", + "type": "integer", + "example": 1649723812 }, "stopTime": { - "description": "Stop Time as Epoch", - "type": "integer" + "description": "Stop Time of job as epoch", + "type": "integer", + "example": 1649763839 } } }, "api.Tag": { + "description": "Defines a tag using name and type.", "type": "object", "properties": { "name": { - "type": "string" + "description": "Tag Name", + "type": "string", + "example": "Testjob" }, "type": { - "type": "string" + "description": "Tag Type", + "type": "string", + "example": "Debug" } } }, "schema.Job": { + "description": "Meta data information of a HPC job.", "type": "object", "properties": { "arrayJobId": { - "type": "integer" + "description": "The unique identifier of an array job", + "type": "integer", + "example": 123000 }, "cluster": { - "type": "string" + "description": "The unique identifier of a cluster", + "type": "string", + "example": "fritz" }, "duration": { - "type": "integer" + "description": "Duration of job in seconds", + "type": "integer", + "minimum": 0, + "example": 43200 }, "exclusive": { - "type": "integer" + "description": "Specifies how nodes are shared. 0 - Shared among multiple jobs of multiple users, 1 - Job exclusive, 2 - Shared among multiple jobs of same user", + "type": "integer", + "maximum": 2, + "minimum": 0, + "example": 2 }, "id": { + "description": "The unique identifier of a job in the database", "type": "integer" }, "jobId": { - "type": "integer" + "description": "The unique identifier of a job", + "type": "integer", + "example": 123000 }, "jobState": { - "type": "string" + "description": "Final state of job", + "type": "string", + "enum": [ + "completed", + "failed", + "cancelled", + "stopped", + "timeout", + "out_of_memory" + ], + "example": "completed" }, "metaData": { + "description": "Additional information about the job", "type": "object", "additionalProperties": { "type": "string" } }, "monitoringStatus": { - "type": "integer" + "description": "State of monitoring system during job run", + "type": "integer", + "example": 1 }, "numAcc": { - "type": "integer" + "description": "Number of accelerators used", + "type": "integer", + "minimum": 0, + "example": 2 }, "numHwthreads": { - "type": "integer" + "description": "Number of HWThreads used", + "type": "integer", + "minimum": 0, + "example": 20 }, "numNodes": { - "type": "integer" + "description": "Number of nodes used", + "type": "integer", + "minimum": 0, + "example": 2 }, "partition": { - "type": "string" + "description": "The Slurm partition to which the job was submitted", + "type": "string", + "example": "main" }, "project": { - "type": "string" + "description": "The unique identifier of a project", + "type": "string", + "example": "abcd200" }, "resources": { + "description": "Resources used by job", "type": "array", "items": { "$ref": "#/definitions/schema.Resource" } }, "smt": { - "type": "integer" + "description": "SMT threads used by job", + "type": "integer", + "example": 4 }, "startTime": { + "description": "Start time as 'time.Time' data type", "type": "string" }, "subCluster": { - "type": "string" + "description": "The unique identifier of a sub cluster", + "type": "string", + "example": "main" }, "tags": { + "description": "List of tags", "type": "array", "items": { "$ref": "#/definitions/schema.Tag" } }, "user": { - "type": "string" + "description": "The unique identifier of a user", + "type": "string", + "example": "abcd100h" }, "walltime": { - "type": "integer" + "description": "Requested walltime of job in seconds", + "type": "integer", + "example": 86400 } } }, "schema.JobMeta": { + "description": "Meta data information of a HPC job.", "type": "object", "properties": { "arrayJobId": { - "type": "integer" + "description": "The unique identifier of an array job", + "type": "integer", + "example": 123000 }, "cluster": { - "type": "string" + "description": "The unique identifier of a cluster", + "type": "string", + "example": "fritz" }, "duration": { - "type": "integer" + "description": "Duration of job in seconds", + "type": "integer", + "minimum": 0, + "example": 43200 }, "exclusive": { - "type": "integer" + "description": "Specifies how nodes are shared. 0 - Shared among multiple jobs of multiple users, 1 - Job exclusive, 2 - Shared among multiple jobs of same user", + "type": "integer", + "maximum": 2, + "minimum": 0, + "example": 2 }, "id": { - "description": "never used in the job-archive, only available via REST-API", + "description": "The unique identifier of a job in the database", "type": "integer" }, "jobId": { - "type": "integer" + "description": "The unique identifier of a job", + "type": "integer", + "example": 123000 }, "jobState": { - "type": "string" + "description": "Final state of job", + "type": "string", + "enum": [ + "completed", + "failed", + "cancelled", + "stopped", + "timeout", + "out_of_memory" + ], + "example": "completed" }, "metaData": { + "description": "Additional information about the job", "type": "object", "additionalProperties": { "type": "string" } }, "monitoringStatus": { - "type": "integer" + "description": "State of monitoring system during job run", + "type": "integer", + "example": 1 }, "numAcc": { - "type": "integer" + "description": "Number of accelerators used", + "type": "integer", + "minimum": 0, + "example": 2 }, "numHwthreads": { - "type": "integer" + "description": "Number of HWThreads used", + "type": "integer", + "minimum": 0, + "example": 20 }, "numNodes": { - "type": "integer" + "description": "Number of nodes used", + "type": "integer", + "minimum": 0, + "example": 2 }, "partition": { - "type": "string" + "description": "The Slurm partition to which the job was submitted", + "type": "string", + "example": "main" }, "project": { - "type": "string" + "description": "The unique identifier of a project", + "type": "string", + "example": "abcd200" }, "resources": { + "description": "Resources used by job", "type": "array", "items": { "$ref": "#/definitions/schema.Resource" } }, "smt": { - "type": "integer" + "description": "SMT threads used by job", + "type": "integer", + "example": 4 }, "startTime": { - "type": "integer" + "description": "Start epoch time stamp in seconds", + "type": "integer", + "minimum": 0, + "example": 1649723812 }, "statistics": { + "description": "Metric statistics of job", "type": "object", "additionalProperties": { "$ref": "#/definitions/schema.JobStatistics" } }, "subCluster": { - "type": "string" + "description": "The unique identifier of a sub cluster", + "type": "string", + "example": "main" }, "tags": { + "description": "List of tags", "type": "array", "items": { "$ref": "#/definitions/schema.Tag" } }, "user": { - "type": "string" + "description": "The unique identifier of a user", + "type": "string", + "example": "abcd100h" }, "walltime": { - "type": "integer" + "description": "Requested walltime of job in seconds", + "type": "integer", + "example": 86400 } } }, "schema.JobStatistics": { + "description": "Specification for job metric statistics.", "type": "object", "properties": { "avg": { - "type": "number" + "description": "Job metric average", + "type": "number", + "minimum": 0, + "example": 2500 }, "max": { - "type": "number" + "description": "Job metric maximum", + "type": "number", + "minimum": 0, + "example": 3000 }, "min": { - "type": "number" + "description": "Job metric minimum", + "type": "number", + "minimum": 0, + "example": 2000 }, "unit": { - "type": "string" + "description": "Metric unit (see schema/unit.schema.json)", + "type": "string", + "example": "GHz" } } }, "schema.Resource": { + "description": "A resource used by a job", "type": "object", "properties": { "accelerators": { + "description": "List of of accelerator device ids", "type": "array", "items": { "type": "string" } }, "configuration": { + "description": "The configuration options of the node", "type": "string" }, "hostname": { + "description": "Name of the host (= node)", "type": "string" }, "hwthreads": { + "description": "List of OS processor ids", "type": "array", "items": { "type": "integer" @@ -595,16 +721,22 @@ const docTemplate = `{ } }, "schema.Tag": { + "description": "Defines a tag using name and type.", "type": "object", "properties": { "id": { + "description": "The unique DB identifier of a tag", "type": "integer" }, "name": { - "type": "string" + "description": "Tag Name", + "type": "string", + "example": "Testjob" }, "type": { - "type": "string" + "description": "Tag Type", + "type": "string", + "example": "Debug" } } } @@ -622,11 +754,11 @@ const docTemplate = `{ // SwaggerInfo holds exported Swagger Info so clients can modify it var SwaggerInfo = &swag.Spec{ Version: "0.1.0", - Host: "localhost:8080", + Host: "clustercockpit.localhost:8082", BasePath: "/api", Schemes: []string{}, Title: "ClusterCockpit REST API", - Description: "Array of tag-objects for request payload", + Description: "Defines a tag using name and type.", InfoInstanceName: "swagger", SwaggerTemplate: docTemplate, } diff --git a/internal/api/rest.go b/internal/api/rest.go index 99e4493..1ca7d20 100644 --- a/internal/api/rest.go +++ b/internal/api/rest.go @@ -34,14 +34,18 @@ import ( // @title ClusterCockpit REST API // @version 0.1.0 // @description API for batch job control. -// @termsOfService TODO -// @contact.name ClusterCockpit project -// @contact.url TODO +// @termsOfService https://monitoring.nhr.fau.de/imprint + +// @contact.name ClusterCockpit Project +// @contact.url https://github.com/ClusterCockpit // @contact.email support@clustercockpit.org + // @license.name MIT License // @license.url https://opensource.org/licenses/MIT -// @host localhost:8080 + +// @host clustercockpit.localhost:8082 // @BasePath /api + // @securityDefinitions.apikey ApiKeyAuth // @in header // @name X-Auth-Token @@ -92,20 +96,19 @@ type StartJobApiResponse struct { } // StopJobApiRequest model -// @Description Request to stop running job using stop time and state. -// @Description Optional fields: JobId, ClusterId and StartTime. -// @Description They are only used if no database id was provided. +// @Description Request to stop running job using stoptime and final state. +// @Description They are only required if no database id was provided with endpoint. type StopJobApiRequest struct { - // Stop Time as Epoch - StopTime int64 `json:"stopTime"` - State schema.JobState `json:"jobState"` // Final job state - JobId *int64 `json:"jobId"` // Job ID of job (Optional) - Cluster *string `json:"cluster"` // Cluster of job (Optional) - StartTime *int64 `json:"startTime"` // Start Time of job (Optional) + // Stop Time of job as epoch + StopTime int64 `json:"stopTime" validate:"required" example:"1649763839"` + State schema.JobState `json:"jobState" validate:"required" example:"completed" enums:"completed,failed,cancelled,stopped,timeout"` // Final job state + JobId *int64 `json:"jobId" example:"123000"` // Cluster Job ID of job + Cluster *string `json:"cluster" example:"fritz"` // Cluster of job + StartTime *int64 `json:"startTime" example:"1649723812"` // Start Time of job as epoch } // ErrorResponse model -// @Description Error Response when using API. +// @Description Error message as returned from backend. type ErrorResponse struct { // Statustext of Errorcode Status string `json:"status"` @@ -116,8 +119,8 @@ type ErrorResponse struct { // @Description Defines a tag using name and type. type Tag struct { // Tag Type - Type string `json:"type"` - Name string `json:"name"` // Tag Name + Type string `json:"type" example:"Debug"` + Name string `json:"name" example:"Testjob"` // Tag Name } type TagJobApiRequest []*Tag @@ -139,14 +142,13 @@ func decode(r io.Reader, val interface{}) error { } // getJobs godoc -// @Summary List all jobs +// @Summary Lists all jobs // @Description Get a list of all jobs. Filters can be applied using query parameters. -// @Tags jobs // @Accept json // @Produce json -// @Param state query string false "Job State" Enums(running, completed, failed, canceled, stopped, timeout) +// @Param state query string false "Job State" Enums(running, completed, failed, cancelled, stopped, timeout) // @Param cluster query string false "Job Cluster" -// @Param start-time query string false "Syntax: -, where and are unix timestamps in seconds" +// @Param start-time query string false "Syntax: '$from-$to', as unix epoch timestamps in seconds" // @Param page query int false "Page Number" // @Param items-per-page query int false "Items per page" // @Param with-metadata query bool false "Include metadata in response" @@ -264,9 +266,9 @@ func (api *RestApi) getJobs(rw http.ResponseWriter, r *http.Request) { } // tagJob godoc -// @Summary Add one or more tags to a job -// @Description Add one or more tags as array in request body to job specified by DB ID. -// @Tags jobs +// @Summary Adds one or more tags to a job +// @Description Adds tag(s) to a job specified by DB ID. Name and Type of Tag(s) can be chosen freely. +// @Description If tagged job is already finished: Tag will be written directly to respective archive files. // @Accept json // @Produce json // @Param id path int true "Job Database ID" @@ -321,10 +323,9 @@ func (api *RestApi) tagJob(rw http.ResponseWriter, r *http.Request) { } // startJob godoc -// @Summary Add a newly started job -// @Description A new job started. The body should be in the `meta.json` format -// @Description but some fields required there are optional here (e.g. `jobState` defaults to "running"). -// @Tags jobs +// @Summary Adds a new job as "running" +// @Description Job specified in request body will be saved to database as "running" with new DB ID. +// @Description Job specifications follow the 'JobMeta' scheme, API will fail to execute if requirements are not met. // @Accept json // @Produce json // @Param request body schema.JobMeta true "Job to add" @@ -388,15 +389,14 @@ func (api *RestApi) startJob(rw http.ResponseWriter, r *http.Request) { } // stopJobById godoc -// @Summary Mark job as stopped and trigger archiving -// @Description Job to stop is specified by database ID. -// @Description Only stopTime and final state are required in request body. -// @Tags jobs +// @Summary Marks job as completed and triggers archiving +// @Description Job to stop is specified by database ID. Only stopTime and final state are required in request body. +// @Description Returns full job resource information according to 'JobMeta' scheme. // @Accept json // @Produce json // @Param id path int true "Database ID of Job" -// @Param request body api.StopJobApiRequest true "Required fields: [stopTime, state]" -// @Success 201 {object} schema.Job "Job resource" +// @Param request body api.StopJobApiRequest true "stopTime and final state in request body" +// @Success 201 {object} schema.JobMeta "Job resource" // @Failure 400 {object} api.ErrorResponse "Bad Request" // @Failure 404 {object} api.ErrorResponse "Resource not found" // @Security ApiKeyAuth @@ -500,11 +500,9 @@ func (api *RestApi) stopJobById(rw http.ResponseWriter, r *http.Request) { } // stopJobByRequest godoc -// @Summary Mark job as stopped and trigger archiving -// @Description Job to stop is specified by request body. -// @Description All fields are required in request body. -// @Tags jobs -// @Accept json +// @Summary Marks job as completed and triggers archiving +// @Description Job to stop is specified by request body. All fields are required in this case. +// @Description Returns full job resource information according to 'JobMeta' scheme. // @Produce json // @Param request body api.StopJobApiRequest true "All fields required" // @Success 201 {object} schema.JobMeta "Job resource" diff --git a/pkg/schema/job.go b/pkg/schema/job.go index 4bbb797..e4e2c6b 100644 --- a/pkg/schema/job.go +++ b/pkg/schema/job.go @@ -11,57 +11,70 @@ import ( "time" ) -// Common subset of Job and JobMeta. Use one of those, not -// this type directly. +// Non-Swaggered Comment: BaseJob +// Non-Swaggered Comment: Common subset of Job and JobMeta. Use one of those, not this type directly. + type BaseJob struct { - JobID int64 `json:"jobId" db:"job_id"` - User string `json:"user" db:"user"` - Project string `json:"project" db:"project"` - Cluster string `json:"cluster" db:"cluster"` - SubCluster string `json:"subCluster" db:"subcluster"` - Partition string `json:"partition" db:"partition"` - ArrayJobId int64 `json:"arrayJobId" db:"array_job_id"` - NumNodes int32 `json:"numNodes" db:"num_nodes"` - NumHWThreads int32 `json:"numHwthreads" db:"num_hwthreads"` - NumAcc int32 `json:"numAcc" db:"num_acc"` - Exclusive int32 `json:"exclusive" db:"exclusive"` - MonitoringStatus int32 `json:"monitoringStatus" db:"monitoring_status"` - SMT int32 `json:"smt" db:"smt"` - State JobState `json:"jobState" db:"job_state"` - Duration int32 `json:"duration" db:"duration"` - Walltime int64 `json:"walltime" db:"walltime"` - Tags []*Tag `json:"tags"` - RawResources []byte `json:"-" db:"resources"` - Resources []*Resource `json:"resources"` - RawMetaData []byte `json:"-" db:"meta_data"` - MetaData map[string]string `json:"metaData"` + // The unique identifier of a job + JobID int64 `json:"jobId" db:"job_id" example:"123000"` + User string `json:"user" db:"user" example:"abcd100h"` // The unique identifier of a user + Project string `json:"project" db:"project" example:"abcd200"` // The unique identifier of a project + Cluster string `json:"cluster" db:"cluster" example:"fritz"` // The unique identifier of a cluster + SubCluster string `json:"subCluster" db:"subcluster" example:"main"` // The unique identifier of a sub cluster + Partition string `json:"partition" db:"partition" example:"main"` // The Slurm partition to which the job was submitted + ArrayJobId int64 `json:"arrayJobId" db:"array_job_id" example:"123000"` // The unique identifier of an array job + NumNodes int32 `json:"numNodes" db:"num_nodes" example:"2" minimum:"0"` // Number of nodes used + NumHWThreads int32 `json:"numHwthreads" db:"num_hwthreads" example:"20" minimum:"0"` // Number of HWThreads used + NumAcc int32 `json:"numAcc" db:"num_acc" example:"2" minimum:"0"` // Number of accelerators used + Exclusive int32 `json:"exclusive" db:"exclusive" example:"2" minimum:"0" maximum:"2"` // Specifies how nodes are shared. 0 - Shared among multiple jobs of multiple users, 1 - Job exclusive, 2 - Shared among multiple jobs of same user + MonitoringStatus int32 `json:"monitoringStatus" db:"monitoring_status" example:"1"` // State of monitoring system during job run + SMT int32 `json:"smt" db:"smt" example:"4"` // SMT threads used by job + State JobState `json:"jobState" db:"job_state" example:"completed" enums:"completed,failed,cancelled,stopped,timeout,out_of_memory"` // Final state of job + Duration int32 `json:"duration" db:"duration" example:"43200" minimum:"0"` // Duration of job in seconds + Walltime int64 `json:"walltime" db:"walltime" example:"86400"` // Requested walltime of job in seconds + Tags []*Tag `json:"tags"` // List of tags + RawResources []byte `json:"-" db:"resources"` // Resources used by job [As Bytes] + Resources []*Resource `json:"resources"` // Resources used by job + RawMetaData []byte `json:"-" db:"meta_data"` // Additional information about the job [As Bytes] + MetaData map[string]string `json:"metaData"` // Additional information about the job } -// This type is used as the GraphQL interface and using sqlx as a table row. +// Non-Swaggered Comment: Job +// Non-Swaggered Comment: This type is used as the GraphQL interface and using sqlx as a table row. + +// Job model +// @Description Information of a HPC job. type Job struct { + // The unique identifier of a job in the database ID int64 `json:"id" db:"id"` BaseJob - StartTimeUnix int64 `json:"-" db:"start_time"` - StartTime time.Time `json:"startTime"` - MemUsedMax float64 `json:"-" db:"mem_used_max"` - FlopsAnyAvg float64 `json:"-" db:"flops_any_avg"` - MemBwAvg float64 `json:"-" db:"mem_bw_avg"` - LoadAvg float64 `json:"-" db:"load_avg"` - NetBwAvg float64 `json:"-" db:"net_bw_avg"` - NetDataVolTotal float64 `json:"-" db:"net_data_vol_total"` - FileBwAvg float64 `json:"-" db:"file_bw_avg"` - FileDataVolTotal float64 `json:"-" db:"file_data_vol_total"` + StartTimeUnix int64 `json:"-" db:"start_time" example:"1649723812"` // Start epoch time stamp in seconds + StartTime time.Time `json:"startTime"` // Start time as 'time.Time' data type + MemUsedMax float64 `json:"-" db:"mem_used_max"` // MemUsedMax as Float64 + FlopsAnyAvg float64 `json:"-" db:"flops_any_avg"` // FlopsAnyAvg as Float64 + MemBwAvg float64 `json:"-" db:"mem_bw_avg"` // MemBwAvg as Float64 + LoadAvg float64 `json:"-" db:"load_avg"` // LoadAvg as Float64 + NetBwAvg float64 `json:"-" db:"net_bw_avg"` // NetBwAvg as Float64 + NetDataVolTotal float64 `json:"-" db:"net_data_vol_total"` // NetDataVolTotal as Float64 + FileBwAvg float64 `json:"-" db:"file_bw_avg"` // FileBwAvg as Float64 + FileDataVolTotal float64 `json:"-" db:"file_data_vol_total"` // FileDataVolTotal as Float64 } -// When reading from the database or sending data via GraphQL, the start time can be in the much more -// convenient time.Time type. In the `meta.json` files, the start time is encoded as a unix epoch timestamp. -// This is why there is this struct, which contains all fields from the regular job struct, but "overwrites" -// the StartTime field with one of type int64. +// Non-Swaggered Comment: JobMeta +// Non-Swaggered Comment: When reading from the database or sending data via GraphQL, the start time can be in the much more +// Non-Swaggered Comment: convenient time.Time type. In the `meta.json` files, the start time is encoded as a unix epoch timestamp. +// Non-Swaggered Comment: This is why there is this struct, which contains all fields from the regular job struct, but "overwrites" +// Non-Swaggered Comment: the StartTime field with one of type int64. +// Non-Swaggered Comment: ID *int64 `json:"id,omitempty"` >> never used in the job-archive, only available via REST-API + +// JobMeta model +// @Description Meta data information of a HPC job. type JobMeta struct { - ID *int64 `json:"id,omitempty"` // never used in the job-archive, only available via REST-API + // The unique identifier of a job in the database + ID *int64 `json:"id,omitempty"` BaseJob - StartTime int64 `json:"startTime" db:"start_time"` - Statistics map[string]JobStatistics `json:"statistics,omitempty"` + StartTime int64 `json:"startTime" db:"start_time" example:"1649723812" minimum:"0"` // Start epoch time stamp in seconds + Statistics map[string]JobStatistics `json:"statistics,omitempty"` // Metric statistics of job } const ( @@ -76,24 +89,32 @@ var JobDefaults BaseJob = BaseJob{ MonitoringStatus: MonitoringStatusRunningOrArchiving, } +// JobStatistics model +// @Description Specification for job metric statistics. type JobStatistics struct { - Unit string `json:"unit"` - Avg float64 `json:"avg"` - Min float64 `json:"min"` - Max float64 `json:"max"` + // Metric unit (see schema/unit.schema.json) + Unit string `json:"unit" example:"GHz"` + Avg float64 `json:"avg" example:"2500" minimum:"0"` // Job metric average + Min float64 `json:"min" example:"2000" minimum:"0"` // Job metric minimum + Max float64 `json:"max" example:"3000" minimum:"0"` // Job metric maximum } +// Tag model +// @Description Defines a tag using name and type. type Tag struct { + // The unique DB identifier of a tag ID int64 `json:"id" db:"id"` - Type string `json:"type" db:"tag_type"` - Name string `json:"name" db:"tag_name"` + Type string `json:"type" db:"tag_type" example:"Debug"` // Tag Type + Name string `json:"name" db:"tag_name" example:"Testjob"` // Tag Name } +// Resource model +// @Description A resource used by a job type Resource struct { - Hostname string `json:"hostname"` - HWThreads []int `json:"hwthreads,omitempty"` - Accelerators []string `json:"accelerators,omitempty"` - Configuration string `json:"configuration,omitempty"` + Hostname string `json:"hostname"` // Name of the host (= node) + HWThreads []int `json:"hwthreads,omitempty"` // List of OS processor ids + Accelerators []string `json:"accelerators,omitempty"` // List of of accelerator device ids + Configuration string `json:"configuration,omitempty"` // The configuration options of the node } type JobState string