clearml-server/apiserver/schema/services/events.conf

1049 lines
35 KiB
Plaintext

{
_description : "Provides an API for running tasks to report events collected by the system."
_definitions {
metrics_scalar_event {
description: "Used for reporting scalar metrics during training task"
type: object
required: [ task, type ]
properties {
timestamp {
description: "Epoch milliseconds UTC, will be set by the server if not set."
type: number
}
type {
description: "training_stats_vector"
const: "training_stats_scalar"
}
task {
description: "Task ID (required)"
type: string
}
iter {
description: "Iteration"
type: integer
}
metric {
description: "Metric name, e.g. 'count', 'loss', 'accuracy'"
type: string
}
variant {
description: "E.g. 'class_1', 'total', 'average"
type: string
}
value {
description: ""
type: number
}
}
}
metrics_vector_event {
description: "Used for reporting vector metrics during training task"
type: object
required: [ task ]
properties {
timestamp {
description: "Epoch milliseconds UTC, will be set by the server if not set."
type: number
}
type {
description: "training_stats_vector"
const: "training_stats_vector"
}
task {
description: "Task ID (required)"
type: string
}
iter {
description: "Iteration"
type: integer
}
metric {
description: "Metric name, e.g. 'count', 'loss', 'accuracy'"
type: string
}
variant {
description: "E.g. 'class_1', 'total', 'average"
type: string
}
values {
description: "vector of float values"
type: array
items { type: number }
}
}
}
metrics_image_event {
description: "An image or video was dumped to storage for debugging"
type: object
required: [ task, type ]
properties {
timestamp {
description: "Epoch milliseconds UTC, will be set by the server if not set."
type: number
}
type {
description: ""
const: "training_debug_image"
}
task {
description: "Task ID (required)"
type: string
}
iter {
description: "Iteration"
type: integer
}
metric {
description: "Metric name, e.g. 'count', 'loss', 'accuracy'"
type: string
}
variant {
description: "E.g. 'class_1', 'total', 'average"
type: string
}
key {
description: "File key"
type: string
}
url {
description: "File URL"
type: string
}
}
}
metrics_plot_event {
description: """ An entire plot (not single datapoint) and it's layout.
Used for plotting ROC curves, confidence matrices, etc. when evaluating the net."""
type: object
required: [ task, type ]
properties {
timestamp {
description: "Epoch milliseconds UTC, will be set by the server if not set."
type: number
}
type {
description: "'plot'"
const: "plot"
}
task {
description: "Task ID (required)"
type: string
}
iter {
description: "Iteration"
type: integer
}
metric {
description: "Metric name, e.g. 'count', 'loss', 'accuracy'"
type: string
}
variant {
description: "E.g. 'class_1', 'total', 'average"
type: string
}
plot_str {
description: """An entire plot (not single datapoint) and it's layout.
Used for plotting ROC curves, confidence matrices, etc. when evaluating the net.
"""
type: string
}
skip_validation {
description: "If set then plot_str is not checked for a valid json. The default is False"
type: boolean
}
}
}
scalar_key_enum {
type: string
enum: [
iter
timestamp
iso_time
]
}
log_level_enum {
type: string
enum: [
notset
debug
verbose
info
warn
warning
error
fatal
critical
]
}
event_type_enum {
type: string
enum: [
training_stats_scalar
training_stats_vector
training_debug_image
plot
log
]
}
task_metric {
type: object
required: [task, metric]
properties {
task {
description: "Task ID"
type: string
}
metric {
description: "Metric name"
type: string
}
}
}
task_log_event {
description: """A log event associated with a task."""
type: object
required: [ task, type ]
properties {
timestamp {
description: "Epoch milliseconds UTC, will be set by the server if not set."
type: number
}
type {
description: "'log'"
const: "log"
}
task {
description: "Task ID (required)"
type: string
}
level {
description: "Log level."
"$ref": "#/definitions/log_level_enum"
}
worker {
description: "Name of machine running the task."
type: string
}
msg {
description: "Log message."
type: string
}
}
}
}
add {
"2.1" {
description: "Adds a single event"
request {
type: object
anyOf: [
{ "$ref": "#/definitions/metrics_scalar_event" }
{ "$ref": "#/definitions/metrics_vector_event" }
{ "$ref": "#/definitions/metrics_image_event" }
{ "$ref": "#/definitions/metrics_plot_event" }
{ "$ref": "#/definitions/task_log_event" }
]
}
response {
type: object
additionalProperties: true
}
}
}
add_batch {
"2.1" {
description: "Adds a batch of events in a single call (json-lines format, stream-friendly)"
batch_request: {
action: add
version: 1.5
}
response {
type: object
properties {
added { type: integer }
errors { type: integer }
errors_info { type: object }
}
}
}
}
delete_for_task {
"2.1" {
description: "Delete all task event. *This cannot be undone!*"
request {
type: object
required: [
task
]
properties {
task {
type: string
description: "Task ID"
}
allow_locked {
type: boolean
description: "Allow deleting events even if the task is locked"
default: false
}
}
}
response {
type: object
properties {
deleted {
type: boolean
description: "Number of deleted events"
}
}
}
}
}
debug_images {
"2.1" {
description: "Get all debug images of a task"
request {
type: object
required: [
task
]
properties {
task {
type: string
description: "Task ID"
}
iters {
type: integer
description: "Max number of latest iterations for which to return debug images"
}
scroll_id {
type: string
description: "Scroll ID of previous call (used for getting more results)"
}
}
}
response {
type: object
properties {
task {
type: string
description: "Task ID"
}
images {
type: array
items { type: object }
description: "Images list"
}
returned {
type: integer
description: "Number of results returned"
}
total {
type: number
description: "Total number of results available for this query"
}
scroll_id {
type: string
description: "Scroll ID for getting more results"
}
}
}
}
"2.7" {
description: "Get the debug image events for the requested amount of iterations per each task's metric"
request {
type: object
required: [
metrics
]
properties {
metrics {
type: array
items { "$ref": "#/definitions/task_metric" }
description: "List metrics for which the envents will be retreived"
}
iters {
type: integer
description: "Max number of latest iterations for which to return debug images"
}
navigate_earlier {
type: boolean
description: "If set then events are retreived from latest iterations to earliest ones. Otherwise from earliest iterations to the latest. The default is True"
}
refresh {
type: boolean
description: "If set then scroll will be moved to the latest iterations. The default is False"
}
scroll_id {
type: string
description: "Scroll ID of previous call (used for getting more results)"
}
}
}
response {
type: object
properties {
metrics {
type: array
items: { type: object }
description: "Debug image events grouped by task metrics and iterations"
}
scroll_id {
type: string
description: "Scroll ID for getting more results"
}
}
}
}
}
get_task_metrics{
"2.7": {
description: "For each task, get a list of metrics for which the requested event type was reported"
request {
type: object
required: [
tasks
]
properties {
tasks {
type: array
items { type: string }
description: "Task IDs"
}
event_type {
"description": "Event type"
"$ref": "#/definitions/event_type_enum"
}
}
}
response {
type: object
properties {
metrics {
type: array
items { type: object }
description: "List of task with their metrics"
}
}
}
}
}
get_task_log {
"1.5" {
description: "Get all 'log' events for this task"
request {
type: object
required: [
task
]
properties {
task {
type: string
description: "Task ID"
}
order {
type: string
description: "Timestamp order in which log events will be returned (defaults to ascending)"
enum: [
asc
desc
]
}
scroll_id {
type: string
description: ""
}
batch_size {
type: integer
description: ""
}
}
}
response {
type: object
properties {
events {
type: array
# TODO: items: log event
items { type: object }
}
returned { type: integer }
total { type: integer }
scroll_id { type: string }
}
}
}
"1.7" {
description: "Get all 'log' events for this task"
request {
type: object
required: [
task
]
properties {
task {
type: string
description: "Task ID"
}
order {
type: string
description: "Timestamp order in which log events will be returned (defaults to ascending)"
enum: [
asc
desc
]
}
from {
type: string
description: "Where will the log entries be taken from (default to the head of the log)"
enum: [
head
tail
]
}
scroll_id {
type: string
description: ""
}
batch_size {
type: integer
description: ""
}
}
}
response {
type: object
properties {
events {
type: array
# TODO: items: log event
items { type: object }
description: "Log items list"
}
returned {
type: integer
description: "Number of results returned"
}
total {
type: number
description: "Total number of results available for this query"
}
scroll_id {
type: string
description: "Scroll ID for getting more results"
}
}
}
}
"2.9" {
description: "Get 'log' events for this task"
request {
type: object
required: [
task
]
properties {
task {
type: string
description: "Task ID"
}
batch_size {
type: integer
description: "The amount of log events to return"
}
navigate_earlier {
type: boolean
description: "If set then log events are retreived from the latest to the earliest ones (in timestamp descending order, unless order='asc'). Otherwise from the earliest to the latest ones (in timestamp ascending order, unless order='desc'). The default is True"
}
from_timestamp {
type: number
description: "Epoch time in UTC ms to use as the navigation start. Optional. If not provided, reference timestamp is determined by the 'navigate_earlier' parameter (if true, reference timestamp is the last timestamp and if false, reference timestamp is the first timestamp)"
}
order {
type: string
description: "If set, changes the order in which log events are returned based on the value of 'navigate_earlier'"
enum: [asc, desc]
}
}
}
response {
type: object
properties {
events {
type: array
items { type: object }
description: "Log items list"
}
returned {
type: integer
description: "Number of log events returned"
}
total {
type: number
description: "Total number of log events available for this query"
}
}
}
}
}
get_task_events {
"2.1" {
description: "Scroll through task events, sorted by timestamp"
request {
type: object
required: [
task
]
properties {
task {
type: string
description: "Task ID"
}
order {
type:string
description: "'asc' (default) or 'desc'."
enum: [
asc
desc
]
}
scroll_id {
type: string
description: "Pass this value on next call to get next page"
}
batch_size {
type: integer
description: "Number of events to return each time (default 500)"
}
event_type {
type: string
description: "Return only events of this type"
}
}
}
response {
type: object
properties {
events {
type: array
items { type: object }
description: "Events list"
}
returned {
type: integer
description: "Number of results returned"
}
total {
type: number
description: "Total number of results available for this query"
}
scroll_id {
type: string
description: "Scroll ID for getting more results"
}
}
}
}
}
download_task_log {
"2.1" {
description: "Get an attachment containing the task's log"
request {
type: object
required: [
task
]
properties {
task {
description: "Task ID"
type: string
}
line_type {
description: "Line format type"
type: string
enum: [
json
text
]
}
line_format {
type: string
description: "Line string format. Used if the line type is 'text'"
default: "{asctime} {worker} {level} {msg}"
}
}
}
response {
type: string
}
}
}
get_task_plots {
"2.1" {
description: "Get all 'plot' events for this task"
request {
type: object
required: [
task
]
properties {
task {
type: string
description: "Task ID"
}
iters {
type: integer
description: "Max number of latest iterations for which to return debug images"
}
scroll_id {
type: string
description: "Scroll ID of previous call (used for getting more results)"
}
}
}
response {
type: object
properties {
plots {
type: array
items {
type: object
}
description: "Plots list"
}
returned {
type: integer
description: "Number of results returned"
}
total {
type: number
description: "Total number of results available for this query"
}
scroll_id {
type: string
description: "Scroll ID for getting more results"
}
}
}
}
}
get_multi_task_plots {
"2.1" {
description: "Get 'plot' events for the given tasks"
request {
type: object
required: [
tasks
]
properties {
tasks {
description: "List of task IDs"
type: array
items {
type: string
description: "Task ID"
}
}
iters {
type: integer
description: "Max number of latest iterations for which to return debug images"
}
scroll_id {
type: string
description: "Scroll ID of previous call (used for getting more results)"
}
}
}
response {
type: object
properties {
plots {
type: object
description: "Plots mapping (keyed by task name)"
}
returned {
type: integer
description: "Number of results returned"
}
total {
type: number
description: "Total number of results available for this query"
}
scroll_id {
type: string
description: "Scroll ID for getting more results"
}
}
}
}
}
get_vector_metrics_and_variants {
"2.1" {
description: ""
request {
type: object
required: [
task
]
properties {
task {
type: string
description: "Task ID"
}
}
}
response {
type: object
properties {
metrics {
description: ""
type: array
items: { type: object }
# TODO: items: ???
}
}
}
}
}
vector_metrics_iter_histogram {
"2.1" {
description: "Get histogram data of all the scalar metrics and variants in the task"
request {
type: object
required: [
task
metric
variant
]
properties {
task {
type: string
description: "Task ID"
}
metric {
type: string
description: ""
}
variant {
type: string
description: ""
}
}
}
response {
type: object
properties {
images {
type: array
items {
type: object
}
}
}
}
}
}
scalar_metrics_iter_histogram {
"2.1" {
description: "Get histogram data of all the vector metrics and variants in the task"
request {
type: object
required: [
task
]
properties {
task {
type: string
description: "Task ID"
}
samples {
description: "The amount of histogram points to return (0 to return all the points). Optional, the default value is 6000."
type: integer
}
key {
description: """
Histogram x axis to use:
iter - iteration number
iso_time - event time as ISO formatted string
timestamp - event timestamp as milliseconds since epoch
"""
"$ref": "#/definitions/scalar_key_enum"
}
}
}
response {
type: object
properties {
images {
type: array
items {
type: object
}
}
}
}
}
}
multi_task_scalar_metrics_iter_histogram {
"2.1" {
description: "Used to compare scalar stats histogram of multiple tasks"
request {
type: object
required: [
tasks
]
properties {
tasks {
description: "List of task Task IDs. Maximum amount of tasks is 10"
type: array
items {
type: string
description: "List of task Task IDs"
}
}
samples {
description: "The amount of histogram points to return. Optional, the default value is 6000"
type: integer
}
key {
description: """
Histogram x axis to use:
iter - iteration number
iso_time - event time as ISO formatted string
timestamp - event timestamp as milliseconds since epoch
"""
"$ref": "#/definitions/scalar_key_enum"
}
}
}
response {
type: object
// properties {}
additionalProperties: true
}
}
}
get_task_latest_scalar_values {
"2.1" {
description: "Get the tasks's latest scalar values"
request {
type: object
required: [
task
]
properties {
task {
type: string
description: "Task ID"
}
}
}
response {
type: object
properties {
metrics {
type: array
items {
type: object
properties {
name {
type: string
description: "Metric name"
}
variants {
type: array
items {
type: object
properties {
name {
type: string
description: "Variant name"
}
last_value {
type: number
description: "Last reported value"
}
last_100_value {
type: number
description: "Average of 100 last reported values"
}
}
}
}
}
}
}
}
}
}
}
get_scalar_metrics_and_variants {
"2.1" {
description: get task scalar metrics and variants
request {
type: object
required: [ task ]
properties {
task {
description: task ID
type: string
}
}
}
response {
type: object
properties {
metrics {
type: object
additionalProperties: true
}
}
}
}
}
get_scalar_metric_data {
"2.1" {
description: "get scalar metric data for task"
request {
type: object
properties {
task {
type: string
description: task ID
}
metric {
type: string
description: type of metric
}
}
}
response {
type: object
properties {
events {
description: "task scalar metric events"
type: array
items {
type: object
}
}
returned {
type: integer
description: "amount of events returned"
}
total {
type: integer
description: "amount of events in task"
}
scroll_id {
type: string
description: "Scroll ID of previous call (used for getting more results)"
}
}
}
}
}
}