Eine Vorlage verwenden Eine benutzerdefinierte Datenquelle von Grund auf erstellen

Einen Konnektor zu einer Datenquelle erstellen

In diesem Thema wird beschrieben, wie eine benutzerdefinierte Datenquelle mit CloudWatch verbunden wird. Sie haben zwei Möglichkeiten, eine benutzerdefinierte Datenquelle mit CloudWatch zu verbinden:

Verwenden Sie eine Beispielvorlage, die CloudWatch bereitstellt. Sie können mit dieser Vorlage entweder JavaScript oder Python verwenden. Diese Vorlagen enthalten Lambda-Beispielcode, der Ihnen bei der Erstellung Ihrer Lambda-Funktion nützlich sein wird. Anschließend können Sie die Lambda-Funktion aus der Vorlage ändern, um eine Verbindung zu Ihrer benutzerdefinierten Datenquelle herzustellen.
Erstellen Sie eine AWS Lambda-Funktion von Grund auf, die den Datenquellen-Konnektor, die Datenabfrage und die Vorbereitung der Zeitreihen für die Verwendung durch CloudWatch implementiert. Diese Funktion muss Datenpunkte bei Bedarf vorab aggregieren oder zusammenführen und auch den Zeitraum und die Zeitstempel so anpassen, dass sie mit CloudWatch kompatibel sind.

Inhalt

Eine Vorlage verwenden

Durch die Verwendung einer Vorlage wird eine Lambda-Beispielfunktion erstellt, mit der Sie Ihren benutzerdefinierten Konnektor schneller erstellen können. Diese Beispielfunktionen enthalten Beispielcode für viele gängige Szenarien beim Erstellen eines benutzerdefinierten Konnektors. Sie können den Lambda-Code untersuchen, nachdem Sie einen Konnektor mit einer Vorlage erstellt haben, und ihn dann so ändern, dass er für die Verbindung mit Ihrer Datenquelle verwendet wird.

Wenn Sie die Vorlage verwenden, kümmert sich CloudWatch außerdem um die Erstellung der Lambda-Berechtigungsrichtlinie und das Anhängen von Ressourcen-Tags an die Lambda-Funktion.

So verwenden Sie die Vorlage, um einen Konnektor für eine benutzerdefinierte Datenquelle zu erstellen

Öffnen Sie die CloudWatch-Konsole unter https://console.aws.amazon.com/cloudwatch/.
Wählen Sie im Navigationsbereich Settings (Einstellungen).
Wählen Sie die Registerkarte Metrik-Datenquellen.
Klicken Sie auf Create data source.
Wählen Sie das Optionsfeld für Benutzerdefiniert – Vorlage für die ersten Schritte aus und dann Weiter.
Geben Sie einen Namen für die Datenquelle ein.
Wählen Sie eine der aufgelisteten Vorlagen aus.
Wählen Sie entweder Node.js oder Python aus.
Klicken Sie auf Create data source.

Die neue benutzerdefinierte Quelle, die Sie gerade hinzugefügt haben, wird erst angezeigt, wenn der CloudFormation-Stack ihre Erstellung abgeschlossen hat. Um den Fortschritt zu überprüfen, können Sie Den Status meines CloudFormation-Stacks anzeigen wählen. Oder Sie können das Aktualisierungssymbol wählen, um diese Liste zu aktualisieren.

Wenn Ihre neue Datenquelle in dieser Liste angezeigt wird, können Sie sie in der Konsole testen und ändern.
(Optional) Um die Testdaten aus dieser Quelle in der Konsole abzufragen, folgen Sie den Anweisungen in Erstellen eines Diagramms mit Metriken aus einer anderen Datenquelle.
Passen Sie die Lambda-Funktion an Ihre Bedürfnisse an.
1. Wählen Sie im Navigationsbereich Settings (Einstellungen).
2. Wählen Sie die Registerkarte Metrik-Datenquellen.
3. Wählen Sie In Lambda-Konsole anzeigen für die Quelle aus, die Sie ändern möchten.
Sie können die Funktion jetzt ändern, um auf Ihre Datenquelle zuzugreifen. Weitere Informationen finden Sie unter Schritt 1: Die Funktion erstellen.

Anmerkung
Wenn Sie die Vorlage verwenden, müssen Sie beim Schreiben Ihrer Lambda-Funktion nicht den Anweisungen in Schritt 2: Eine Lambda-Berechtigungsrichtlinie erstellen oder Schritt 3: Ein Ressourcen-Tag an die Lambda-Funktion anfügen folgen. Diese Schritte wurden von CloudWatch ausgeführt, weil Sie die Vorlage verwendet haben.

