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

1048 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
}
}
}
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.7" {
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). Otherwise from the earliest to the latest ones (in timestamp ascending order). The default is True"
}
refresh {
type: boolean
description: "If set then scroll will be moved to the latest logs (if 'navigate_earlier' is set to True) or to the earliest (otherwise)"
}
scroll_id {
type: string
description: "Scroll ID of previous call (used for getting more results)"
}
}
}
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"
}
scroll_id {
type: string
description: "Scroll ID for getting more results"
}
}
}
}
}
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 10000."
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"
type: array
items {
type: string
description: "List of task Task IDs"
}
}
samples {
description: "The amount of histogram points to return (0 to return all the points). Optional, the default value is 10000."
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)"
}
}
}
}
}
}