Verwendungsberichte Endpunkt

Die Endpunkte der Nutzungsberichte werden verwendet, um Nutzungsmuster für „ AWS EC2 “-Instanzen zu analysieren. Die Nutzungsanalyse verwendet Daten aus „ AWS “ Cloudwatch, die Details auf Instanzebene wie durchschnittliche CPU-Auslastung (Prozent), Bandbreite und Festplatten-E/A anzeigen. Auslastungsanalysen eignen sich hervorragend, um die Gesamtelastizität zu visualisieren und festzustellen, ob Ihre Instanzen angepasst oder abgeschaltet werden müssen.

Die Kostenmetriken, die in Utilization Analytics verfügbar sind, werden in Cloudability unter Verwendung von On-Demand-Tarifen berechnet und decken nur den Rechenanteil Ihrer Rechnung ab (d. h. die abrechenbaren Instanzstunden, nicht aber Bandbreite, Speicherplatz usw.). Als solche sollten sie nur für die Trendentwicklung und nicht für die Finanzberichterstattung verwendet werden. Beachten Sie, dass die Metrik als Kosten (geschätzt) bezeichnet wird.

Beachten Sie, dass Utilization Analytics nur dann auf Nutzungsdaten zugreifen kann, wenn für die jeweiligen Mitgliedskonten erweiterte Berechtigungen eingerichtet sind, die die entsprechenden IAM-Berechtigungen ermöglichen.

Durch flexibles Filtern, Sortieren und Auswählen von Messgrößen (Dimensionen und Metriken) können die Ergebnisse so gestaltet werden, dass sie spezifischen Berichtsanforderungen entsprechen. Als empfohlene Richtlinie gilt, dass maximal 15 Dimensionen und 10 Metriken zu einem API-Aufruf hinzugefügt werden können. Standardmäßig werden die Ergebnisse in JSON zurückgegeben. Um Ergebnisse im CSV-Format zu erhalten, stellen Sie sicher, dass Sie den Accept-Header mit dem Wert „text/ CSV “ setzen. Beachten Sie, dass eine Paginierung implementiert wird, wenn die Ergebnisse 10.000 Zeilen überschreiten, wie unten beschrieben. Beispiele für Berichtsaufrufe finden Sie am Ende dieses Dokuments.

Endpunkt des Verwendungsberichts

• /reporting/reports/util zur Auflistung aktueller Nutzungsberichte
• /reporting/util/run zur Ausführung von Nutzungsberichten
• /reporting/util/measures zur Auflistung der verfügbaren Maßnahmen zur Nutzungsberichterstattung
• /reporting/util/filters zur Auflistung der in Filtern verwendeten Vergleichsoperatoren
• /reporting/util/enqueue zum Einreihen von util-Berichten
• /reporting/reports/:id/state zur Überprüfung des Status von Berichten in der Warteschlange
• /reporting/reports/:id/results zum Abrufen von fertigen Berichten in der Warteschlange

Das Objekt Verwendungsbericht

• ergebnisse (Array) - Liste von Nutzungsreihenobjekten, wobei jede Reihe aus den berichteten Dimensionen und Metriken besteht
• meta (Objekt) - Objekt mit Metainformationen über den ausgeführten Bericht
  • dates (Objekt) - Zeichenfolgen für Anfangs- und Enddatum, die den Datumsbereich des Berichts angeben
  • filters (array) - Liste der auf den Bericht angewandten Filter mit detaillierten Informationen
  • metrics (array) - Liste der im Bericht zurückgegebenen Metriken mit detaillierten Informationen
  • dimensions (array) - Liste der im Bericht zurückgegebenen Dimensionen mit detaillierten Informationen
  • aggregates (array) - Liste der aggregierten Metriken mit detaillierten Informationen für den Bericht
  • offset (Zahl) - Position, an der die Ergebnisse beginnen sollen. Standardwert ist 0
  • limit (number) - Maximale Anzahl von Nutzungszeilen, die zurückgegeben werden können
  • total_results (Zahl) - Summe der für den ausgeführten Bericht zurückgegebenen Nutzungszeilen