Eine benutzerdefinierte Datenquelle von Grund auf erstellen

Führen Sie die Schritte in diesem Abschnitt aus, um eine Lambda-Funktion zu erstellen, die CloudWatch mit einer Datenquelle verbindet.

Schritt 1: Die Funktion erstellen

Ein benutzerdefinierter Datenquellen-Konnektor muss GetMetricData-Ereignisse von CloudWatch unterstützen. Optional können Sie auch ein DescribeGetMetricData-Ereignis implementieren, um Benutzern in der CloudWatch-Konsole Dokumentation zur Verwendung des Konnektors zur Verfügung zu stellen. Die DescribeGetMetricData-Antwort kann auch verwendet werden, um Standardwerte festzulegen, die im benutzerdefinierten CloudWatch-Abfragegenerator verwendet werden.

CloudWatch stellt Codeausschnitte als Beispiele bereit, die Ihnen bei den ersten Schritten helfen. Weitere Informationen finden Sie im Beispiele-Repository unter https://github.com/aws-samples/cloudwatch-data-source-samples.

Beschränkungen

Die Antwort von Lambda muss kleiner als 6 MB sein. Wenn die Antwort 6 MB überschreitet, markiert die GetMetricData-Antwort die Lambda-Funktion als InternalError und es werden keine Daten zurückgegeben.
Die Lambda-Funktion muss die Ausführung innerhalb von 10 Sekunden für Visualisierungs- und Dashboardingzwecke oder innerhalb von 4,5 Sekunden für die Verwendung von Alarmen abschließen. Wenn die Ausführungszeit diesen Wert überschreitet, markiert die GetMetricData-Antwort die Lambda-Funktion als InternalError und es werden keine Daten zurückgegeben.
Die Lambda-Funktion muss ihre Ausgabe mit Epochen-Zeitstempeln in Sekunden senden.
Wenn die Lambda-Funktion die Daten nicht neu berechnet und stattdessen Daten zurückgibt, die nicht der vom CloudWatch-Benutzer angeforderten Startzeit und Periodenlänge entsprechen, werden diese Daten von CloudWatch ignoriert. Die zusätzlichen Daten werden bei allen Visualisierungen oder Alarmen verworfen. Alle Daten, die nicht zwischen der Startzeit und der Endzeit liegen, werden ebenfalls verworfen.

Wenn ein Benutzer beispielsweise nach Daten von 10:00 bis 11:00 Uhr mit einem Zeitraum von 5 Minuten fragt, dann sind „10:00:00 bis 10:04:59“ und „10:05:00 bis 10:09:59“ die gültigen Zeitbereiche für die Rückgabe von Daten. Sie müssen eine Zeitreihe zurückgeben, die 10:00 value1, 10:05 value2 usw. enthält. Wenn die Funktion beispielsweise 10:03 valueX zurückgibt, wird sie verworfen, weil 10:03 nicht der angeforderten Startzeit und dem angeforderten Startzeitraum entspricht.
Mehrzeilige Abfragen werden von den CloudWatch-Datenquellen-Konnektoren nicht unterstützt. Jeder Zeilenvorschub wird durch ein Leerzeichen ersetzt, wenn die Abfrage ausgeführt wird oder wenn Sie mit der Abfrage einen Alarm oder ein Dashboard-Widget erstellen. In einigen Fällen kann dies dazu führen, dass Ihre Abfrage ungültig ist.

GetMetricData-Ereignis

Anforderungs-Nutzlast

Im Folgenden sehen Sie ein Beispiel für eine GetMetricData-Anforderungs-Nutzlast, die als Eingabe an die Lambda-Funktion gesendet wird.


{
  "EventType": "GetMetricData",
  "GetMetricDataRequest": {
    "StartTime": 1697060700,
    "EndTime": 1697061600,
    "Period": 300,
    "Arguments": ["serviceregistry_external_http_requests{host_cluster!=\"prod\"}"] 
  }
}

StartTime – Der Zeitstempel, der die frühesten zurückzugebenden Daten angibt. Der Typ ist Zeitstempel, Epoche, Sekunden.
EndTime – Der Zeitstempel, der die letzten zurückzugebenden Daten angibt. Der Typ ist Zeitstempel, Epoche, Sekunden.
Zeitraum – Die Anzahl der Sekunden, die jede Aggregation der Metrikdaten darstellt. Der Mindestwert beträgt 60 Sekunden. Der Typ ist Sekunden.
Argumente – Ein Array von Argumenten, die an den mathematischen Ausdruck der Lambda-Metrik übergeben werden. Informationen zur Übergabe von Argumenten finden Sie unter So übergeben Sie Argumente an Ihre Lambda-Funktion.

