# Module `netapp_ontap.resources.top_metrics_directory`

Copyright © 2022 NetApp Inc. All rights reserved.

## Overview

You can use this API to retrieve a list of directories with the most IO activity for a specified volume. Use the `top_metric` parameter to specify which type of IO activity to filter for. This API is used to provide insight into IO activity and supports ordering by IO activity types, namely `iops` and `throughput` metrics. This API supports only returning one IO activity type per request.

## Retrieve a list of the directories with the most IO activity

For a report on the directories with the most IO activity returned in descending order, specify the IO activity type you want to filter for by passing the `iops` or `throughput` property into the top_metric parameter. If the IO activity type is not specified, by default the API returns a list of directories with the greatest number of average read operations per second. The maximum number of directories returned by the API for an IO activity type is 25.

- GET /api/storage/volumes/{volume.uuid}/top-metrics/directories

## Examples

### Retrieving a list of the directories with the greatest average number of read operations per second:

    from netapp_ontap import HostConnection
    from netapp_ontap.resources import TopMetricsDirectory

    with HostConnection("<mgmt-ip>", username="admin", password="password", verify=False):
        print(
            list(
                TopMetricsDirectory.get_collection("{volume.uuid}", top_metric="iops.read")
            )
        )

Try it out

    [
        TopMetricsDirectory(
            {
                "svm": {
                    "_links": {
                        "self": {
                            "href": "/api/svm/svms/572361f3-e769-439d-9c04-2ba48a08ff43"
                        }
                    },
                    "uuid": "572361f3-e769-439d-9c04-2ba48a08ff43",
                    "name": "vs1",
                },
                "volume": {"name": "vol1"},
                "iops": {"error": {"upper_bound": 1505, "lower_bound": 1495}, "read": 1495},
                "path": "/dir1/dir2",
                "_links": {
                    "metadata": {
                        "href": "/api/storage/volumes/73b293df-e9d7-46cc-a9ce-2df8e52ef864/files/dir1%2Fdir2?return_metadata=true"
                    }
                },
            }
        ),
        TopMetricsDirectory(
            {
                "svm": {
                    "_links": {
                        "self": {
                            "href": "/api/svm/svms/572361f3-e769-439d-9c04-2ba48a08ff43"
                        }
                    },
                    "uuid": "572361f3-e769-439d-9c04-2ba48a08ff43",
                    "name": "vs1",
                },
                "volume": {"name": "vol1"},
                "iops": {"error": {"upper_bound": 1032, "lower_bound": 1022}, "read": 1022},
                "path": "/dir3/dir4",
                "_links": {
                    "metadata": {
                        "href": "/api/storage/volumes/73b293df-e9d7-46cc-a9ce-2df8e52ef864/files/dir3%2Fdir4?return_metadata=true"
                    }
                },
            }
        ),
        TopMetricsDirectory(
            {
                "svm": {
                    "_links": {
                        "self": {
                            "href": "/api/svm/svms/572361f3-e769-439d-9c04-2ba48a08ff43"
                        }
                    },
                    "uuid": "572361f3-e769-439d-9c04-2ba48a08ff43",
                    "name": "vs1",
                },
                "volume": {
                    "_links": {
                        "self": {
                            "href": "/api/storage/volumes/73b293df-e9d7-46cc-a9ce-2df8e52ef864"
                        }
                    },
                    "uuid": "73b293df-e9d7-46cc-a9ce-2df8e52ef864",
                    "name": "vol1",
                },
                "iops": {"error": {"upper_bound": 355, "lower_bound": 345}, "read": 345},
                "path": "/dir12",
                "_links": {
                    "metadata": {
                        "href": "/api/storage/volumes/73b293df-e9d7-46cc-a9ce-2df8e52ef864/files/dir12?return_metadata=true"
                    }
                },
            }
        ),
    ]

## Classes