Beispiel für ein Objekt des Nutzungsberichts (Review-Beispiel)

{
  "results": [
    {
      "instance_identifier": "i-1237aa0e1587577f5",
      "max_cpu_utilization": "0.91925"
    },
    {
      "instance_identifier": "i-0007aa0e1587572c7",
      "max_cpu_utilization": "0.179183"
    }
  ],
  "meta": {
    "dates": {
      "start": "2022-08-30T00:00:00Z",
      "end": "2022-08-30T00:00:00Z"
    },
    "filters": [],
    "metrics": [
      {
        "name": "max_cpu_utilization",
        "label": "CPU Utilization (Max)",
        "description": "The maximum percentage of CPU Utilization...
        "data_type": "percentage",
        "type": "metric",
        "group": {
          "ID": 9,
          "Key": "compute",
          "Name": "Compute"
        },
        "sub_group": {
          "ID": 12,
          "Key": "processing",
          "Name": "Processing"
        }
      }
    ],
    "dimensions": [
      {
        "name": "instance_identifier",
        "label": "Instance ID",
        "description": "The ID associated with a particular AWS instance.",
        "data_type": "string",
        "type": "dimension",
        "group": {
          "ID": 9,
          "Key": "compute",
          "Name": "Compute"
        },
        "sub_group": {
          "ID": 1,
          "Key": "common",
          "Name": "Common"
        }
      }
    ],
    "aggregates": [
      {
        "name": "max_cpu_utilization",
        "label": "CPU Utilization (Max)",
        "description": "The maximum percentage of CPU Utilization...",
        "data_type": "percentage",
        "type": "metric",
        "value": "0.91925"
      }
    ]
  },
  "offset": 0,
  "limit": 2,
  "total_results": 2
}

Liste aktueller Verwendungsnachweise

Abrufen einer Liste von Nutzungsberichten, die entweder dem Benutzer oder der Organisation gehören oder für sie freigegeben sind.

curl 'https://api.cloudability.com/v3/reporting/reports/util' -u '[auth_token]:'

Beispiel Antwort

[
 {
  "id": 1,
  "author": {
  "id": 12345,
  "safe_name": "Test User"
  },
  "category": "Utilization",
  "custom": true,
  "description": "The number of instances running during each hour of the day over the last 7 days.",
  "dimensions": [
  {
  "name": "date",
  "label": "Date",
  "description": "The calendar date (e.g. YYYY-MM-DD).",
  "data_type": "date",
  "type": "dimension",
  "group": {
  "id": 9,
  "key": "compute",
  "name": "Compute"
  },
  "sub_group": {
  "id": 2,
  "key": "time",
  "name": "Time"
  }
   },
  {
  "name": "hour",
  "label": "Hour",
  "description": "The numeric hour of the day (e.g. 1pm => 13).",
  "data_type": "integer",
  "type": "dimension",
  "group": {
  "id": 9,
  "key": "compute",
  "name": "Compute"
  },
  "sub_group": {
  "id": 2,
  "key": "time",
  "name": "Time"
  }
   }
  ],
 "end_date": "23:59:59",
 "filters": [
 {
  "comparator": "==",
  "measure": {
  "name": "date",
  "label": "Date",
  "description": "The calendar date (e.g. YYYY-MM-DD).",
  "data_type": "date",
  "type": "dimension",
  "group": {
  "id": 9,
  "key": "compute",
  "name": "Compute"
  },
  "sub_group": {
  "id": 2,
  "key": "time",
  "name": "Time"
  }
   },
  "value": "2019-06-24"
  }
   ],
  "metrics": [
 {
  "name": "running_instances",
  "label": "Unique Instance Count",
  "description": "The total number of unique instances in a running state during a given time period.",
  "data_type": "integer",
  "type": "metric",
  "group": {
  "id": 9,
  "key": "compute",
  "name": "Compute"
  },
  "sub_group": {
  "id": 8,
  "key": "usage",
  "name": "Usage"
  }
   }
    ],
  "order": "asc",
  "owned_by_user": false,
  "shared_with_organization": false,
  "permission": {
  "actions": [
  "read"
  ]
   },
 "report_dimension_links": [],
 "secondary_end_date": null,
 "secondary_start_date": null,
 "shared": true,
 "shares": [],
 "sort_by": "date",
 "star": false,
 "start_date": "7 days ago at 00:00:00",
 "subscriptions": [],
 "title": "Elasticity - Running Instances per Hour"
  },
    ]