Antwort-Nutzlast

Nachfolgend sehen Sie ein Beispiel für eine von der Lambda-Funktion zurückgegebenen GetMetricData-Antwort-Nutzlast.


{
   "MetricDataResults": [
      {
         "StatusCode": "Complete",
         "Label": "CPUUtilization",
         "Timestamps": [ 1697060700, 1697061000, 1697061300 ],
         "Values": [ 15000, 14000, 16000 ]
      }
   ]
}

Die Antwort-Nutzlast enthält entweder ein MetricDataResults-Feld oder ein Error-Feld, aber nicht beides.

Ein MetricDataResults-Feld ist eine Liste von Zeitreihenfeldern des Typs MetricDataResult. Jedes dieser Zeitreihenfelder kann die folgenden Felder enthalten.

StatusCode – (Optional) Complete gibt an, dass alle Datenpunkte im angeforderten Zeitraum zurückgegeben wurden. PartialData bedeutet, dass ein unvollständiger Satz von Datenpunkten zurückgegeben wurde. Wenn dieses Argument weggelassen wird, ist der Standardwert Complete.

Zulässige Werte: Complete | InternalError | PartialData | Forbidden
Nachrichten – Optionale Liste von Nachrichten mit zusätzlichen Informationen zu den zurückgegebenen Daten.

Typ: Array von MessageData-Objekten mit Code- und Value-Zeichenfolgen.
Label – Das für Menschen lesbare Etikett, das den Daten zugeordnet ist.

Typ: Zeichenfolge
Zeitstempel – Die Zeitstempel für die Datenpunkte, formatiert in Epochenzeit. Die Anzahl der Zeitstempel entspricht immer der Anzahl der Werte und der Wert für Timestamps[x] ist Values[x].

Typ: Array von Zeitstempeln
Werte – Die Datenpunktwerte für die Metrik, entsprechend der Timestamps. Die Anzahl der Werte entspricht immer der Anzahl der Zeitstempel und der Wert für Timestamps[x] ist Values[x].

Typ: Array von Dubletten

Weitere Informationen über Error-Objekte finden Sie in den folgenden Abschnitten.

Formate für die Fehlerantwort

Sie können optional die Fehlerantwort verwenden, um weitere Informationen zu Fehlern bereitzustellen. Wir empfehlen, dass Sie mit der Codevalidierung einen Fehler zurückgeben, wenn ein Validierungsfehler auftritt, z. B. wenn ein Parameter fehlt oder vom falschen Typ ist.

Im Folgenden finden Sie ein Beispiel für die Reaktion, wenn die Lambda-Funktion eine GetMetricData-Validierungsausnahme auslösen möchte.


{
   "Error": {
      "Code": "Validation",
      "Value": "Invalid Prometheus cluster"
   }
}

Das Folgende ist ein Beispiel für die Reaktion, wenn die Lambda-Funktion angibt, dass sie aufgrund eines Zugriffsproblems keine Daten zurückgeben kann. Die Antwort wird in eine einzige Zeitreihe mit dem Statuscode Forbidden übersetzt.


{
   "Error": {
      "Code": "Forbidden",
      "Value": "Unable to access ..."
   }
}

Das Folgende ist ein Beispiel dafür, wann die Lambda-Funktion eine allgemeine InternalError-Ausnahme auslöst, die in eine einzige Zeitreihe mit dem Statuscode InternalError und einer Nachricht übersetzt wird. Immer wenn ein Fehlercode einen anderen Wert als Validation oder Forbidden hat, geht CloudWatch davon aus, dass es sich um einen generischen internen Fehler handelt.


{
   "Error": {
      "Code": "PrometheusClusterUnreachable",
      "Value": "Unable to communicate with the cluster"
   }
}

DescribeGetMetricData-Ereignis

Anforderungs-Nutzlast

Es folgt ein Beispiel für eine DescribeGetMetricData-Anforderungs-Nutzlast.


{
  "EventType": "DescribeGetMetricData"
}

Antwort-Nutzlast

Es folgt ein Beispiel für eine DescribeGetMetricData-Antwort-Nutzlast.


{
    "Description": "Data source connector",
    "ArgumentDefaults": [{
        Value: "default value"
     }]
}

Beschreibung – Eine Beschreibung der Verwendung des Datenquellen-Konnektors. Diese Beschreibung wird in der CloudWatch-Konsole angezeigt. Markdown wird unterstützt.

Typ: Zeichenfolge
ArgumentDefaults – Optionales Array von Standardwerten für Argumente, die verwendet werden, um den benutzerdefinierten Datenquellen-Generator vorab auszufüllen.

