ClusterCockpit/cc-backend
1
0
Fork 0
mirror of https://github.com/ClusterCockpit/cc-backend synced 2024-12-26 05:19:05 +01:00
Code Issues Packages Releases Activity

Extend parsed swagger documentation by adding comments

Browse Source
This commit is contained in:
Christoph Kluge 2022-09-21 11:54:19 +02:00
parent 35114aeb2d
commit 05a84cb95c
5 changed files with 736 additions and 318 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

313
api/swagger.json
View File

@ -1,12 +1,12 @@
{ {
"swagger": "2.0", "swagger": "2.0",
"info": { "info": {
"description": "Array of tag-objects for request payload", "description": "Defines a tag using name and type.",
"title": "ClusterCockpit REST API", "title": "ClusterCockpit REST API",
"termsOfService": "TODO", "termsOfService": "https://monitoring.nhr.fau.de/imprint",
"contact": { "contact": {
"name": "ClusterCockpit project", "name": "ClusterCockpit Project",
"url": "TODO", "url": "https://github.com/ClusterCockpit",
"email": "support@clustercockpit.org" "email": "support@clustercockpit.org"
}, },
"license": { "license": {
@ -15,7 +15,7 @@
}, },
"version": "0.1.0" "version": "0.1.0"
}, },
"host": "localhost:8080", "host": "clustercockpit.localhost:8082",
"basePath": "/api", "basePath": "/api",
"paths": { "paths": {
"/jobs/": { "/jobs/": {
@ -32,17 +32,14 @@
"produces": [ "produces": [
"application/json" "application/json"
], ],
"tags": [ "summary": "Lists all jobs",
"jobs"
],
"summary": "List all jobs",
"parameters": [ "parameters": [
{ {
"enum": [ "enum": [
"running", "running",
"completed", "completed",
"failed", "failed",
"canceled", "cancelled",
"stopped", "stopped",
"timeout" "timeout"
], ],
@ -59,7 +56,7 @@
}, },
{ {
"type": "string", "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", "name": "start-time",
"in": "query" "in": "query"
}, },
@ -108,17 +105,14 @@
"ApiKeyAuth": [] "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": [ "consumes": [
"application/json" "application/json"
], ],
"produces": [ "produces": [
"application/json" "application/json"
], ],
"tags": [ "summary": "Adds a new job as \"running\"",
"jobs"
],
"summary": "Add a newly started job",
"parameters": [ "parameters": [
{ {
"description": "Job to add", "description": "Job to add",
@ -159,17 +153,11 @@
"ApiKeyAuth": [] "ApiKeyAuth": []
} }
], ],
"description": "Job to stop is specified by request body.\nAll fields are required in request body.", "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.",
"consumes": [
"application/json"
],
"produces": [ "produces": [
"application/json" "application/json"
], ],
"tags": [ "summary": "Marks job as completed and triggers archiving",
"jobs"
],
"summary": "Mark job as stopped and trigger archiving",
"parameters": [ "parameters": [
{ {
"description": "All fields required", "description": "All fields required",
@ -210,17 +198,14 @@
"ApiKeyAuth": [] "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": [ "consumes": [
"application/json" "application/json"
], ],
"produces": [ "produces": [
"application/json" "application/json"
], ],
"tags": [ "summary": "Marks job as completed and triggers archiving",
"jobs"
],
"summary": "Mark job as stopped and trigger archiving",
"parameters": [ "parameters": [
{ {
"type": "integer", "type": "integer",
@ -230,7 +215,7 @@
"required": true "required": true
}, },
{ {
"description": "Required fields: [stopTime, state]", "description": "stopTime and final state in request body",
"name": "request", "name": "request",
"in": "body", "in": "body",
"required": true, "required": true,
@ -243,7 +228,7 @@
"201": { "201": {
"description": "Job resource", "description": "Job resource",
"schema": { "schema": {
"$ref": "#/definitions/schema.Job" "$ref": "#/definitions/schema.JobMeta"
} }
}, },
"400": { "400": {
@ -268,17 +253,14 @@
"ApiKeyAuth": [] "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": [ "consumes": [
"application/json" "application/json"
], ],
"produces": [ "produces": [
"application/json" "application/json"
], ],
"tags": [ "summary": "Adds one or more tags to a job",
"jobs"
],
"summary": "Add one or more tags to a job",
"parameters": [ "parameters": [
{ {
"type": "integer", "type": "integer",
@ -293,7 +275,6 @@
"in": "body", "in": "body",
"required": true, "required": true,
"schema": { "schema": {
"description": "Array of tag-objects for request payload",
"type": "array", "type": "array",
"items": { "items": {
"$ref": "#/definitions/api.Tag" "$ref": "#/definitions/api.Tag"
@ -326,7 +307,7 @@
}, },
"definitions": { "definitions": {
"api.ErrorResponse": { "api.ErrorResponse": {
"description": "Error Response when using API.", "description": "Error message as returned from backend.",
"type": "object", "type": "object",
"properties": { "properties": {
"error": { "error": {
@ -350,236 +331,380 @@
} }
}, },
"api.StopJobApiRequest": { "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", "type": "object",
"required": [
"jobState",
"stopTime"
],
"properties": { "properties": {
"cluster": { "cluster": {
"description": "Cluster of job (Optional)", "description": "Cluster of job",
"type": "string" "type": "string",
"example": "fritz"
}, },
"jobId": { "jobId": {
"description": "Job ID of job (Optional)", "description": "Cluster Job ID of job",
"type": "integer" "type": "integer",
"example": 123000
}, },
"jobState": { "jobState": {
"description": "Final job state", "description": "Final state of job",
"type": "string" "type": "string",
"enum": [
"completed",
"failed",
"cancelled",
"stopped",
"timeout"
],
"example": "completed"
}, },
"startTime": { "startTime": {
"description": "Start Time of job (Optional)", "description": "Start Time of job as epoch",
"type": "integer" "type": "integer",
"example": 1649723812
}, },
"stopTime": { "stopTime": {
"description": "Stop Time as Epoch", "description": "Stop Time of job as epoch",
"type": "integer" "type": "integer",
"example": 1649763839
} }
} }
}, },
"api.Tag": { "api.Tag": {
"description": "Defines a tag using name and type.",
"type": "object", "type": "object",
"properties": { "properties": {
"name": { "name": {
"type": "string" "description": "Tag Name",
"type": "string",
"example": "Testjob"
}, },
"type": { "type": {
"type": "string" "description": "Tag Type",
"type": "string",
"example": "Debug"
} }
} }
}, },
"schema.Job": { "schema.Job": {
"description": "Meta data information of a HPC job.",
"type": "object", "type": "object",
"properties": { "properties": {
"arrayJobId": { "arrayJobId": {
"type": "integer" "description": "The unique identifier of an array job",
"type": "integer",
"example": 123000
}, },
"cluster": { "cluster": {
"type": "string" "description": "The unique identifier of a cluster",
"type": "string",
"example": "fritz"
}, },
"duration": { "duration": {
"type": "integer" "description": "Duration of job in seconds",
"type": "integer",
"minimum": 0,
"example": 43200
}, },
"exclusive": { "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": { "id": {
"description": "The unique identifier of a job in the database",
"type": "integer" "type": "integer"
}, },
"jobId": { "jobId": {
"type": "integer" "description": "The unique identifier of a job",
"type": "integer",
"example": 123000
}, },
"jobState": { "jobState": {
"type": "string" "description": "Final state of job",
"type": "string",
"enum": [
"completed",
"failed",
"cancelled",
"stopped",
"timeout",
"out_of_memory"
],
"example": "completed"
}, },
"metaData": { "metaData": {
"description": "Additional information about the job",
"type": "object", "type": "object",
"additionalProperties": { "additionalProperties": {
"type": "string" "type": "string"
} }
}, },
"monitoringStatus": { "monitoringStatus": {
"type": "integer" "description": "State of monitoring system during job run",
"type": "integer",
"example": 1
}, },
"numAcc": { "numAcc": {
"type": "integer" "description": "Number of accelerators used",
"type": "integer",
"minimum": 0,
"example": 2
}, },
"numHwthreads": { "numHwthreads": {
"type": "integer" "description": "Number of HWThreads used",
"type": "integer",
"minimum": 0,
"example": 20
}, },
"numNodes": { "numNodes": {
"type": "integer" "description": "Number of nodes used",
"type": "integer",
"minimum": 0,
"example": 2
}, },
"partition": { "partition": {
"type": "string" "description": "The Slurm partition to which the job was submitted",
"type": "string",
"example": "main"
}, },
"project": { "project": {
"type": "string" "description": "The unique identifier of a project",
"type": "string",
"example": "abcd200"
}, },
"resources": { "resources": {
"description": "Resources used by job",
"type": "array", "type": "array",
"items": { "items": {
"$ref": "#/definitions/schema.Resource" "$ref": "#/definitions/schema.Resource"
} }
}, },
"smt": { "smt": {
"type": "integer" "description": "SMT threads used by job",
"type": "integer",
"example": 4
}, },
"startTime": { "startTime": {
"description": "Start time as 'time.Time' data type",
"type": "string" "type": "string"
}, },
"subCluster": { "subCluster": {
"type": "string" "description": "The unique identifier of a sub cluster",
"type": "string",
"example": "main"
}, },
"tags": { "tags": {
"description": "List of tags",
"type": "array", "type": "array",
"items": { "items": {
"$ref": "#/definitions/schema.Tag" "$ref": "#/definitions/schema.Tag"
} }
}, },
"user": { "user": {
"type": "string" "description": "The unique identifier of a user",
"type": "string",
"example": "abcd100h"
}, },
"walltime": { "walltime": {
"type": "integer" "description": "Requested walltime of job in seconds",
"type": "integer",
"example": 86400
} }
} }
}, },
"schema.JobMeta": { "schema.JobMeta": {
"description": "Meta data information of a HPC job.",
"type": "object", "type": "object",
"properties": { "properties": {
"arrayJobId": { "arrayJobId": {
"type": "integer" "description": "The unique identifier of an array job",
"type": "integer",
"example": 123000
}, },
"cluster": { "cluster": {
"type": "string" "description": "The unique identifier of a cluster",
"type": "string",
"example": "fritz"
}, },
"duration": { "duration": {
"type": "integer" "description": "Duration of job in seconds",
"type": "integer",
"minimum": 0,
"example": 43200
}, },
"exclusive": { "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": { "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" "type": "integer"
}, },
"jobId": { "jobId": {
"type": "integer" "description": "The unique identifier of a job",
"type": "integer",
"example": 123000
}, },
"jobState": { "jobState": {
"type": "string" "description": "Final state of job",
"type": "string",
"enum": [
"completed",
"failed",
"cancelled",
"stopped",
"timeout",
"out_of_memory"
],
"example": "completed"
}, },
"metaData": { "metaData": {
"description": "Additional information about the job",
"type": "object", "type": "object",
"additionalProperties": { "additionalProperties": {
"type": "string" "type": "string"
} }
}, },
"monitoringStatus": { "monitoringStatus": {
"type": "integer" "description": "State of monitoring system during job run",
"type": "integer",
"example": 1
}, },
"numAcc": { "numAcc": {
"type": "integer" "description": "Number of accelerators used",
"type": "integer",
"minimum": 0,
"example": 2
}, },
"numHwthreads": { "numHwthreads": {
"type": "integer" "description": "Number of HWThreads used",
"type": "integer",
"minimum": 0,
"example": 20
}, },
"numNodes": { "numNodes": {
"type": "integer" "description": "Number of nodes used",
"type": "integer",
"minimum": 0,
"example": 2
}, },
"partition": { "partition": {
"type": "string" "description": "The Slurm partition to which the job was submitted",
"type": "string",
"example": "main"
}, },
"project": { "project": {
"type": "string" "description": "The unique identifier of a project",
"type": "string",
"example": "abcd200"
}, },
"resources": { "resources": {
"description": "Resources used by job",
"type": "array", "type": "array",
"items": { "items": {
"$ref": "#/definitions/schema.Resource" "$ref": "#/definitions/schema.Resource"
} }
}, },
"smt": { "smt": {
"type": "integer" "description": "SMT threads used by job",
"type": "integer",
"example": 4
}, },
"startTime": { "startTime": {
"type": "integer" "description": "Start epoch time stamp in seconds",
"type": "integer",
"minimum": 0,
"example": 1649723812
}, },
"statistics": { "statistics": {
"description": "Metric statistics of job",
"type": "object", "type": "object",
"additionalProperties": { "additionalProperties": {
"$ref": "#/definitions/schema.JobStatistics" "$ref": "#/definitions/schema.JobStatistics"
} }
}, },
"subCluster": { "subCluster": {
"type": "string" "description": "The unique identifier of a sub cluster",
"type": "string",
"example": "main"
}, },
"tags": { "tags": {
"description": "List of tags",
"type": "array", "type": "array",
"items": { "items": {
"$ref": "#/definitions/schema.Tag" "$ref": "#/definitions/schema.Tag"
} }
}, },
"user": { "user": {
"type": "string" "description": "The unique identifier of a user",
"type": "string",
"example": "abcd100h"
}, },
"walltime": { "walltime": {
"type": "integer" "description": "Requested walltime of job in seconds",
"type": "integer",
"example": 86400
} }
} }
}, },
"schema.JobStatistics": { "schema.JobStatistics": {
"description": "Specification for job metric statistics.",
"type": "object", "type": "object",
"properties": { "properties": {
"avg": { "avg": {
"type": "number" "description": "Job metric average",
"type": "number",
"minimum": 0,
"example": 2500
}, },
"max": { "max": {
"type": "number" "description": "Job metric maximum",
"type": "number",
"minimum": 0,
"example": 3000
}, },
"min": { "min": {
"type": "number" "description": "Job metric minimum",
"type": "number",
"minimum": 0,
"example": 2000
}, },
"unit": { "unit": {
"type": "string" "description": "Metric unit (see schema/unit.schema.json)",
"type": "string",
"example": "GHz"
} }
} }
}, },
"schema.Resource": { "schema.Resource": {
"description": "A resource used by a job",
"type": "object", "type": "object",
"properties": { "properties": {
"accelerators": { "accelerators": {
"description": "List of of accelerator device ids",
"type": "array", "type": "array",
"items": { "items": {
"type": "string" "type": "string"
} }
}, },
"configuration": { "configuration": {
"description": "The configuration options of the node",
"type": "string" "type": "string"
}, },
"hostname": { "hostname": {
"description": "Name of the host (= node)",
"type": "string" "type": "string"
}, },
"hwthreads": { "hwthreads": {
"description": "List of OS processor ids",
"type": "array", "type": "array",
"items": { "items": {
"type": "integer" "type": "integer"
@ -588,16 +713,22 @@
} }
}, },
"schema.Tag": { "schema.Tag": {
"description": "Defines a tag using name and type.",
"type": "object", "type": "object",
"properties": { "properties": {
"id": { "id": {
"description": "The unique DB identifier of a tag",
"type": "integer" "type": "integer"
}, },
"name": { "name": {
"type": "string" "description": "Tag Name",
"type": "string",
"example": "Testjob"
}, },
"type": { "type": {
"type": "string" "description": "Tag Type",
"type": "string",
"example": "Debug"
} }
} }
} }

228
api/swagger.yaml
View File

@ -1,7 +1,7 @@
basePath: /api basePath: /api
definitions: definitions:
api.ErrorResponse: api.ErrorResponse:
description: Error Response when using API. description: Error message as returned from backend.
properties: properties:
error: error:
description: Error Message description: Error Message
@ -18,186 +18,335 @@ definitions:
type: integer type: integer
type: object type: object
api.StopJobApiRequest: api.StopJobApiRequest:
description: 'Request to stop running job using stop time and state. Optional description: Request to stop running job using stoptime and final state. They
fields: JobId, ClusterId and StartTime. They are only used if no database id are only required if no database id was provided with endpoint.
was provided.'
properties: properties:
cluster: cluster:
description: Cluster of job (Optional) description: Cluster of job
example: fritz
type: string type: string
jobId: jobId:
description: Job ID of job (Optional) description: Cluster Job ID of job
example: 123000
type: integer type: integer
jobState: jobState:
description: Final job state description: Final state of job
enum:
- completed
- failed
- cancelled
- stopped
- timeout
example: completed
type: string type: string
startTime: startTime:
description: Start Time of job (Optional) description: Start Time of job as epoch
example: 1649723812
type: integer type: integer
stopTime: stopTime:
description: Stop Time as Epoch description: Stop Time of job as epoch
example: 1649763839
type: integer type: integer
required:
- jobState
- stopTime
type: object type: object
api.Tag: api.Tag:
description: Defines a tag using name and type.
properties: properties:
name: name:
description: Tag Name
example: Testjob
type: string type: string
type: type:
description: Tag Type
example: Debug
type: string type: string
type: object type: object
schema.Job: schema.Job:
description: Meta data information of a HPC job.
properties: properties:
arrayJobId: arrayJobId:
description: The unique identifier of an array job
example: 123000
type: integer type: integer
cluster: cluster:
description: The unique identifier of a cluster
example: fritz
type: string type: string
duration: duration:
description: Duration of job in seconds
example: 43200
minimum: 0
type: integer type: integer
exclusive: 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 type: integer
id: id:
description: The unique identifier of a job in the database
type: integer type: integer
jobId: jobId:
description: The unique identifier of a job
example: 123000
type: integer type: integer
jobState: jobState:
description: Final state of job
enum:
- completed
- failed
- cancelled
- stopped
- timeout
- out_of_memory
example: completed
type: string type: string
metaData: metaData:
additionalProperties: additionalProperties:
type: string type: string
description: Additional information about the job
type: object type: object
monitoringStatus: monitoringStatus:
description: State of monitoring system during job run
example: 1
type: integer type: integer
numAcc: numAcc:
description: Number of accelerators used
example: 2
minimum: 0
type: integer type: integer
numHwthreads: numHwthreads:
description: Number of HWThreads used
example: 20
minimum: 0
type: integer type: integer
numNodes: numNodes:
description: Number of nodes used
example: 2
minimum: 0
type: integer type: integer
partition: partition:
description: The Slurm partition to which the job was submitted
example: main
type: string type: string
project: project:
description: The unique identifier of a project
example: abcd200
type: string type: string
resources: resources:
description: Resources used by job
items: items:
$ref: '#/definitions/schema.Resource' $ref: '#/definitions/schema.Resource'
type: array type: array
smt: smt:
description: SMT threads used by job
example: 4
type: integer type: integer
startTime: startTime:
description: Start time as 'time.Time' data type
type: string type: string
subCluster: subCluster:
description: The unique identifier of a sub cluster
example: main
type: string type: string
tags: tags:
description: List of tags
items: items:
$ref: '#/definitions/schema.Tag' $ref: '#/definitions/schema.Tag'
type: array type: array
user: user:
description: The unique identifier of a user
example: abcd100h
type: string type: string
walltime: walltime:
description: Requested walltime of job in seconds
example: 86400
type: integer type: integer
type: object type: object
schema.JobMeta: schema.JobMeta:
description: Meta data information of a HPC job.
properties: properties:
arrayJobId: arrayJobId:
description: The unique identifier of an array job
example: 123000
type: integer type: integer
cluster: cluster:
description: The unique identifier of a cluster
example: fritz
type: string type: string
duration: duration:
description: Duration of job in seconds
example: 43200
minimum: 0
type: integer type: integer
exclusive: 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 type: integer
id: 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 type: integer
jobId: jobId:
description: The unique identifier of a job
example: 123000
type: integer type: integer
jobState: jobState:
description: Final state of job
enum:
- completed
- failed
- cancelled
- stopped
- timeout
- out_of_memory
example: completed
type: string type: string
metaData: metaData:
additionalProperties: additionalProperties:
type: string type: string
description: Additional information about the job
type: object type: object
monitoringStatus: monitoringStatus:
description: State of monitoring system during job run
example: 1
type: integer type: integer
numAcc: numAcc:
description: Number of accelerators used
example: 2
minimum: 0
type: integer type: integer
numHwthreads: numHwthreads:
description: Number of HWThreads used
example: 20
minimum: 0
type: integer type: integer
numNodes: numNodes:
description: Number of nodes used
example: 2
minimum: 0
type: integer type: integer
partition: partition:
description: The Slurm partition to which the job was submitted
example: main
type: string type: string
project: project:
description: The unique identifier of a project
example: abcd200
type: string type: string
resources: resources:
description: Resources used by job
items: items:
$ref: '#/definitions/schema.Resource' $ref: '#/definitions/schema.Resource'
type: array type: array
smt: smt:
description: SMT threads used by job
example: 4
type: integer type: integer
startTime: startTime:
description: Start epoch time stamp in seconds
example: 1649723812
minimum: 0
type: integer type: integer
statistics: statistics:
additionalProperties: additionalProperties:
$ref: '#/definitions/schema.JobStatistics' $ref: '#/definitions/schema.JobStatistics'
description: Metric statistics of job
type: object type: object
subCluster: subCluster:
description: The unique identifier of a sub cluster
example: main
type: string type: string
tags: tags:
description: List of tags
items: items:
$ref: '#/definitions/schema.Tag' $ref: '#/definitions/schema.Tag'
type: array type: array
user: user:
description: The unique identifier of a user
example: abcd100h
type: string type: string
walltime: walltime:
description: Requested walltime of job in seconds
example: 86400
type: integer type: integer
type: object type: object
schema.JobStatistics: schema.JobStatistics:
description: Specification for job metric statistics.
properties: properties:
avg: avg:
description: Job metric average
example: 2500
minimum: 0
type: number type: number
max: max:
description: Job metric maximum
example: 3000
minimum: 0
type: number type: number
min: min:
description: Job metric minimum
example: 2000
minimum: 0
type: number type: number
unit: unit:
description: Metric unit (see schema/unit.schema.json)
example: GHz
type: string type: string
type: object type: object
schema.Resource: schema.Resource:
description: A resource used by a job
properties: properties:
accelerators: accelerators:
description: List of of accelerator device ids
items: items:
type: string type: string
type: array type: array
configuration: configuration:
description: The configuration options of the node
type: string type: string
hostname: hostname:
description: Name of the host (= node)
type: string type: string
hwthreads: hwthreads:
description: List of OS processor ids
items: items:
type: integer type: integer
type: array type: array
type: object type: object
schema.Tag: schema.Tag:
description: Defines a tag using name and type.
properties: properties:
id: id:
description: The unique DB identifier of a tag
type: integer type: integer
name: name:
description: Tag Name
example: Testjob
type: string type: string
type: type:
description: Tag Type
example: Debug
type: string type: string
type: object type: object
host: localhost:8080 host: clustercockpit.localhost:8082
info: info:
contact: contact:
email: support@clustercockpit.org email: support@clustercockpit.org
name: ClusterCockpit project name: ClusterCockpit Project
url: TODO url: https://github.com/ClusterCockpit
description: Array of tag-objects for request payload description: Defines a tag using name and type.
license: license:
name: MIT License name: MIT License
url: https://opensource.org/licenses/MIT url: https://opensource.org/licenses/MIT
termsOfService: TODO termsOfService: https://monitoring.nhr.fau.de/imprint
title: ClusterCockpit REST API title: ClusterCockpit REST API
version: 0.1.0 version: 0.1.0
paths: paths:
@ -212,7 +361,7 @@ paths:
- running - running
- completed - completed
- failed - failed
- canceled - cancelled
- stopped - stopped
- timeout - timeout
in: query in: query
@ -222,8 +371,7 @@ paths:
in: query in: query
name: cluster name: cluster
type: string type: string
- description: 'Syntax: <from>-<to>, where <from> and <to> are unix timestamps - description: 'Syntax: ''$from-$to'', as unix epoch timestamps in seconds'
in seconds'
in: query in: query
name: start-time name: start-time
type: string type: string
@ -254,16 +402,14 @@ paths:
$ref: '#/definitions/api.ErrorResponse' $ref: '#/definitions/api.ErrorResponse'
security: security:
- ApiKeyAuth: [] - ApiKeyAuth: []
summary: List all jobs summary: Lists all jobs
tags:
- jobs
/jobs/start_job/: /jobs/start_job/:
post: post:
consumes: consumes:
- application/json - application/json
description: |- description: |-
A new job started. The body should be in the `meta.json` format Job specified in request body will be saved to database as "running" with new DB ID.
but some fields required there are optional here (e.g. `jobState` defaults to "running"). Job specifications follow the 'JobMeta' scheme, API will fail to execute if requirements are not met.
parameters: parameters:
- description: Job to add - description: Job to add
in: body in: body
@ -289,16 +435,12 @@ paths:
$ref: '#/definitions/api.ErrorResponse' $ref: '#/definitions/api.ErrorResponse'
security: security:
- ApiKeyAuth: [] - ApiKeyAuth: []
summary: Add a newly started job summary: Adds a new job as "running"
tags:
- jobs
/jobs/stop_job/: /jobs/stop_job/:
post: post:
consumes:
- application/json
description: |- description: |-
Job to stop is specified by request body. Job to stop is specified by request body. All fields are required in this case.
All fields are required in request body. Returns full job resource information according to 'JobMeta' scheme.
parameters: parameters:
- description: All fields required - description: All fields required
in: body in: body
@ -323,23 +465,21 @@ paths:
$ref: '#/definitions/api.ErrorResponse' $ref: '#/definitions/api.ErrorResponse'
security: security:
- ApiKeyAuth: [] - ApiKeyAuth: []
summary: Mark job as stopped and trigger archiving summary: Marks job as completed and triggers archiving
tags:
- jobs
/jobs/stop_job/{id}: /jobs/stop_job/{id}:
post: post:
consumes: consumes:
- application/json - application/json
description: |- description: |-
Job to stop is specified by database ID. Job to stop is specified by database ID. Only stopTime and final state are required in request body.
Only stopTime and final state are required in request body. Returns full job resource information according to 'JobMeta' scheme.
parameters: parameters:
- description: Database ID of Job - description: Database ID of Job
in: path in: path
name: id name: id
required: true required: true
type: integer type: integer
- description: 'Required fields: [stopTime, state]' - description: stopTime and final state in request body
in: body in: body
name: request name: request
required: true required: true
@ -351,7 +491,7 @@ paths:
"201": "201":
description: Job resource description: Job resource
schema: schema:
$ref: '#/definitions/schema.Job' $ref: '#/definitions/schema.JobMeta'
"400": "400":
description: Bad Request description: Bad Request
schema: schema:
@ -362,15 +502,14 @@ paths:
$ref: '#/definitions/api.ErrorResponse' $ref: '#/definitions/api.ErrorResponse'
security: security:
- ApiKeyAuth: [] - ApiKeyAuth: []
summary: Mark job as stopped and trigger archiving summary: Marks job as completed and triggers archiving
tags:
- jobs
/jobs/tag_job/{id}: /jobs/tag_job/{id}:
post: post:
consumes: consumes:
- application/json - application/json
description: Add one or more tags as array in request body to job specified description: |-
by DB ID. 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: parameters:
- description: Job Database ID - description: Job Database ID
in: path in: path
@ -382,7 +521,6 @@ paths:
name: request name: request
required: true required: true
schema: schema:
description: Array of tag-objects for request payload
items: items:
$ref: '#/definitions/api.Tag' $ref: '#/definitions/api.Tag'
type: array type: array
@ -403,9 +541,7 @@ paths:
$ref: '#/definitions/api.ErrorResponse' $ref: '#/definitions/api.ErrorResponse'
security: security:
- ApiKeyAuth: [] - ApiKeyAuth: []
summary: Add one or more tags to a job summary: Adds one or more tags to a job
tags:
- jobs
securityDefinitions: securityDefinitions:
ApiKeyAuth: ApiKeyAuth:
description: JWT based authentification for general API endpoint use. description: JWT based authentification for general API endpoint use.

316
internal/api/docs.go
View File

@ -1,5 +1,6 @@
// Package api GENERATED BY SWAG; DO NOT EDIT // 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 package api
import "github.com/swaggo/swag" import "github.com/swaggo/swag"
@ -10,10 +11,10 @@ const docTemplate = `{
"info": { "info": {
"description": "{{escape .Description}}", "description": "{{escape .Description}}",
"title": "{{.Title}}", "title": "{{.Title}}",
"termsOfService": "TODO", "termsOfService": "https://monitoring.nhr.fau.de/imprint",
"contact": { "contact": {
"name": "ClusterCockpit project", "name": "ClusterCockpit Project",
"url": "TODO", "url": "https://github.com/ClusterCockpit",
"email": "support@clustercockpit.org" "email": "support@clustercockpit.org"
}, },
"license": { "license": {
@ -39,17 +40,14 @@ const docTemplate = `{
"produces": [ "produces": [
"application/json" "application/json"
], ],
"tags": [ "summary": "Lists all jobs",
"jobs"
],
"summary": "List all jobs",
"parameters": [ "parameters": [
{ {
"enum": [ "enum": [
"running", "running",
"completed", "completed",
"failed", "failed",
"canceled", "cancelled",
"stopped", "stopped",
"timeout" "timeout"
], ],
@ -66,7 +64,7 @@ const docTemplate = `{
}, },
{ {
"type": "string", "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", "name": "start-time",
"in": "query" "in": "query"
}, },
@ -115,17 +113,14 @@ const docTemplate = `{
"ApiKeyAuth": [] "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": [ "consumes": [
"application/json" "application/json"
], ],
"produces": [ "produces": [
"application/json" "application/json"
], ],
"tags": [ "summary": "Adds a new job as \"running\"",
"jobs"
],
"summary": "Add a newly started job",
"parameters": [ "parameters": [
{ {
"description": "Job to add", "description": "Job to add",
@ -166,17 +161,11 @@ const docTemplate = `{
"ApiKeyAuth": [] "ApiKeyAuth": []
} }
], ],
"description": "Job to stop is specified by request body.\nAll fields are required in request body.", "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.",
"consumes": [
"application/json"
],
"produces": [ "produces": [
"application/json" "application/json"
], ],
"tags": [ "summary": "Marks job as completed and triggers archiving",
"jobs"
],
"summary": "Mark job as stopped and trigger archiving",
"parameters": [ "parameters": [
{ {
"description": "All fields required", "description": "All fields required",
@ -217,17 +206,14 @@ const docTemplate = `{
"ApiKeyAuth": [] "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": [ "consumes": [
"application/json" "application/json"
], ],
"produces": [ "produces": [
"application/json" "application/json"
], ],
"tags": [ "summary": "Marks job as completed and triggers archiving",
"jobs"
],
"summary": "Mark job as stopped and trigger archiving",
"parameters": [ "parameters": [
{ {
"type": "integer", "type": "integer",
@ -237,7 +223,7 @@ const docTemplate = `{
"required": true "required": true
}, },
{ {
"description": "Required fields: [stopTime, state]", "description": "stopTime and final state in request body",
"name": "request", "name": "request",
"in": "body", "in": "body",
"required": true, "required": true,
@ -250,7 +236,7 @@ const docTemplate = `{
"201": { "201": {
"description": "Job resource", "description": "Job resource",
"schema": { "schema": {
"$ref": "#/definitions/schema.Job" "$ref": "#/definitions/schema.JobMeta"
} }
}, },
"400": { "400": {
@ -275,17 +261,14 @@ const docTemplate = `{
"ApiKeyAuth": [] "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": [ "consumes": [
"application/json" "application/json"
], ],
"produces": [ "produces": [
"application/json" "application/json"
], ],
"tags": [ "summary": "Adds one or more tags to a job",
"jobs"
],
"summary": "Add one or more tags to a job",
"parameters": [ "parameters": [
{ {
"type": "integer", "type": "integer",
@ -300,7 +283,6 @@ const docTemplate = `{
"in": "body", "in": "body",
"required": true, "required": true,
"schema": { "schema": {
"description": "Array of tag-objects for request payload",
"type": "array", "type": "array",
"items": { "items": {
"$ref": "#/definitions/api.Tag" "$ref": "#/definitions/api.Tag"
@ -333,7 +315,7 @@ const docTemplate = `{
}, },
"definitions": { "definitions": {
"api.ErrorResponse": { "api.ErrorResponse": {
"description": "Error Response when using API.", "description": "Error message as returned from backend.",
"type": "object", "type": "object",
"properties": { "properties": {
"error": { "error": {
@ -357,236 +339,380 @@ const docTemplate = `{
} }
}, },
"api.StopJobApiRequest": { "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", "type": "object",
"required": [
"jobState",
"stopTime"
],
"properties": { "properties": {
"cluster": { "cluster": {
"description": "Cluster of job (Optional)", "description": "Cluster of job",
"type": "string" "type": "string",
"example": "fritz"
}, },
"jobId": { "jobId": {
"description": "Job ID of job (Optional)", "description": "Cluster Job ID of job",
"type": "integer" "type": "integer",
"example": 123000
}, },
"jobState": { "jobState": {
"description": "Final job state", "description": "Final state of job",
"type": "string" "type": "string",
"enum": [
"completed",
"failed",
"cancelled",
"stopped",
"timeout"
],
"example": "completed"
}, },
"startTime": { "startTime": {
"description": "Start Time of job (Optional)", "description": "Start Time of job as epoch",
"type": "integer" "type": "integer",
"example": 1649723812
}, },
"stopTime": { "stopTime": {
"description": "Stop Time as Epoch", "description": "Stop Time of job as epoch",
"type": "integer" "type": "integer",
"example": 1649763839
} }
} }
}, },
"api.Tag": { "api.Tag": {
"description": "Defines a tag using name and type.",
"type": "object", "type": "object",
"properties": { "properties": {
"name": { "name": {
"type": "string" "description": "Tag Name",
"type": "string",
"example": "Testjob"
}, },
"type": { "type": {
"type": "string" "description": "Tag Type",
"type": "string",
"example": "Debug"
} }
} }
}, },
"schema.Job": { "schema.Job": {
"description": "Meta data information of a HPC job.",
"type": "object", "type": "object",
"properties": { "properties": {
"arrayJobId": { "arrayJobId": {
"type": "integer" "description": "The unique identifier of an array job",
"type": "integer",
"example": 123000
}, },
"cluster": { "cluster": {
"type": "string" "description": "The unique identifier of a cluster",
"type": "string",
"example": "fritz"
}, },
"duration": { "duration": {
"type": "integer" "description": "Duration of job in seconds",
"type": "integer",
"minimum": 0,
"example": 43200
}, },
"exclusive": { "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": { "id": {
"description": "The unique identifier of a job in the database",
"type": "integer" "type": "integer"
}, },
"jobId": { "jobId": {
"type": "integer" "description": "The unique identifier of a job",
"type": "integer",
"example": 123000
}, },
"jobState": { "jobState": {
"type": "string" "description": "Final state of job",
"type": "string",
"enum": [
"completed",
"failed",
"cancelled",
"stopped",
"timeout",
"out_of_memory"
],
"example": "completed"
}, },
"metaData": { "metaData": {
"description": "Additional information about the job",
"type": "object", "type": "object",
"additionalProperties": { "additionalProperties": {
"type": "string" "type": "string"
} }
}, },
"monitoringStatus": { "monitoringStatus": {
"type": "integer" "description": "State of monitoring system during job run",
"type": "integer",
"example": 1
}, },
"numAcc": { "numAcc": {
"type": "integer" "description": "Number of accelerators used",
"type": "integer",
"minimum": 0,
"example": 2
}, },
"numHwthreads": { "numHwthreads": {
"type": "integer" "description": "Number of HWThreads used",
"type": "integer",
"minimum": 0,
"example": 20
}, },
"numNodes": { "numNodes": {
"type": "integer" "description": "Number of nodes used",
"type": "integer",
"minimum": 0,
"example": 2
}, },
"partition": { "partition": {
"type": "string" "description": "The Slurm partition to which the job was submitted",
"type": "string",
"example": "main"
}, },
"project": { "project": {
"type": "string" "description": "The unique identifier of a project",
"type": "string",
"example": "abcd200"
}, },
"resources": { "resources": {
"description": "Resources used by job",
"type": "array", "type": "array",
"items": { "items": {
"$ref": "#/definitions/schema.Resource" "$ref": "#/definitions/schema.Resource"
} }
}, },
"smt": { "smt": {
"type": "integer" "description": "SMT threads used by job",
"type": "integer",
"example": 4
}, },
"startTime": { "startTime": {
"description": "Start time as 'time.Time' data type",
"type": "string" "type": "string"
}, },
"subCluster": { "subCluster": {
"type": "string" "description": "The unique identifier of a sub cluster",
"type": "string",
"example": "main"
}, },
"tags": { "tags": {
"description": "List of tags",
"type": "array", "type": "array",
"items": { "items": {
"$ref": "#/definitions/schema.Tag" "$ref": "#/definitions/schema.Tag"
} }
}, },
"user": { "user": {
"type": "string" "description": "The unique identifier of a user",
"type": "string",
"example": "abcd100h"
}, },
"walltime": { "walltime": {
"type": "integer" "description": "Requested walltime of job in seconds",
"type": "integer",
"example": 86400
} }
} }
}, },
"schema.JobMeta": { "schema.JobMeta": {
"description": "Meta data information of a HPC job.",
"type": "object", "type": "object",
"properties": { "properties": {
"arrayJobId": { "arrayJobId": {
"type": "integer" "description": "The unique identifier of an array job",
"type": "integer",
"example": 123000
}, },
"cluster": { "cluster": {
"type": "string" "description": "The unique identifier of a cluster",
"type": "string",
"example": "fritz"
}, },
"duration": { "duration": {
"type": "integer" "description": "Duration of job in seconds",
"type": "integer",
"minimum": 0,
"example": 43200
}, },
"exclusive": { "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": { "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" "type": "integer"
}, },
"jobId": { "jobId": {
"type": "integer" "description": "The unique identifier of a job",
"type": "integer",
"example": 123000
}, },
"jobState": { "jobState": {
"type": "string" "description": "Final state of job",
"type": "string",
"enum": [
"completed",
"failed",
"cancelled",
"stopped",
"timeout",
"out_of_memory"
],
"example": "completed"
}, },
"metaData": { "metaData": {
"description": "Additional information about the job",
"type": "object", "type": "object",
"additionalProperties": { "additionalProperties": {
"type": "string" "type": "string"
} }
}, },
"monitoringStatus": { "monitoringStatus": {
"type": "integer" "description": "State of monitoring system during job run",
"type": "integer",
"example": 1
}, },
"numAcc": { "numAcc": {
"type": "integer" "description": "Number of accelerators used",
"type": "integer",
"minimum": 0,
"example": 2
}, },
"numHwthreads": { "numHwthreads": {
"type": "integer" "description": "Number of HWThreads used",
"type": "integer",
"minimum": 0,
"example": 20
}, },
"numNodes": { "numNodes": {
"type": "integer" "description": "Number of nodes used",
"type": "integer",
"minimum": 0,
"example": 2
}, },
"partition": { "partition": {
"type": "string" "description": "The Slurm partition to which the job was submitted",
"type": "string",
"example": "main"
}, },
"project": { "project": {
"type": "string" "description": "The unique identifier of a project",
"type": "string",
"example": "abcd200"
}, },
"resources": { "resources": {
"description": "Resources used by job",
"type": "array", "type": "array",
"items": { "items": {
"$ref": "#/definitions/schema.Resource" "$ref": "#/definitions/schema.Resource"
} }
}, },
"smt": { "smt": {
"type": "integer" "description": "SMT threads used by job",
"type": "integer",
"example": 4
}, },
"startTime": { "startTime": {
"type": "integer" "description": "Start epoch time stamp in seconds",
"type": "integer",
"minimum": 0,
"example": 1649723812
}, },
"statistics": { "statistics": {
"description": "Metric statistics of job",
"type": "object", "type": "object",
"additionalProperties": { "additionalProperties": {
"$ref": "#/definitions/schema.JobStatistics" "$ref": "#/definitions/schema.JobStatistics"
} }
}, },
"subCluster": { "subCluster": {
"type": "string" "description": "The unique identifier of a sub cluster",
"type": "string",
"example": "main"
}, },
"tags": { "tags": {
"description": "List of tags",
"type": "array", "type": "array",
"items": { "items": {
"$ref": "#/definitions/schema.Tag" "$ref": "#/definitions/schema.Tag"
} }
}, },
"user": { "user": {
"type": "string" "description": "The unique identifier of a user",
"type": "string",
"example": "abcd100h"
}, },
"walltime": { "walltime": {
"type": "integer" "description": "Requested walltime of job in seconds",
"type": "integer",
"example": 86400
} }
} }
}, },
"schema.JobStatistics": { "schema.JobStatistics": {
"description": "Specification for job metric statistics.",
"type": "object", "type": "object",
"properties": { "properties": {
"avg": { "avg": {
"type": "number" "description": "Job metric average",
"type": "number",
"minimum": 0,
"example": 2500
}, },
"max": { "max": {
"type": "number" "description": "Job metric maximum",
"type": "number",
"minimum": 0,
"example": 3000
}, },
"min": { "min": {
"type": "number" "description": "Job metric minimum",
"type": "number",
"minimum": 0,
"example": 2000
}, },
"unit": { "unit": {
"type": "string" "description": "Metric unit (see schema/unit.schema.json)",
"type": "string",
"example": "GHz"
} }
} }
}, },
"schema.Resource": { "schema.Resource": {
"description": "A resource used by a job",
"type": "object", "type": "object",
"properties": { "properties": {
"accelerators": { "accelerators": {
"description": "List of of accelerator device ids",
"type": "array", "type": "array",
"items": { "items": {
"type": "string" "type": "string"
} }
}, },
"configuration": { "configuration": {
"description": "The configuration options of the node",
"type": "string" "type": "string"
}, },
"hostname": { "hostname": {
"description": "Name of the host (= node)",
"type": "string" "type": "string"
}, },
"hwthreads": { "hwthreads": {
"description": "List of OS processor ids",
"type": "array", "type": "array",
"items": { "items": {
"type": "integer" "type": "integer"
@ -595,16 +721,22 @@ const docTemplate = `{
} }
}, },
"schema.Tag": { "schema.Tag": {
"description": "Defines a tag using name and type.",
"type": "object", "type": "object",
"properties": { "properties": {
"id": { "id": {
"description": "The unique DB identifier of a tag",
"type": "integer" "type": "integer"
}, },
"name": { "name": {
"type": "string" "description": "Tag Name",
"type": "string",
"example": "Testjob"
}, },
"type": { "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 // SwaggerInfo holds exported Swagger Info so clients can modify it
var SwaggerInfo = &swag.Spec{ var SwaggerInfo = &swag.Spec{
Version: "0.1.0", Version: "0.1.0",
Host: "localhost:8080", Host: "clustercockpit.localhost:8082",
BasePath: "/api", BasePath: "/api",
Schemes: []string{}, Schemes: []string{},
Title: "ClusterCockpit REST API", Title: "ClusterCockpit REST API",
Description: "Array of tag-objects for request payload", Description: "Defines a tag using name and type.",
InfoInstanceName: "swagger", InfoInstanceName: "swagger",
SwaggerTemplate: docTemplate, SwaggerTemplate: docTemplate,
} }

74
internal/api/rest.go
View File

@ -34,14 +34,18 @@ import (
// @title ClusterCockpit REST API // @title ClusterCockpit REST API
// @version 0.1.0 // @version 0.1.0
// @description API for batch job control. // @description API for batch job control.
// @termsOfService TODO // @termsOfService https://monitoring.nhr.fau.de/imprint
// @contact.name ClusterCockpit project
// @contact.url TODO // @contact.name ClusterCockpit Project
// @contact.url https://github.com/ClusterCockpit
// @contact.email support@clustercockpit.org // @contact.email support@clustercockpit.org
// @license.name MIT License // @license.name MIT License
// @license.url https://opensource.org/licenses/MIT // @license.url https://opensource.org/licenses/MIT
// @host localhost:8080
// @host clustercockpit.localhost:8082
// @BasePath /api // @BasePath /api
// @securityDefinitions.apikey ApiKeyAuth // @securityDefinitions.apikey ApiKeyAuth
// @in header // @in header
// @name X-Auth-Token // @name X-Auth-Token
@ -92,20 +96,19 @@ type StartJobApiResponse struct {
} }
// StopJobApiRequest model // StopJobApiRequest model
// @Description Request to stop running job using stop time and state. // @Description Request to stop running job using stoptime and final state.
// @Description Optional fields: JobId, ClusterId and StartTime. // @Description They are only required if no database id was provided with endpoint.
// @Description They are only used if no database id was provided.
type StopJobApiRequest struct { type StopJobApiRequest struct {
// Stop Time as Epoch // Stop Time of job as epoch
StopTime int64 `json:"stopTime"` StopTime int64 `json:"stopTime" validate:"required" example:"1649763839"`
State schema.JobState `json:"jobState"` // Final job state State schema.JobState `json:"jobState" validate:"required" example:"completed" enums:"completed,failed,cancelled,stopped,timeout"` // Final job state
JobId *int64 `json:"jobId"` // Job ID of job (Optional) JobId *int64 `json:"jobId" example:"123000"` // Cluster Job ID of job
Cluster *string `json:"cluster"` // Cluster of job (Optional) Cluster *string `json:"cluster" example:"fritz"` // Cluster of job
StartTime *int64 `json:"startTime"` // Start Time of job (Optional) StartTime *int64 `json:"startTime" example:"1649723812"` // Start Time of job as epoch
} }
// ErrorResponse model // ErrorResponse model
// @Description Error Response when using API. // @Description Error message as returned from backend.
type ErrorResponse struct { type ErrorResponse struct {
// Statustext of Errorcode // Statustext of Errorcode
Status string `json:"status"` Status string `json:"status"`
@ -116,8 +119,8 @@ type ErrorResponse struct {
// @Description Defines a tag using name and type. // @Description Defines a tag using name and type.
type Tag struct { type Tag struct {
// Tag Type // Tag Type
Type string `json:"type"` Type string `json:"type" example:"Debug"`
Name string `json:"name"` // Tag Name Name string `json:"name" example:"Testjob"` // Tag Name
} }
type TagJobApiRequest []*Tag type TagJobApiRequest []*Tag
@ -139,14 +142,13 @@ func decode(r io.Reader, val interface{}) error {
} }
// getJobs godoc // getJobs godoc
// @Summary List all jobs // @Summary Lists all jobs
// @Description Get a list of all jobs. Filters can be applied using query parameters. // @Description Get a list of all jobs. Filters can be applied using query parameters.
// @Tags jobs
// @Accept json // @Accept json
// @Produce 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 cluster query string false "Job Cluster"
// @Param start-time query string false "Syntax: <from>-<to>, where <from> and <to> 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 page query int false "Page Number"
// @Param items-per-page query int false "Items per page" // @Param items-per-page query int false "Items per page"
// @Param with-metadata query bool false "Include metadata in response" // @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 // tagJob godoc
// @Summary Add one or more tags to a job // @Summary Adds one or more tags to a job
// @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.
// @Tags jobs // @Description If tagged job is already finished: Tag will be written directly to respective archive files.
// @Accept json // @Accept json
// @Produce json // @Produce json
// @Param id path int true "Job Database ID" // @Param id path int true "Job Database ID"
@ -321,10 +323,9 @@ func (api *RestApi) tagJob(rw http.ResponseWriter, r *http.Request) {
} }
// startJob godoc // startJob godoc
// @Summary Add a newly started job // @Summary Adds a new job as "running"
// @Description A new job started. The body should be in the `meta.json` format // @Description Job specified in request body will be saved to database as "running" with new DB ID.
// @Description but some fields required there are optional here (e.g. `jobState` defaults to "running"). // @Description Job specifications follow the 'JobMeta' scheme, API will fail to execute if requirements are not met.
// @Tags jobs
// @Accept json // @Accept json
// @Produce json // @Produce json
// @Param request body schema.JobMeta true "Job to add" // @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 // stopJobById godoc
// @Summary Mark job as stopped and trigger archiving // @Summary Marks job as completed and triggers archiving
// @Description Job to stop is specified by database ID. // @Description Job to stop is specified by database ID. Only stopTime and final state are required in request body.
// @Description Only stopTime and final state are required in request body. // @Description Returns full job resource information according to 'JobMeta' scheme.
// @Tags jobs
// @Accept json // @Accept json
// @Produce json // @Produce json
// @Param id path int true "Database ID of Job" // @Param id path int true "Database ID of Job"
// @Param request body api.StopJobApiRequest true "Required fields: [stopTime, state]" // @Param request body api.StopJobApiRequest true "stopTime and final state in request body"
// @Success 201 {object} schema.Job "Job resource" // @Success 201 {object} schema.JobMeta "Job resource"
// @Failure 400 {object} api.ErrorResponse "Bad Request" // @Failure 400 {object} api.ErrorResponse "Bad Request"
// @Failure 404 {object} api.ErrorResponse "Resource not found" // @Failure 404 {object} api.ErrorResponse "Resource not found"
// @Security ApiKeyAuth // @Security ApiKeyAuth
@ -500,11 +500,9 @@ func (api *RestApi) stopJobById(rw http.ResponseWriter, r *http.Request) {
} }
// stopJobByRequest godoc // stopJobByRequest godoc
// @Summary Mark job as stopped and trigger archiving // @Summary Marks job as completed and triggers archiving
// @Description Job to stop is specified by request body. // @Description Job to stop is specified by request body. All fields are required in this case.
// @Description All fields are required in request body. // @Description Returns full job resource information according to 'JobMeta' scheme.
// @Tags jobs
// @Accept json
// @Produce json // @Produce json
// @Param request body api.StopJobApiRequest true "All fields required" // @Param request body api.StopJobApiRequest true "All fields required"
// @Success 201 {object} schema.JobMeta "Job resource" // @Success 201 {object} schema.JobMeta "Job resource"

123
pkg/schema/job.go
View File

@ -11,57 +11,70 @@ import (
"time" "time"
) )
// Common subset of Job and JobMeta. Use one of those, not // Non-Swaggered Comment: BaseJob
// this type directly. // Non-Swaggered Comment: Common subset of Job and JobMeta. Use one of those, not this type directly.
type BaseJob struct { type BaseJob struct {
JobID int64 `json:"jobId" db:"job_id"` // The unique identifier of a job
User string `json:"user" db:"user"` JobID int64 `json:"jobId" db:"job_id" example:"123000"`
Project string `json:"project" db:"project"` User string `json:"user" db:"user" example:"abcd100h"` // The unique identifier of a user
Cluster string `json:"cluster" db:"cluster"` Project string `json:"project" db:"project" example:"abcd200"` // The unique identifier of a project
SubCluster string `json:"subCluster" db:"subcluster"` Cluster string `json:"cluster" db:"cluster" example:"fritz"` // The unique identifier of a cluster
Partition string `json:"partition" db:"partition"` SubCluster string `json:"subCluster" db:"subcluster" example:"main"` // The unique identifier of a sub cluster
ArrayJobId int64 `json:"arrayJobId" db:"array_job_id"` Partition string `json:"partition" db:"partition" example:"main"` // The Slurm partition to which the job was submitted
NumNodes int32 `json:"numNodes" db:"num_nodes"` ArrayJobId int64 `json:"arrayJobId" db:"array_job_id" example:"123000"` // The unique identifier of an array job
NumHWThreads int32 `json:"numHwthreads" db:"num_hwthreads"` NumNodes int32 `json:"numNodes" db:"num_nodes" example:"2" minimum:"0"` // Number of nodes used
NumAcc int32 `json:"numAcc" db:"num_acc"` NumHWThreads int32 `json:"numHwthreads" db:"num_hwthreads" example:"20" minimum:"0"` // Number of HWThreads used
Exclusive int32 `json:"exclusive" db:"exclusive"` NumAcc int32 `json:"numAcc" db:"num_acc" example:"2" minimum:"0"` // Number of accelerators used
MonitoringStatus int32 `json:"monitoringStatus" db:"monitoring_status"` 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
SMT int32 `json:"smt" db:"smt"` MonitoringStatus int32 `json:"monitoringStatus" db:"monitoring_status" example:"1"` // State of monitoring system during job run
State JobState `json:"jobState" db:"job_state"` SMT int32 `json:"smt" db:"smt" example:"4"` // SMT threads used by job
Duration int32 `json:"duration" db:"duration"` State JobState `json:"jobState" db:"job_state" example:"completed" enums:"completed,failed,cancelled,stopped,timeout,out_of_memory"` // Final state of job
Walltime int64 `json:"walltime" db:"walltime"` Duration int32 `json:"duration" db:"duration" example:"43200" minimum:"0"` // Duration of job in seconds
Tags []*Tag `json:"tags"` Walltime int64 `json:"walltime" db:"walltime" example:"86400"` // Requested walltime of job in seconds
RawResources []byte `json:"-" db:"resources"` Tags []*Tag `json:"tags"` // List of tags
Resources []*Resource `json:"resources"` RawResources []byte `json:"-" db:"resources"` // Resources used by job [As Bytes]
RawMetaData []byte `json:"-" db:"meta_data"` Resources []*Resource `json:"resources"` // Resources used by job
MetaData map[string]string `json:"metaData"` 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 { type Job struct {
// The unique identifier of a job in the database
ID int64 `json:"id" db:"id"` ID int64 `json:"id" db:"id"`
BaseJob BaseJob
StartTimeUnix int64 `json:"-" db:"start_time"` StartTimeUnix int64 `json:"-" db:"start_time" example:"1649723812"` // Start epoch time stamp in seconds
StartTime time.Time `json:"startTime"` StartTime time.Time `json:"startTime"` // Start time as 'time.Time' data type
MemUsedMax float64 `json:"-" db:"mem_used_max"` MemUsedMax float64 `json:"-" db:"mem_used_max"` // MemUsedMax as Float64
FlopsAnyAvg float64 `json:"-" db:"flops_any_avg"` FlopsAnyAvg float64 `json:"-" db:"flops_any_avg"` // FlopsAnyAvg as Float64
MemBwAvg float64 `json:"-" db:"mem_bw_avg"` MemBwAvg float64 `json:"-" db:"mem_bw_avg"` // MemBwAvg as Float64
LoadAvg float64 `json:"-" db:"load_avg"` LoadAvg float64 `json:"-" db:"load_avg"` // LoadAvg as Float64
NetBwAvg float64 `json:"-" db:"net_bw_avg"` NetBwAvg float64 `json:"-" db:"net_bw_avg"` // NetBwAvg as Float64
NetDataVolTotal float64 `json:"-" db:"net_data_vol_total"` NetDataVolTotal float64 `json:"-" db:"net_data_vol_total"` // NetDataVolTotal as Float64
FileBwAvg float64 `json:"-" db:"file_bw_avg"` FileBwAvg float64 `json:"-" db:"file_bw_avg"` // FileBwAvg as Float64
FileDataVolTotal float64 `json:"-" db:"file_data_vol_total"` 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 // Non-Swaggered Comment: JobMeta
// convenient time.Time type. In the `meta.json` files, the start time is encoded as a unix epoch timestamp. // Non-Swaggered Comment: When reading from the database or sending data via GraphQL, the start time can be in the much more
// This is why there is this struct, which contains all fields from the regular job struct, but "overwrites" // Non-Swaggered Comment: convenient time.Time type. In the `meta.json` files, the start time is encoded as a unix epoch timestamp.
// the StartTime field with one of type int64. // 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 { 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 BaseJob
StartTime int64 `json:"startTime" db:"start_time"` StartTime int64 `json:"startTime" db:"start_time" example:"1649723812" minimum:"0"` // Start epoch time stamp in seconds
Statistics map[string]JobStatistics `json:"statistics,omitempty"` Statistics map[string]JobStatistics `json:"statistics,omitempty"` // Metric statistics of job
} }
const ( const (
@ -76,24 +89,32 @@ var JobDefaults BaseJob = BaseJob{
MonitoringStatus: MonitoringStatusRunningOrArchiving, MonitoringStatus: MonitoringStatusRunningOrArchiving,
} }
// JobStatistics model
// @Description Specification for job metric statistics.
type JobStatistics struct { type JobStatistics struct {
Unit string `json:"unit"` // Metric unit (see schema/unit.schema.json)
Avg float64 `json:"avg"` Unit string `json:"unit" example:"GHz"`
Min float64 `json:"min"` Avg float64 `json:"avg" example:"2500" minimum:"0"` // Job metric average
Max float64 `json:"max"` 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 { type Tag struct {
// The unique DB identifier of a tag
ID int64 `json:"id" db:"id"` ID int64 `json:"id" db:"id"`
Type string `json:"type" db:"tag_type"` Type string `json:"type" db:"tag_type" example:"Debug"` // Tag Type
Name string `json:"name" db:"tag_name"` Name string `json:"name" db:"tag_name" example:"Testjob"` // Tag Name
} }
// Resource model
// @Description A resource used by a job
type Resource struct { type Resource struct {
Hostname string `json:"hostname"` Hostname string `json:"hostname"` // Name of the host (= node)
HWThreads []int `json:"hwthreads,omitempty"` HWThreads []int `json:"hwthreads,omitempty"` // List of OS processor ids
Accelerators []string `json:"accelerators,omitempty"` Accelerators []string `json:"accelerators,omitempty"` // List of of accelerator device ids
Configuration string `json:"configuration,omitempty"` Configuration string `json:"configuration,omitempty"` // The configuration options of the node
} }
type JobState string type JobState string