get-metric-data

Описание

Вы можете использовать API GetMetricData для получения значений метрик CloudWatch. Операция также может включать запрос CloudWatch Metrics Insights и одну или несколько функций математических операций над метриками.

Операция GetMetricData, не включающая запрос, может получить до 500 различных метрик в одном запросе и до 100 800 точек данных. Вы также можете выполнять математические выражения над метриками для создания новых временных рядов, которые предоставляют новые сведения о ваших данных. Например, используя метрики Lambda, вы можете разделить метрику Ошибки на метрику Вызовов, чтобы получить временной ряд показателя ошибок. Дополнительные сведения о математических выражениях над метриками см. в руководстве пользователя Amazon CloudWatch в разделе Синтаксис и функции математических выражений над метриками.

Если вы включаете запрос Metrics Insights, каждая операция GetMetricData может содержать только один запрос. Но та же операция GetMetricData также может получать другие метрики. Запросы Metrics Insights могут запросить только данные о метриках за последние три часа. Дополнительные сведения о Metrics Insights см. в разделе Запрос метрик с помощью CloudWatch Metrics Insights.

Вызовы API GetMetricData имеют другую структуру ценообразования, чем вызовы GetMetricStatistics. Дополнительные сведения о ценообразовании см. в разделе Amazon CloudWatch Pricing.

Amazon CloudWatch сохраняет данные метрик следующим образом:

• Точки данных с периодом менее 60 секунд доступны в течение 3 часов. Эти данные — это метрики с высоким разрешением, и они доступны только для настраиваемых метрик, которые были определены с StorageResolution значением 1.
• Точки данных с периодом 60 секунд (1 минута) доступны в течение 15 дней.
• Точки данных с периодом 300 секунд (5 минут) доступны в течение 63 дней.
• Точки данных с периодом 3600 секунд (1 час) доступны в течение 455 дней (15 месяцев).

Точки данных, которые первоначально публикуются с более коротким периодом, агрегируются для долгосрочного хранения. Например, если вы собираете данные с периодом 1 минута, данные остаются доступными в течение 15 дней с разрешением 1 минута. По истечении 15 дней эти данные по-прежнему доступны, но агрегируются и доступны только с разрешением 5 минут. По истечении 63 дней данные дополнительно агрегируются и доступны с разрешением 1 час.

Если вы опустите Unit в запросе, будут возвращены все данные, собранные с любыми единицами, вместе с соответствующими единицами, которые были указаны при отправке данных в CloudWatch. Если вы укажете единицу, операция вернёт только данные, собранные с этой единицей. Если вы укажете единицу, которая не соответствует собранным данным, результаты операции будут null. CloudWatch не выполняет преобразование единиц.

Вы не можете смешивать запрос Metrics Insights и синтаксис математических операций над метриками в одном выражении, но вы можете ссылаться на результаты запроса Metrics Insights в других математических выражениях над метриками. Запрос Metrics Insights без условия GROUP BY возвращает один временной ряд (TS), который может быть использован в качестве входных данных для математического выражения над метриками, ожидающего один временной ряд. Запрос Metrics Insights с условием GROUP BY возвращает массив временных рядов (TS[]), который может быть использован в качестве входных данных для математического выражения над метриками, ожидающего массив временных рядов.

См. также: Документация API AWS

Операция get-metric-data является постраничной. Для получения всего набора результатов могут быть выполнены несколько вызовов API. Вы можете отключить постраничную обработку, указав аргумент --no-paginate. При использовании --output text и аргумента --query в постраничном ответе, аргумент --query должен извлекать данные из результатов следующих выражений запросов: MetricDataResults, Messages

Синтаксис

  get-metric-data
--metric-data-queries <value>
--start-time <value>
--end-time <value>
[--scan-by <value>]
[--label-options <value>]
[--cli-input-json | --cli-input-yaml]
[--starting-token <value>]
[--page-size <value>]
[--max-items <value>]
[--generate-cli-skeleton <value>]
[--debug]
[--endpoint-url <value>]
[--no-verify-ssl]
[--no-paginate]
[--output <value>]
[--query <value>]
[--profile <value>]
[--region <value>]
[--version <value>]
[--color <value>]
[--no-sign-request]
[--ca-bundle <value>]
[--cli-read-timeout <value>]
[--cli-connect-timeout <value>]
[--cli-binary-format <value>]
[--no-cli-pager]
[--cli-auto-prompt]
[--no-cli-auto-prompt]

