logger.Logger¶
-
class
clearml.logger.
Logger
¶ The
Logger
class is the ClearML console log and metric statistics interface, and contains methods for explicit reporting.Explicit reporting extends ClearML automagical capturing of inputs and output. Explicit reporting methods include scalar plots, line plots, histograms, confusion matrices, 2D and 3D scatter diagrams, text logging, tables, and image uploading and reporting.
In the ClearML Web-App (UI),
Logger
output appears in the RESULTS tab, LOG, SCALARS, PLOTS, and DEBUG SAMPLES sub-tabs. When you compare experiments,Logger
output appears in the comparisons.Warning
Do not construct Logger objects directly.
You must get a Logger object before calling any of the other
Logger
class methods by callingTask.get_logger()
orLogger.current_logger()
.-
capture_logging
()¶ Return context capturing all the logs (via logging) reported under the context
- Returns
a ContextManager
-
classmethod
current_logger
()¶ Get the Logger object for the main execution Task, the current running Task, if one exists. If no Logger object exists, this method creates one and returns it. Therefore, you can call this method from anywhere in the code.
logger = Logger.current_logger()
- Returns
The Logger object (a singleton) for the current running Task.
-
flush
()¶ Flush cached reports and console outputs to backend.
- Returns
True, if successfully flushed the cache. False, if failed.
-
get_default_upload_destination
()¶ Get the destination storage URI (for example, S3, Google Cloud Storage, a file path) for uploading debug images (see
Logger.set_default_upload_destination()
).- Returns
The default upload destination URI.
For example:
s3://bucket/directory/
, orfile:///tmp/debug/
.
-
get_flush_period
()¶ Get the Logger flush period.
- Returns
The logger flush period in seconds.
-
report_confusion_matrix
(title, series, matrix, iteration, xaxis=None, yaxis=None, xlabels=None, ylabels=None, yaxis_reversed=False, comment=None, extra_layout=None)¶ For explicit reporting, plot a heat-map matrix.
For example:
confusion = np.random.randint(10, size=(10, 10)) logger.report_confusion_matrix("example confusion matrix", "ignored", iteration=1, matrix=confusion, xaxis="title X", yaxis="title Y")
- Parameters
title (str) – The title (metric) of the plot.
series (str) – The series name (variant) of the reported confusion matrix.
matrix (numpy.ndarray) – A heat-map matrix (example: confusion matrix)
iteration (int) – The iteration number.
xaxis (str) – The x-axis title. (Optional)
yaxis (str) – The y-axis title. (Optional)
xlabels (list(str)) – Labels for each column of the matrix. (Optional)
ylabels (list(str)) – Labels for each row of the matrix. (Optional)
yaxis_reversed (bool) – If False 0,0 is at the bottom left corner. If True 0,0 is at the Top left corner
comment (str) – A comment displayed with the plot, underneath the title.
extra_layout (dict) – optional dictionary for layout configuration, passed directly to plotly example: extra_layout={‘xaxis’: {‘type’: ‘date’, ‘range’: [‘2020-01-01’, ‘2020-01-31’]}}
-
report_histogram
(title, series, values, iteration, labels=None, xlabels=None, xaxis=None, yaxis=None, mode=None, extra_layout=None)¶ For explicit reporting, plot a (default grouped) histogram. Notice this function will not calculate the histogram, it assumes the histogram was already calculated in values
For example:
vector_series = np.random.randint(10, size=10).reshape(2,5) logger.report_histogram(title='histogram example', series='histogram series', values=vector_series, iteration=0, labels=['A','B'], xaxis='X axis label', yaxis='Y axis label')
You can view the reported histograms in the ClearML Web-App (UI), RESULTS tab, PLOTS sub-tab.
- Parameters
title (str) – The title (metric) of the plot.
series (str) – The series name (variant) of the reported histogram.
values (list(float), numpy.ndarray) – The series values. A list of floats, or an N-dimensional Numpy array containing data for each histogram bar.
iteration (int) – The iteration number. Each
iteration
creates another plot.labels (list(str)) – Labels for each bar group, creating a plot legend labeling each series. (Optional)
xlabels (list(str)) – Labels per entry in each bucket in the histogram (vector), creating a set of labels for each histogram bar on the x-axis. (Optional)
xaxis (str) – The x-axis title. (Optional)
yaxis (str) – The y-axis title. (Optional)
mode (str) – Multiple histograms mode, stack / group / relative. Default is ‘group’.
extra_layout (dict) – optional dictionary for layout configuration, passed directly to plotly example: extra_layout={‘xaxis’: {‘type’: ‘date’, ‘range’: [‘2020-01-01’, ‘2020-01-31’]}}
-
report_image
(title, series, iteration, local_path=None, image=None, matrix=None, max_image_history=None, delete_after_upload=False, url=None)¶ For explicit reporting, report an image and upload its contents.
This method uploads the image to a preconfigured bucket (see
Logger.setup_upload()
) with a key (filename) describing the task ID, title, series and iteration.For example:
matrix = np.eye(256, 256, dtype=np.uint8)*255 matrix = np.concatenate((np.atleast_3d(matrix), np.zeros((256, 256, 2), dtype=np.uint8)), axis=2) logger.report_image("test case", "image color red", iteration=1, image=m) image_open = Image.open(os.path.join("<image_path>", "<image_filename>")) logger.report_image("test case", "image PIL", iteration=1, image=image_open)
One and only one of the following parameters must be provided.
local_path
url
image
matrix
- Parameters
title (str) – The title (metric) of the image.
series (str) – The series name (variant) of the reported image.
iteration (int) – The iteration number.
local_path (str) – A path to an image file.
url (str) – A URL for the location of a pre-uploaded image.
image (numpy.ndarray, PIL.Image.Image) – Image data (RGB).
matrix (3D numpy.ndarray) –
Image data (RGB).
Note
The
matrix
paramater is deprecated. Use theimage
parameters.max_image_history (int) – The maximum number of images to store per metric/variant combination. For an unlimited number, use a negative value. The default value is set in global configuration (default=``5``).
delete_after_upload (bool) –
After the upload, delete the local copy of the image
The values are:
True
- Delete after upload.False
- Do not delete after upload. (default)
-
report_image_and_upload
(title, series, iteration, path=None, matrix=None, max_image_history=None, delete_after_upload=False)¶ Deprecated since version 0.13.0: Use
Logger.report_image()
instead
-
report_line_plot
(title, series, iteration, xaxis, yaxis, mode='lines', reverse_xaxis=False, comment=None, extra_layout=None)¶ For explicit reporting, plot one or more series as lines.
- Parameters
title (str) – The title (metric) of the plot.
series (list) – All the series data, one list element for each line in the plot.
iteration (int) – The iteration number.
xaxis (str) – The x-axis title. (Optional)
yaxis (str) – The y-axis title. (Optional)
mode (str) –
The type of line plot.
The values are:
lines
(default)markers
lines+markers
reverse_xaxis (bool) –
Reverse the x-axis
The values are:
True
- The x-axis is high to low (reversed).False
- The x-axis is low to high (not reversed). (default)
comment (str) – A comment displayed with the plot, underneath the title.
extra_layout (dict) – optional dictionary for layout configuration, passed directly to plotly example: extra_layout={‘xaxis’: {‘type’: ‘date’, ‘range’: [‘2020-01-01’, ‘2020-01-31’]}}
-
report_matplotlib_figure
(title, series, iteration, figure, report_image=False)¶ Report a
matplotlib
figure / plot directlymatplotlib.figure.Figure
/matplotlib.pyplot
- Parameters
title (str) – The title (metric) of the plot.
series (str) – The series name (variant) of the reported plot.
iteration (int) – The iteration number.
figure (MatplotlibFigure) – A
matplotlib
Figure objectreport_image – Default False. If True the plot will be uploaded as a debug sample (png image), and will appear under the debug samples tab (instead of the Plots tab).
-
report_matrix
(title, series, matrix, iteration, xaxis=None, yaxis=None, xlabels=None, ylabels=None, yaxis_reversed=False, extra_layout=None)¶ For explicit reporting, plot a confusion matrix.
Note
This method is the same as
Logger.report_confusion_matrix()
.- Parameters
title (str) – The title (metric) of the plot.
series (str) – The series name (variant) of the reported confusion matrix.
matrix (numpy.ndarray) – A heat-map matrix (example: confusion matrix)
iteration (int) – The iteration number.
xaxis (str) – The x-axis title. (Optional)
yaxis (str) – The y-axis title. (Optional)
xlabels (list(str)) – Labels for each column of the matrix. (Optional)
ylabels (list(str)) – Labels for each row of the matrix. (Optional)
yaxis_reversed (bool) – If False 0,0 is at the bottom left corner. If True 0,0 is at the Top left corner
extra_layout (dict) – optional dictionary for layout configuration, passed directly to plotly example: extra_layout={‘xaxis’: {‘type’: ‘date’, ‘range’: [‘2020-01-01’, ‘2020-01-31’]}}
-
report_media
(title, series, iteration, local_path=None, stream=None, file_extension=None, max_history=None, delete_after_upload=False, url=None)¶ Report media upload its contents, including images, audio, and video.
Media is uploaded to a preconfigured bucket (see setup_upload()) with a key (filename) describing the task ID, title, series and iteration.
One and only one of the following parameters must be provided
local_path
stream
url
If you use
stream
for a BytesIO stream to upload,file_extension
must be provided.- Parameters
title (str) – The title (metric) of the media.
series (str) – The series name (variant) of the reported media.
iteration (int) – The iteration number.
local_path (str) – A path to an media file.
stream – BytesIO stream to upload. If provided,
file_extension
must also be provided.url (str) – A URL to the location of a pre-uploaded media.
file_extension – A file extension to use when
stream
is passed.max_history (int) – The maximum number of media files to store per metric/variant combination use negative value for unlimited. default is set in global configuration (default=5)
delete_after_upload (bool) –
After the file is uploaded, delete the local copy
True
- DeleteFalse
- Do not delete
-
report_plotly
(title, series, iteration, figure)¶ Report a
Plotly
figure (plot) directlyPlotly
figure can be aplotly.graph_objs._figure.Figure
or a dictionary as defined byplotly.js
- Parameters
title (str) – The title (metric) of the plot.
series (str) – The series name (variant) of the reported plot.
iteration (int) – The iteration number.
figure (dict) – A
plotly
Figure object or apoltly
dictionary
-
report_scalar
(title, series, value, iteration)¶ For explicit reporting, plot a scalar series.
For example, plot a scalar series:
scalar_series = [random.randint(0,10) for i in range(10)] logger.report_scalar(title='scalar metrics','series', value=scalar_series[iteration], iteration=0)
You can view the scalar plots in the ClearML Web-App (UI), RESULTS tab, SCALARS sub-tab.
- Parameters
title (str) – The title (metric) of the plot. Plot more than one scalar series on the same plot by using the same
title
for each call to this method.series (str) – The series name (variant) of the reported scalar.
value (float) – The value to plot per iteration.
iteration (int) – The iteration number. Iterations are on the x-axis.
-
report_scatter2d
(title, series, scatter, iteration, xaxis=None, yaxis=None, labels=None, mode='lines', comment=None, extra_layout=None)¶ For explicit reporting, report a 2d scatter plot.
For example:
scatter2d = np.hstack((np.atleast_2d(np.arange(0, 10)).T, np.random.randint(10, size=(10, 1)))) logger.report_scatter2d(title="example_scatter", series="series", iteration=0, scatter=scatter2d, xaxis="title x", yaxis="title y")
Plot multiple 2D scatter series on the same plot by passing the same
title
anditeration
values to this method:scatter2d_1 = np.hstack((np.atleast_2d(np.arange(0, 10)).T, np.random.randint(10, size=(10, 1)))) logger.report_scatter2d(title="example_scatter", series="series_1", iteration=1, scatter=scatter2d_1, xaxis="title x", yaxis="title y") scatter2d_2 = np.hstack((np.atleast_2d(np.arange(0, 10)).T, np.random.randint(10, size=(10, 1)))) logger.report_scatter2d("example_scatter", "series_2", iteration=1, scatter=scatter2d_2, xaxis="title x", yaxis="title y")
- Parameters
title (str) – The title (metric) of the plot.
series (str) – The series name (variant) of the reported scatter plot.
scatter (list) – The scatter data. numpy.ndarray or list of (pairs of x,y) scatter:
iteration (int) – The iteration number. To set an initial iteration, for example to continue a previously
xaxis (str) – The x-axis title. (Optional)
yaxis (str) – The y-axis title. (Optional)
labels (list(str)) – Labels per point in the data assigned to the
scatter
parameter. The labels must be in the same order as the data.mode (str) –
The type of scatter plot.
The values are:
lines
markers
lines+markers
comment (str) – A comment displayed with the plot, underneath the title.
extra_layout (dict) – optional dictionary for layout configuration, passed directly to plotly example: extra_layout={‘xaxis’: {‘type’: ‘date’, ‘range’: [‘2020-01-01’, ‘2020-01-31’]}}
-
report_scatter3d
(title, series, scatter, iteration, xaxis=None, yaxis=None, zaxis=None, labels=None, mode='markers', fill=False, comment=None, extra_layout=None)¶ For explicit reporting, plot a 3d scatter graph (with markers).
- Parameters
title (str) – The title (metric) of the plot.
series (str) – The series name (variant) of the reported scatter plot.
list] scatter (Union[numpy.ndarray,) – The scatter data. list of (pairs of x,y,z), list of series [[(x1,y1,z1)…]], or numpy.ndarray
iteration (int) – The iteration number.
xaxis (str) – The x-axis title. (Optional)
yaxis (str) – The y-axis title. (Optional)
zaxis (str) – The z-axis title. (Optional)
labels (list(str)) – Labels per point in the data assigned to the
scatter
parameter. The labels must be in the same order as the data.mode (str) –
The type of scatter plot.
The values are:
lines
markers
lines+markers
For example:
scatter3d = np.random.randint(10, size=(10, 3)) logger.report_scatter3d(title="example_scatter_3d", series="series_xyz", iteration=1, scatter=scatter3d, xaxis="title x", yaxis="title y", zaxis="title z")
- Parameters
fill (bool) –
Fill the area under the curve
The values are:
True
- FillFalse
- Do not fill (default)
comment (str) – A comment displayed with the plot, underneath the title.
extra_layout (dict) – optional dictionary for layout configuration, passed directly to plotly example: extra_layout={‘xaxis’: {‘type’: ‘date’, ‘range’: [‘2020-01-01’, ‘2020-01-31’]}}
-
report_surface
(title, series, matrix, iteration, xaxis=None, yaxis=None, zaxis=None, xlabels=None, ylabels=None, camera=None, comment=None, extra_layout=None)¶ For explicit reporting, report a 3d surface plot.
Note
This method plots the same data as
Logger.report_confusion_matrix()
, but presents the data as a surface diagram not a confusion matrix.surface_matrix = np.random.randint(10, size=(10, 10)) logger.report_surface("example surface", "series", iteration=0, matrix=surface_matrix, xaxis="title X", yaxis="title Y", zaxis="title Z")
- Parameters
title (str) – The title (metric) of the plot.
series (str) – The series name (variant) of the reported surface.
matrix (numpy.ndarray) – A heat-map matrix (example: confusion matrix)
iteration (int) – The iteration number.
xaxis (str) – The x-axis title. (Optional)
yaxis (str) – The y-axis title. (Optional)
zaxis (str) – The z-axis title. (Optional)
xlabels (list(str)) – Labels for each column of the matrix. (Optional)
ylabels (list(str)) – Labels for each row of the matrix. (Optional)
camera (list(float)) – X,Y,Z coordinates indicating the camera position. The default value is
(1,1,1)
.comment (str) – A comment displayed with the plot, underneath the title.
extra_layout (dict) – optional dictionary for layout configuration, passed directly to plotly example: extra_layout={‘xaxis’: {‘type’: ‘date’, ‘range’: [‘2020-01-01’, ‘2020-01-31’]}}
-
report_table
(title, series, iteration, table_plot=None, csv=None, url=None, extra_layout=None)¶ For explicit report, report a table plot.
One and only one of the following parameters must be provided.
table_plot
- Pandas DataFrame or Table as list of rows (list)csv
- CSV fileurl
- URL to CSV file
For example:
df = pd.DataFrame({'num_legs': [2, 4, 8, 0], 'num_wings': [2, 0, 0, 0], 'num_specimen_seen': [10, 2, 1, 8]}, index=['falcon', 'dog', 'spider', 'fish']) logger.report_table(title='table example',series='pandas DataFrame',iteration=0,table_plot=df)
You can view the reported tables in the ClearML Web-App (UI), RESULTS tab, PLOTS sub-tab.
- Parameters
title (str) – The title (metric) of the table.
series (str) – The series name (variant) of the reported table.
iteration (int) – The iteration number.
table_plot (pandas.DataFrame or Table as list of rows (list)) – The output table plot object
csv (str) – path to local csv file
url (str) – A URL to the location of csv file.
extra_layout (dict) – optional dictionary for layout configuration, passed directly to plotly example: extra_layout={‘xaxis’: {‘type’: ‘date’, ‘range’: [‘2020-01-01’, ‘2020-01-31’]}}
-
report_text
(msg, level=20, print_console=True, *args, **_)¶ For explicit reporting, print text to the log. Optionally, print a log level and print to the console.
For example:
logger.report_text('log some text', level=logging.DEBUG, print_console=False)
You can view the reported text in the ClearML Web-App (UI), RESULTS tab, LOG sub-tab.
- Parameters
msg (str) – The text to log.
level (int) – The log level from the Python
logging
package. The default value islogging.INFO
.print_console (bool) –
In addition to the log, print to the console
The values are:
True
- Print to the console. (default)False
- Do not print to the console.
-
report_vector
(title, series, values, iteration, labels=None, xlabels=None, xaxis=None, yaxis=None, mode=None, extra_layout=None)¶ For explicit reporting, plot a vector as (default stacked) histogram.
For example:
vector_series = np.random.randint(10, size=10).reshape(2,5) logger.report_vector(title='vector example', series='vector series', values=vector_series, iteration=0, labels=['A','B'], xaxis='X axis label', yaxis='Y axis label')
You can view the vectors plots in the ClearML Web-App (UI), RESULTS tab, PLOTS sub-tab.
- Parameters
title (str) – The title (metric) of the plot.
series (str) – The series name (variant) of the reported histogram.
values (list(float), numpy.ndarray) – The series values. A list of floats, or an N-dimensional Numpy array containing data for each histogram bar.
iteration (int) – The iteration number. Each
iteration
creates another plot.labels (list(str)) – Labels for each bar group, creating a plot legend labeling each series. (Optional)
xlabels (list(str)) – Labels per entry in each bucket in the histogram (vector), creating a set of labels for each histogram bar on the x-axis. (Optional)
xaxis (str) – The x-axis title. (Optional)
yaxis (str) – The y-axis title. (Optional)
mode (str) – Multiple histograms mode, stack / group / relative. Default is ‘group’.
extra_layout (dict) – optional dictionary for layout configuration, passed directly to plotly example: extra_layout={‘xaxis’: {‘type’: ‘date’, ‘range’: [‘2020-01-01’, ‘2020-01-31’]}}
-
set_default_upload_destination
(uri)¶ Set the destination storage URI (for example, S3, Google Cloud Storage, a file path) for uploading debug images.
The images are uploaded separately. A link to each image is reported.
Note
Credentials for the destination storage are specified in the ClearML configuration file,
~/clearml.conf
.- Parameters
uri (str) – example: ‘s3://bucket/directory/’ or ‘file:///tmp/debug/’
- Returns
True, if the destination scheme is supported (for example,
s3://
,file://
, orgc://
). False, if not supported.
-
set_flush_period
(period)¶ Set the logger flush period.
Deprecated - Use
sdk.development.worker.report_period_sec
to externally control the flush period.- Parameters
period (float) – The period to flush the logger in seconds. To set no periodic flush, specify
None
or0
.
-
classmethod
tensorboard_auto_group_scalars
(group_scalars=False)¶ Group together TensorBoard scalars that do not have a title, or assign a title/series with the same tag.
- Parameters
group_scalars (bool) –
Group TensorBoard scalars without a title
The values are:
True
- Scalars without specific titles are grouped together in the “Scalars” plot, preserving backward compatibility with ClearML automagical behavior.False
- TensorBoard scalars without titles get a title/series with the same tag. (default)
-
classmethod
tensorboard_single_series_per_graph
(single_series=False)¶ Group TensorBoard scalar series together or in separate plots.
- Parameters
single_series (bool) –
Group TensorBoard scalar series together
The values are:
True
- Generate a separate plot for each TensorBoard scalar series.False
- Group the TensorBoard scalar series together in the same plot. (default)
-