Wenn [{ Value: "default value 1"}, { Value: 10}] zurückgegeben wird, zeigt der Abfragegenerator in der CloudWatch-Konsole zwei Eingaben an, die erste mit „Standardwert 1“ und die zweite mit 10.

Wenn ArgumentDefaults nicht angegeben wird, wird eine einzelne Eingabe angezeigt, wobei der Standardtyp auf String gesetzt ist.

Typ: Array von Objekten, die Wert und Typ enthalten.
Fehler – (Optional) In jeder Antwort kann ein Fehlerfeld enthalten sein. Beispiele finden Sie unter GetMetricData-Ereignis.

Wichtige Überlegungen zu CloudWatch-Alarmen

Wenn Sie die Datenquelle zum Einrichten von CloudWatch-Alarmen verwenden möchten, sollten Sie sie so einrichten, dass jede Minute Daten mit Zeitstempeln an CloudWatch gemeldet werden. Weitere Informationen und weitere Überlegungen zur Erstellung von Alarmen für Metriken aus verbundenen Datenquellen finden Sie unter Einen Alarm basierend auf einer verbundenen Datenquelle erstellen.

(Optional) AWS Secrets Manager zum Speichern von Anmeldeinformationen verwenden

Wenn Ihre Lambda-Funktion Anmeldeinformationen für den Zugriff auf die Datenquelle verwenden muss, empfehlen wir, diese Anmeldeinformationen mit AWS Secrets Manager zu speichern, anstatt sie fest in Ihre Lambda-Funktion zu codieren. Weitere Informationen zur Verwendung von AWS Secrets Manager mit Lambda finden Sie unter Verwenden von AWS Secrets Manager-Geheimnissen in AWS Lambda-Funktionen.

(Optional) Mit einer Datenquelle in einer VPC verbinden

Wenn sich Ihre Datenquelle in einer von Amazon Virtual Private Cloud verwalteten VPC befindet, müssen Sie Ihre Lambda-Funktion für den Zugriff darauf konfigurieren. Weitere Informationen finden Sie unter Verbinden von ausgehenden Netzwerken mit Ressourcen in einer VPC.

Möglicherweise müssen Sie auch VPC-Service-Endpunkte für den Zugriff auf Services wie AWS Secrets Manager konfigurieren. Weitere Informationen finden Sie unter Zugriff auf einen AWS-Service über einen Schnittstellen-VPC-Endpunkt.

Schritt 2: Eine Lambda-Berechtigungsrichtlinie erstellen

Sie müssen eine Richtlinienanweisung erstellen, die CloudWatch die Erlaubnis erteilt, die von Ihnen erstellte Lambda-Funktion zu verwenden. Sie können die AWS CLI oder die Lambda-Konsole verwenden, um die Richtlinienerklärung zu erstellen.

So verwenden Sie die AWS CLI, um die Richtlinienerklärung zu erstellen

Geben Sie den folgenden Befehl ein. Ersetzen Sie 123456789012 durch Ihre Konto-ID, ersetzen Sie my-data-source-function durch den Namen Ihrer Lambda-Funktion und ersetzen Sie myDataSource-DataSourcePermission1234 durch einen beliebigen eindeutigen Wert.


aws lambda add-permission --function-name my-data-source-function --statement-id MyDataSource-DataSourcePermission1234 --action lambda:InvokeFunction --principal lambda.datasource.cloudwatch.amazonaws.com --source-account 123456789012

Schritt 3: Ein Ressourcen-Tag an die Lambda-Funktion anfügen

Die CloudWatch-Konsole bestimmt mithilfe eines Tags, welche Ihrer Lambda-Funktionen Datenquellen-Konnektoren sind. Wenn Sie mit einem der Assistenten eine Datenquelle erstellen, wird das Tag automatisch von dem CloudFormation-Stack angewendet, der es konfiguriert. Wenn Sie selbst eine Datenquelle erstellen, können Sie das folgende Tag für Ihre Lambda-Funktion verwenden. Dadurch wird Ihr Konnektor im Dropdown-Menü Datenquelle in der CloudWatch-Konsole angezeigt, wenn Sie Metriken abfragen.

Ein Tag mit cloudwatch:datasource als Schlüssel und custom als Wert.

Warnung JavaScript ist in Ihrem Browser nicht verfügbar oder deaktiviert.

Zur Nutzung der AWS-Dokumentation muss JavaScript aktiviert sein. Weitere Informationen finden auf den Hilfe-Seiten Ihres Browsers.

Dokumentkonventionen

Mit einem Assistenten eine Verbindung zu einer vordefinierten Datenquelle herstellen

Ihre benutzerdefinierte Datenquelle verwenden