Параметры

--metric-data-queries (список)

Синтаксис JSON:

[
  {
    "Id": "string",
    "MetricStat": {
      "Metric": {
        "Namespace": "string",
        "MetricName": "string",
        "Dimensions": [
          {
            "Name": "string",
            "Value": "string"
          }
          ...
        ]
      },
      "Period": integer,
      "Stat": "string",
      "Unit": "Seconds"|"Microseconds"|"Milliseconds"|"Bytes"|"Kilobytes"|"Megabytes"|"Gigabytes"|"Terabytes"|"Bits"|"Kilobits"|"Megabits"|"Gigabits"|"Terabits"|"Percent"|"Count"|"Bytes/Second"|"Kilobytes/Second"|"Megabytes/Second"|"Gigabytes/Second"|"Terabytes/Second"|"Bits/Second"|"Kilobits/Second"|"Megabits/Second"|"Gigabits/Second"|"Terabits/Second"|"Count/Second"|"None"
    },
    "Expression": "string",
    "Label": "string",
    "ReturnData": true|false,
    "Period": integer,
    "AccountId": "string"
  }
  ...
]

--start-time (отметка времени)

--end-time (отметка времени)

--scan-by (строка)

--label-options (структура)

Сокращенная синтаксическая запись:

Timezone=string

Синтаксис JSON:

{
  "Timezone": "string"
}

--cli-input-json | --cli-input-yaml (строка) Читает аргументы из предоставленной JSON-строки. JSON-строка соответствует формату, предоставленному --generate-cli-skeleton. Если на командной строке указаны другие аргументы, эти значения будут переопределять значения, предоставленные через JSON. Невозможно передавать произвольные двоичные значения с помощью значения JSON, так как строка будет воспринята буквально. Это не может быть указано вместе с --cli-input-yaml.

--starting-token (строка)

--page-size (целое число)

--max-items (целое число)

--generate-cli-skeleton (строка) Выводит JSON-скелет в стандартный вывод без отправки запроса к API. Если предоставлено значение без значения или значение input, выводится пример входного JSON, который может быть использован в качестве аргумента для --cli-input-json. Аналогично, если предоставлено yaml-input, будет напечатан пример входного YAML, который можно использовать с --cli-input-yaml. Если предоставлено значение output, это валидирует входные данные команды и возвращает пример выходного JSON для этой команды. Сгенерированный JSON-скелет нестабилен между версиями AWS CLI, и нет гарантий обратной совместимости в сгенерированном JSON-скелете.

Глобальные параметры

--debug (логическое значение)

Включить отладовую запись журнала.

--endpoint-url (строка)

Переопределить URL по умолчанию команды указанным URL.

--no-verify-ssl (логическое значение)

По умолчанию AWS CLI использует SSL при общении с AWS-сервисами. Для каждого SSL-соединения AWS CLI проверяет сертификаты SSL. Этот параметр переопределяет поведение по умолчанию проверки сертификатов SSL.

--no-paginate (логическое значение)

Отключить автоматический постраничный вывод. Если автоматический постраничный вывод отключен, AWS CLI выполнит только один вызов для первой страницы результатов.

--output (строка)

Стиль форматирования вывода команды.

• json
• text
• table
• yaml
• yaml-stream

--query (строка)

Запрос JMESPath для фильтрации данных ответа.

--profile (строка)

Использовать определённый профиль из файла аутентификации.

--region (строка)

Использовать определённый регион. Переопределяет настройки конфигурации/среды.

--version (строка)

Отобразить версию этого инструмента.

--color (строка)

Включить/отключить цветной вывод.

• on
• off
• auto

--no-sign-request (логическое значение)

Не подписывать запросы. Кредиты не будут загружаться, если этот аргумент указан.

--ca-bundle (строка)

Файл CA-сертификатов для проверки SSL-сертификатов. Переопределяет настройки конфигурации/среды.

--cli-read-timeout (целое число)

Максимальное время чтения сокета в секундах. Если значение установлено в 0, чтение сокета будет блокирующим и не будет иметь таймаута. Значение по умолчанию - 60 секунд.