Liste der verfügbaren Maßnahmen abrufen

Ruft eine Liste der vom Server erkannten Maßnahmen ab. Measures umfasst sowohl Dimensionen als auch Metriken, die in Berichten verwendet werden können. Führen Sie einfach einen GET auf den Endpunkt der Maßnahmen durch.

curl ‘https://api.cloudability.com/v3/reporting/util/measures’ -u ‘[auth_token]:’

Beispiel Antwort

[
  {
    "name": "avg_cpu_utilization",
    "label": "CPU Utilization (Avg)",
    "description": "The average percentage of CPU Utilization...",
    "type": "metric",
    "group": {
      "id": 9,
      "key": "compute",
      "name": "Compute"
    },
    "sub_group": {
      "id": 12,
      "key": "processing",
      "name": "Processing"
    }
  },
  {
    "name": "utilization_hours",
    "label": "Utilization Hours",
    "description": "The total number of usage hours on an instance ...",
    "data_type": "integer",
    "type": "metric",
    "group": {
      "id": 9,
      "key": "compute",
      "name": "Compute"
    },
    "sub_group": {
      "id": 8,
      "key": "usage",
      "name": "Usage"
    }
  },
]

Liste der verfügbaren Filteroperatoren abrufen

Abrufen einer Liste von erkannten Filteroperatoren für die Datenabfrage

curl ‘https://api.cloudability.com/v3/reporting/util/filters’ -u ‘[auth_token]:’

Beispiel Antwort

[
  "<=",   # less than or equals
  "[]=",  # in*
  ">="    # greater than or equals
  "<",    # less than
  "=@",   # contains
  "^=",   # matches
  "===",  # strictly equals*
  "==",   # equals
  "!=@",  # does not contain
  "!=",   # not equals
  "!==",  # strictly not equals*
  ">",    # greater than
  "!^=",  # does not match
  "!$=",  #does not end with
  "[]!=", # not in*
  "$=",   #end with
]	

* Beachten Sie, dass diese Operatoren nur über die API verfügbar sind

Ausführen eines Nutzungsberichts

Anfrage-Parameter

Hinweis: Relative/dynamische Datumszeichenfolgen werden vom Endpunkt v3 cost reporting unterstützt:

Handhabung der Paginierung

Zur Unterstützung der API-Leistung wird eine Paginierung implementiert, wenn die Anzahl der Zeilen in einem zurückgegebenen Bericht 10.000 übersteigt. Dies tritt in der Regel auf, wenn Benutzer mehrere Dimensionen zu einem Bericht hinzufügen, die eine hohe Kardinalität aufweisen, wie z. B. resource_identifier. Der Wert von total_results von 10.000 und das Vorhandensein eines Paginierungsobjekts zeigen an, dass eine Paginierung stattgefunden hat.

Beispiel für ein Paginierungsobjekt:

"pagination": {
  "next": "38bc18d0",
  "previous": "1d93c71e"

Um zwischen den Seiten eines Berichts vorwärts und rückwärts zu navigieren, fügen Sie einen Token-Abfrageparameter am Ende des Berichts URL mit dem entsprechenden Token-Wert hinzu (z. B. token=38bc18d0 ).

Hinweis : Sie können die automatische Weiterleitung auf 64.000 Zeilen erhöhen, indem Sie limit=0 in den Abfrageparametern einstellen

Führen Sie einen typischen Nutzungsbericht aus - langfristige Nutzungstrends

curl ‘https://api.cloudability.com/v3/reporting/util/run?start_date=2022-01-01&end_date=2022-06-30&dimensions=date&metrics=total_bandwidth,avg_cpu_utilization&sort=dateASC&view_id=0’ -u ‘[auth_token]:’"

Beispielhafte Antwort (Teilmenge der angezeigten Ergebnisse)

{
  "results": [
    {
      "avg_cpu_utilization": "0.84463",
      "estimated_cost": "393.12",
      "instance_identifier": "i-0a70f28b01f652f14",
      "instance_name": "common-operations-ondemand-r5-large-green-Node",
      "instance_size": "r5.large",
      "total_bandwidth": "2019199735862",
      "utilization_hours": "24",
      "vendor_account_name": "My Account Name"
    },
    {
      "avg_cpu_utilization": "0.830585",
      "estimated_cost": "1071.2",
      "instance_identifier": "i-0278b62c3679c7286",
      "instance_name": "production-operations-spot-16cpu-64gb-green-Node",
      "instance_size": "m5ad.4xlarge",
      "total_bandwidth": "864959230667",
      "utilization_hours": "9",
      "vendor_account_name": "My Account Name"
    }
  ],
  "meta": {
    "dates": {
      "start": "2022-08-30T00:00:00Z",
      "end": "2022-08-30T00:00:00Z"
    },
    "filters": [],
    "metrics": [
      {
        "name": "avg_cpu_utilization",
        "label": "CPU Utilization (Avg)",
        "description": "The average percentage of CPU Utilization...",
        "data_type": "percentage",
        "type": "metric",
        "group": {
          "ID": 9,
          "Key": "compute",
          "Name": "Compute"
        },
        "sub_group": {
          "ID": 12,
          "Key": "processing",
          "Name": "Processing"
        }
      }
    ],
    "dimensions": [
      {
        "name": "instance_identifier",
        "label": "Instance ID",
        "description": "The ID associated with a particular AWS instance.",
        "data_type": "string",
        "type": "dimension",
        "group": {
          "ID": 9,
          "Key": "compute",
          "Name": "Compute"
        },
        "sub_group": {
          "ID": 1,
          "Key": "common",
          "Name": "Common"
        }
      }
    ],
    "aggregates": [
      {
        "name": "avg_cpu_utilization",
        "label": "CPU Utilization (Avg)",
        "description": "The average percentage of CPU Utilization. For EC2, this is the average percentage of allocated EC2 compute units in use for an instance.",
        "data_type": "percentage",
        "type": "metric",
        "value": "0.840516"
      }
    ]
  },
  "offset": 0,
  "pagination": {
    "next": "02f296f8"
  },
  "limit": 2,
  "total_results": 2
}

Erstellen Sie einen Bericht über die Nutzungsdaten und rufen Sie die Ergebnisse später ab

Diese Option eignet sich hervorragend für Berichte, deren Erstellung länger dauert (wegen hoher Kardinalität oder Zeitspanne), indem die Berichterstellung ausgelöst wird und die Ergebnisse später abgerufen werden. Der Endpunkt des asynchronen Berichtsflusses nimmt die gleichen Parameter wie der synchrone Nutzungsbericht, aber anstatt zu warten und den Inhalt des Berichts zurückzugeben, wird stattdessen ein Anfrage-Token zurückgegeben. Der aktuelle Stand der Verarbeitung wird durch Abfrage der Zustandsressource für das angegebene Token abgefragt. Wenn der Status als "fertig" angegeben wird, kann der Inhalt des Berichts abgerufen werden, indem die Ergebnisressource für das Token angefordert wird. Ein Beispiel für den vollständigen Datenfluss folgt der Beschreibung der Ergebnisressource.

curl ‘https://api.cloudability.com/v3/reporting/util/enqueue?start_date=2022-01-01&end_date=2022-06-30&dimensions=date&metrics=total_bandwidth,avg_cpu_utilization&sort=dateASC&view_id=0’ -u ‘[auth_token]:’

curl ‘https://api.cloudability.com/v3/reporting/util/enqueue?start_date=2022-01-01&end_date=2022-06-30&dimensions=date&metrics=total_bandwidth,avg_cpu_utilization&sort=dateASC&view_id=0&useDimensionNames=true' -u ‘[auth_token]:’

Beispiel Antwort

{"id":31272850}

Abfrage des Status eines asynchronen Berichts

Gültige Zustände eines asynchronen Berichts sind: in der Warteschlange, in Bearbeitung, fehlerhaft und beendet. Der Status kann mit folgendem API-Aufruf abgefragt werden (ersetzen Sie :id durch Ihre Berichts-ID, wie sie vom Enqueue-Aufruf zurückgegeben wird)

curl https://api.cloudability.com/v3/reporting/reports/:id/state -u ‘[auth_token]:’

Beispiel Antwort

{"status":"running"}

Abrufen eines zuvor von Enqueue erstellten Berichts

Berichte, die den Status "fertig" haben, können abgerufen werden. Dies gibt ein Standardauslastungsberichtsobjekt zurück

curl ‘https://api.cloudability.com/v3/reporting/reports/:id/results’-u ‘[auth_token]:’]"

Wichtiger Hinweis zur Paginierung: Bei Berichten in der Warteschlange wird die Paginierung auf ähnliche Weise wie bei synchronen Nutzungsberichten durchgeführt. Der einzige Unterschied besteht darin, dass die Größe der Seiten 30.000 statt 10.000 Zeilen beträgt. Das bedeutet, dass Berichte in der Warteschlange erst dann paginiert werden, wenn die Zeilenzahl 30.000 Zeilen überschreitet.

Liste der Musterberichte

Im Folgenden finden Sie einige Beispielberichte, die Ihnen bei der Verwendung der API für Nutzungsberichte helfen können.

Auslastungsbericht mit relativen Daten

curl ‘https://api.cloudability.com/v3/reporting/util/run?start_date=0+of+last+month&end_date=end+of+last+month&dimensions=date&metrics=total_bandwidth,avg_cpu_utilization&sort=dateASC&view_id=0’ -u ‘[auth_token]:’

Trends zur Nutzung von Instanztypen, zurückgegeben über „ CSV “

 curl -H ‘Accept: text/csv’ ‘https://api.cloudability.com/v3/reporting/util/run?start_date=2022-02-01&end_date=2022-02-28&dimensions=instance_size&metrics=utilization_hours,running_instances&sort=utilization_hoursDESC’ -u ‘[auth_token]:’

Nicht ausgelastete rechenoptimierte Instanzen (Bericht mit mehreren Dimensionen und Filtern)

curl 'https://api.cloudability.com/v3/reporting/util/run?start_date=2022-02-01&end_date=2022-02-28&dimensions=instance_size&metrics=utilization_hours%2Crunning_instances&sort=utilization_hoursDESC' -u '[auth_token]:'

Typischer Nutzungsbericht (Bericht über die Tage seit dem Start)

curl ‘https://api.cloudability.com/v3/reporting/util/run?dimensions=launch_date&end_date=2022-08-30&filters=product_name%3D%3DAmazon%20Elastic%20Compute%20Cloud&limit=2&metrics=avg_cpu_utilization&relativePeriods=custom&sort=launch_dateDESC&start_date=2022-08-22&viewId=0’ -u ‘[auth_token]:’