`class TopMetricsDirectory (*args, **kwargs)`

  Information about a directory's IO activity.

  Initialize the instance of the resource.

  Any keyword arguments are set on the instance as properties. For example, if the class was named 'MyResource', then this statement would be true:

      MyResource(name='foo').name == 'foo'

  ## Args

  `*args`
    Each positional argument represents a parent key as used in the URL of the object. That is, each value will be used to fill in a segment of the URL which refers to some parent object. The order of these arguments must match the order they are specified in the URL, from left to right.
  `**kwargs`
    each entry will have its key set as an attribute name on the instance and its value will be the value of that attribute.

  ### Ancestors

  - Resource

  ### Static methods

  `def count_collection(*args, connection: HostConnection = None, **kwargs) -> int`

    Fetch a count of all objects of this type from the host.

    This calls GET on the object to determine the number of records. It is more efficient than calling get_collection() because it will not construct any objects. Query parameters can be passed in as kwargs to determine a count of objects that match some filtered criteria.

    ## Args

    `*args`
      Each entry represents a parent key which is used to build the path to the child object. If the URL definition were /api/foos/{foo.name}/bars, then to get the count of bars for a particular foo, the foo.name value should be passed.
    `connection`
      The `HostConnection` object to use for this API call. If unset, tries to use the connection which is set globally for the library or from the current context.
    `**kwargs`
      Any key/value pairs passed will be sent as query parameters to the host. These query parameters can affect the count. A return_records query param will be ignored.

    ## Returns

    On success, returns an integer count of the objects of this type. On failure, returns -1.

    ## Raises

    `NetAppRestError`: If the API call returned a status code >= 400, or if there is no connection available to use either passed in or on the library.

  `def find(*args, connection: HostConnection = None, **kwargs) -> Resource`

    Retrieves a list of directories with the most IO activity.

    ### Learn more

    - `DOC /storage/volumes/{volume.uuid}/top-metrics/directories`

    Find an instance of an object on the host given a query.

    The host will be queried with the provided key/value pairs to find a matching resource. If 0 are found, None will be returned. If more than 1 is found, an error will be raised or returned. If there is exactly 1 matching record, then it will be returned.

    ## Args

    `*args`
      Each entry represents a parent key which is used to build the path to the child object. If the URL definition were /api/foos/{foo.name}/bars, then to find a bar for a particular foo, the foo.name value should be passed.
    `connection`
      The `HostConnection` object to use for this API call. If unset, tries to use the connection which is set globally for the library or from the current context.
    `**kwargs`
      Any key/value pairs passed will be sent as query parameters to the host.

    ## Returns

    A `Resource` object containing the details of the object or None if no matches were found.

    ## Raises

    `NetAppRestError`: If the API call returned more than 1 matching resource.

  `def get_collection(*args, connection: HostConnection = None, max_records: int = None, **kwargs) -> Iterable[Resource]`

    Retrieves a list of directories with the most IO activity.

    ### Learn more

    - `DOC /storage/volumes/{volume.uuid}/top-metrics/directories`

    Fetch a list of all objects of this type from the host.

    This is a lazy fetch, making API calls only as necessary when the result of this call is iterated over. For instance, if max_records is set to 5, then iterating over the collection causes an API call to be sent to the server once for every 5 records. If the client stops iterating before getting to the 6th record, then no additional API calls are made.

    ## Args

    `*args`
      Each entry represents a parent key which is used to build the path to the child object. If the URL definition were /api/foos/{foo.name}/bars, then to get the collection of bars for a particular foo, the foo.name value should be passed.
    `connection`
      The `HostConnection` object to use for this API call. If unset, tries to use the connection which is set globally for the library or from the current context.
    `max_records`
      The maximum number of records to return per call
    `**kwargs`
      Any key/value pairs passed will be sent as query parameters to the host.

    ## Returns

    A list of `Resource` objects

    ## Raises

    `NetAppRestError`: If there is no connection available to use either passed in or on the library. This would be not be raised when get_collection() is called, but rather when the result is iterated.

  ### Inherited members

  - `Resource`:
    - `from_dict`
    - `get_collection_url`
    - `get_connection`
    - `instance_location`
    - `path_keys`
    - `poll`
    - `set_connection`
    - `to_dict`
`class TopMetricsDirectorySchema (*, only: Union[Sequence[str], Set[str]] = None, exclude: Union[Sequence[str], Set[str]] = (), many: bool = False, context: Dict = None, load_only: Union[Sequence[str], Set[str]] = (), dump_only: Union[Sequence[str], Set[str]] = (), partial: Union[bool, Sequence[str], Set[str]] = False, unknown: str = None)`

  The fields of the TopMetricsDirectory object

  ### Ancestors

  - netapp_ontap.resource.ResourceSchema
  - marshmallow.schema.Schema
  - marshmallow.base.SchemaABC

  ### Class variables

  `iops GET POST PATCH`

    The iops field of the top_metrics_directory.

  `links GET`

    The links field of the top_metrics_directory.

  `path GET`

    Path of the directory.

    Example: /dir_abc/dir_123/dir_20

  `svm GET POST PATCH`

    The svm field of the top_metrics_directory.

  `throughput GET POST PATCH`

    The throughput field of the top_metrics_directory.

  `volume GET POST PATCH`

    The volume field of the top_metrics_directory.