--cli-connect-timeout (целое число)

Максимальное время подключения сокета в секундах. Если значение установлено в 0, подключение сокета будет блокирующим и не будет иметь таймаута. Значение по умолчанию - 60 секунд.

--cli-binary-format (строка)

Стиль форматирования, используемый для двоичных блоков. Формат по умолчанию - base64. Формат base64 ожидает, что двоичные блоки будут предоставлены как строка, закодированная в base64. Формат raw-in-base64-out сохраняет совместимость с поведением AWS CLI V1, а двоичные значения должны передаваться буквально. При предоставлении содержимого из файла, соответствующего двоичному блоку, fileb:// всегда будет обрабатываться как двоичный и использовать содержимое файла напрямую независимо от настройки cli-binary-format. При использовании file:// содержимое файла должно быть должным образом отформатировано для настроенного cli-binary-format.

• base64
• raw-in-base64-out

--no-cli-pager (логическое значение)

Отключить пагинатор CLI для вывода.

--cli-auto-prompt (логическое значение)

Автоматически запрашивать параметры ввода CLI.

--no-cli-auto-prompt (логическое значение)

Отключить автоматическое запрошение параметров ввода CLI.

Примеры

Пример 1: Получение среднего значения Total IOPS для указанного EC2 с использованием математического выражения

Следующий пример get-metric-data извлекает значения метрик CloudWatch для экземпляра EC2 с InstanceID i-abcdef, используя математическое выражение для метрик EBSReadOps и EBSWriteOps.

aws cloudwatch get-metric-data \
    --metric-data-queries file://file.json \
    --start-time 2024-09-29T22:10:00Z \
    --end-time 2024-09-29T22:15:00Z

Содержимое file.json:

[
    {
        "Id": "m3",
        "Expression": "(m1+m2)/300",
        "Label": "Avg Total IOPS"
    },
    {
        "Id": "m1",
        "MetricStat": {
            "Metric": {
                "Namespace": "AWS/EC2",
                "MetricName": "EBSReadOps",
                "Dimensions": [
                    {
                        "Name": "InstanceId",
                        "Value": "i-abcdef"
                    }
                ]
            },
            "Period": 300,
            "Stat": "Sum",
            "Unit": "Count"
        },
        "ReturnData": false
    },
    {
        "Id": "m2",
        "MetricStat": {
            "Metric": {
                "Namespace": "AWS/EC2",
                "MetricName": "EBSWriteOps",
                "Dimensions": [
                    {
                        "Name": "InstanceId",
                        "Value": "i-abcdef"
                    }
                ]
            },
            "Period": 300,
            "Stat": "Sum",
            "Unit": "Count"
        },
        "ReturnData": false
    }
]

Вывод:

{
    "MetricDataResults": [
        {
            "Id": "m3",
            "Label": "Avg Total IOPS",
            "Timestamps": [
                "2024-09-29T22:10:00+00:00"
            ],
            "Values": [
                96.85
            ],
            "StatusCode": "Complete"
        }
    ],
    "Messages": []
}

Пример 2: Мониторинг оценочных AWS-расходов с помощью метрик CloudWatch billing

Следующий пример get-metric-data извлекает метрику EstimatedCharges CloudWatch из пространства имён AWS/Billing.

aws cloudwatch get-metric-data \
    --metric-data-queries '[{"Id":"m1","MetricStat":{"Metric":{"Namespace":"AWS/Billing","MetricName":"EstimatedCharges","Dimensions":[{"Name":"Currency","Value":"USD"}]},"Period":21600,"Stat":"Maximum"}}]' \
    --start-time 2024-09-26T12:00:00Z \
    --end-time 2024-09-26T18:00:00Z \
    --region us-east-1

Вывод:

{
    "MetricDataResults": [
        {
            "Id": "m1",
            "Label": "EstimatedCharges",
            "Timestamps": [
                "2024-09-26T12:00:00+00:00"
            ],
            "Values": [
                542.38
            ],
            "StatusCode": "Complete"
        }
    ],
    "Messages": []
}

Дополнительную информацию см. в разделе Использование математических выражений с метриками CloudWatch в Руководстве пользователя Amazon CloudWatch.

Вывод

MetricDataResults -> (список)

NextToken -> (строка)

Messages -> (список)