Add oadm top (images|imagestrams) commands

_build_cfg.yml

@@ -391,6 +391,9 @@ Topics:
   - Name: Scoped Tokens
     File: scoped_tokens
     Distros: openshift-origin
+  - Name: Monitoring Images
+    File: monitoring_images
+    Distros: openshift-origin,openshift-enterprise
   - Name: Managing the Default Image Streams and Templates
     File: osd_imagestreams_templates
     Distros: openshift-dedicated

admin_guide/monitoring_images.adoc

@@ -0,0 +1,83 @@
+[[admin-guide-monitoring-images]]
+= Monitoring images
+{product-author}
+{product-version}
+:data-uri:
+:icons:
+:experimental:
+:toc: macro
+:toc-title:
+
+toc::[]
+
+[[monitoring-images-overview]]
+== Overview
+
+You can monitor
+xref:../architecture/core_components/builds_and_image_streams.adoc#image-streams[images]
+in your instance using the xref:../cli_reference/index.adoc#cli-reference-index[CLI].
+
+[[monitoring-images-view-images]]
+== Viewing Images Statistics
+
+{product-title} can display several usage statistics about all the `*Images*` it
+manages. In other words, all the images pushed to the internal registry either
+xref:../install_config/install/docker_registry.adoc#access-pushing-and-pulling-images[directly]
+or through a xref:../dev_guide/builds.adoc#dev-guide-builds[Build].
+
+To view the usage statistics:
+
+====
+----
+$ oadm top images
+NAME                 IMAGESTREAMTAG            PARENTS                   USAGE                         METADATA    STORAGE
+sha256:80c985739a78b openshift/python (3.5)                                                            yes         303.12MiB
+sha256:64461b5111fc7 openshift/ruby (2.2)                                                              yes         234.33MiB
+sha256:0e19a0290ddc1 test/ruby-ex (latest)     sha256:64461b5111fc71ec   Deployment: ruby-ex-1/test    yes         150.65MiB
+sha256:a968c61adad58 test/django-ex (latest)   sha256:80c985739a78b760   Deployment: django-ex-1/test  yes         186.07MiB
+----
+====
+
+The command displays the following informations:
+
+- image ID
+- project, name, and tag of the accompanying `*ImageStreamTag*`
+- potential parents of the image, using their ID
+- information about where the image is being used
+- flag informing whether the image contains proper Docker metadata information
+- the size of the image
+
+
+[[monitoring-images-view-streams]]
+== Viewing ImageStreams Statistics
+
+{product-title} can display several usage statistics about all the `*ImageStreams*`.
+
+To view the usage statistics:
+
+====
+----
+$ oadm top imagestreams
+NAME                STORAGE     IMAGES  LAYERS
+openshift/python    1.21GiB     4       36
+openshift/ruby      717.76MiB   3       27
+test/ruby-ex        150.65MiB   1       10
+test/django-ex      186.07MiB   1       10
+----
+====
+
+The command displays the following informations:
+
+- project and name of the `*ImageStream*`
+- the size of the entire `*ImageStream*` stored in the internal
+xref:../install_config/install/docker_registry.adoc#install-config-install-docker-registry[docker registry]
+- number of `*Images*` this particular `*ImageStream*` is pointing to
+- number of layers `*ImageStream*` consists of
+
+
+[[monitoring-images-pruning]]
+== Pruning Images
+
+The information returned from the above commands is helpful when performing
+xref:pruning_resources.adoc#pruning-images[image pruning].
+