CloudWatch-Protokollformate für API Gateway Berechtigungen für die CloudWatch-Protokollierung Einrichten der CloudWatch-API-Protokollierung über die API Gateway-Konsole CloudWatch-API-Protokollierung mit AWS CloudFormation einrichten

Einrichten der CloudWatch-Protokollierung für eine REST-API in API Gateway

Zur Behebung von Problemen im Zusammenhang mit der Anforderungsausführung oder dem Client-Zugriff auf Ihre API können Sie Amazon CloudWatch Logs aktivieren, um API-Aufrufe nachzuverfolgen. Weitere Informationen zu CloudWatch finden Sie unter Überwachung von REST-API-Ausführung mit Amazon CloudWatch-Metriken.

CloudWatch-Protokollformate für API Gateway

Es gibt zwei Arten der API-Protokollierung in CloudWatch: Ausführungsprotokollierung und Zugriffsprotokollierung. In der Ausführungsprotokollierung verwaltet API Gateway die CloudWatch Logs. Der Prozess umfasst das Erstellen von Protokollgruppen und -Streams sowie die Meldung der Anforderungen und Antworten jedes Aufrufers an Protokoll-Streams.

Die Protokolldaten umfassen Fehler oder Ablaufverfolgungen der Ausführung (z. B. Parameterwerte oder Nutzlasten von Anforderungen oder Antworten), von Lambda-Genehmigern (ehemals als benutzerdefinierte Genehmiger bezeichnet) verwendete Daten, Angaben darüber, ob API-Schlüssel erforderlich sind, Informationen dazu, ob Nutzungspläne aktiviert sind, und so weiter.

Wenn Sie eine API bereitstellen, erstellt API Gateway eine Protokollgruppe und -Streams unter der Protokollgruppe. Die Protokollgruppe wird nach dem API-Gateway-Execution-Logs_{rest-api-id}/{stage_name}-Format benannt. In jeder Protokollgruppe, werden die Protokolle weiter in Protokoll-Streams unterteilt, die bei Meldung von Protokolldaten nach Last Event Time sortiert werden.

In der Zugriffsprotokollierung protokollieren Sie, als API-Entwickler, wer auf Ihre API zugegriffen hat und wie der Aufrufer auf die API zugegriffen hat. Erstellen Sie eine eigene Protokollgruppe oder wählen Sie eine vorhandene Protokollgruppe aus, die von API Gateway verwaltet werden kann. Um die Zugriffsdetails anzugeben, wählen Sie $context-Variablen (ausgedrückt in einem Format Ihrer Wahl) und eine Protokollgruppe als Ziel aus. Das Zugriffsprotokoll-Format muss mindestens $context.requestId oder $context.extendedRequestId enthalten. Als Best Practice gehören $context.requestId und $context.extendedRequestId in Ihr Protokollformat. $context.requestId protokolliert den Wert im x-amzn-RequestId-Header. Clients können den Wert im x-amzn-RequestId-Header durch einen Wert im Format einer UUID (Universally Unique Identifier) überschreiben. API Gateway gibt diese Anforderungs-ID im x-amzn-RequestId-Antwort-Header zurück. API Gateway ersetzt überschriebene Anforderungs-IDs, die nicht im Format einer UUID vorliegen, in Ihren Zugriffsprotokollen durch UUID_REPLACED_INVALID_REQUEST_ID. $context.extendedRequestId ist eine eindeutige ID, die API Gateway generiert. API Gateway gibt diese Anforderungs-ID im x-amz-apigw-id-Antwort-Header zurück. Ein API-Aufrufer kann diese Anforderungs-ID nicht bereitstellen oder überschreiben. Weitere Informationen finden Sie unter $context Variablen für Datenmodelle, Genehmiger, Zuweisungsvorlagen und CloudWatch Zugriffsprotokollierung.

Anmerkung

Nur $context-Variablen werden unterstützt ($input usw. nicht).

Wählen Sie ein Protokollformat aus, das auch von Ihrem analytischen Backend genutzt wird, z. B. Common Log Format (CLF), JSON, XML, oder CSV. Anschließend können Sie die Zugriffsprotokolle direkt eingeben und Ihre Metriken berechnen und rendern lassen. Um das Protokollformat zu definieren, legen Sie den Protokollgruppen-ARN bei der accessLogSettings/destinationArn-Eigenschaft für die Stufe fest. Sie erhalten einen Protokollgruppen-ARN in der CloudWatch-Konsole, sofern die ARN-Spalte zur Anzeige ausgewählt ist. Wenn Sie das Zugriffsprotokollformat definieren möchten, legen Sie bei der accessLogSetting/format-Eigenschaft für die Stufe ein ausgewähltes Format fest.

Beispiele für einige häufig verwendete Zugriffsprotokollformate werden in der API Gateway-Konsole dargestellt und wie folgt aufgeführt.

CLF (Common Log Format):
```
$context.identity.sourceIp $context.identity.caller  \
$context.identity.user [$context.requestTime] \
"$context.httpMethod $context.resourcePath $context.protocol" \
$context.status $context.responseLength $context.requestId $context.extendedRequestId
```
Die Fortsetzungszeichen (\) sind als visuelle Hilfe gedacht. Das Protokollformat muss eine einzelne Zeile sein. Sie können am Ende des Protokollformats ein Zeilenumbruchzeichen (\n) hinzufügen, um am Ende jedes Protokolleintrags einen Zeilenumbruch einzuschließen.

JSON:


{ "requestId":"$context.requestId", \
  "extendedRequestId":"$context.extendedRequestId", \
  "ip": "$context.identity.sourceIp", \
  "caller":"$context.identity.caller", \
  "user":"$context.identity.user", \
  "requestTime":"$context.requestTime", \
  "httpMethod":"$context.httpMethod", \
  "resourcePath":"$context.resourcePath", \
  "status":"$context.status", \
  "protocol":"$context.protocol", \
  "responseLength":"$context.responseLength" \
}

Die Fortsetzungszeichen (\) sind als visuelle Hilfe gedacht. Das Protokollformat muss eine einzelne Zeile sein. Sie können am Ende des Protokollformats ein Zeilenumbruchzeichen (\n) hinzufügen, um am Ende jedes Protokolleintrags einen Zeilenumbruch einzuschließen.

XML:


<request id="$context.requestId"> \
    <extendedRequestId>$context.extendedRequestId</extendedRequestId>
    <ip>$context.identity.sourceIp</ip> \
    <caller>$context.identity.caller</caller> \
    <user>$context.identity.user</user> \
    <requestTime>$context.requestTime</requestTime> \
    <httpMethod>$context.httpMethod</httpMethod> \
    <resourcePath>$context.resourcePath</resourcePath> \
    <status>$context.status</status> \
    <protocol>$context.protocol</protocol> \
    <responseLength>$context.responseLength</responseLength> \
</request>

CSV (durch Komma getrennte Werte):
```
$context.identity.sourceIp,$context.identity.caller,\
$context.identity.user,$context.requestTime,$context.httpMethod,\
$context.resourcePath,$context.protocol,$context.status,\
$context.responseLength,$context.requestId,$context.extendedRequestId
```
Die Fortsetzungszeichen (\) sind als visuelle Hilfe gedacht. Das Protokollformat muss eine einzelne Zeile sein. Sie können am Ende des Protokollformats ein Zeilenumbruchzeichen (\n) hinzufügen, um am Ende jedes Protokolleintrags einen Zeilenumbruch einzuschließen.

Berechtigungen für die CloudWatch-Protokollierung

Um CloudWatch Logs zu aktivieren, müssen Sie die API Gateway-Berechtigung zum Lesen und Schreiben von Protokollen in CloudWatch für Ihr Konto erteilen. Die AmazonAPIGatewayPushToCloudWatchLogs verwaltete Richtlinie (mit dem ARN arn:aws:iam::aws:policy/service-role/AmazonAPIGatewayPushToCloudWatchLogs) verfügt über alle erforderlichen Berechtigungen:


{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Effect": "Allow",
            "Action": [
                "logs:CreateLogGroup",
                "logs:CreateLogStream",
                "logs:DescribeLogGroups",
                "logs:DescribeLogStreams",
                "logs:PutLogEvents",
                "logs:GetLogEvents",
                "logs:FilterLogEvents"
            ],
            "Resource": "*"
        }
    ]
}

Anmerkung

API Gateway ruft AWS Security Token Service auf, um die IAM-Rolle anzunehmen. Stellen Sie daher sicher, dass AWS STS für die Region aktiviert ist. Weitere Informationen finden Sie unter Verwalten von AWS STS in einer AWS-Region.

Um Ihrem Konto diese Berechtigungen zu gewähren, erstellen Sie zunächst eine IAM-Rolle mit apigateway.amazonaws.com als vertrauenswürdige Entität. Fügen Sie der IAM-Rolle dann die vorangegangene Richtlinie an und legen Sie den ARN der IAM-Rolle bei der cloudWatchRoleArn-Eigenschaft für Ihr Konto fest. Sie müssen die Eigenschaft cloudWatchRoleArn für jede AWS-Region, in der Sie CloudWatch Logs aktivieren möchten, separat festlegen.

Wenn Sie beim Festlegen des IAM-Rollen-ARN eine Fehlermeldung erhalten, überprüfen Sie Ihre AWS Security Token Service-Kontoeinstellungen, um sicherzustellen, dass AWS STS in der von Ihnen verwendeten Region aktiviert ist. Weitere Informationen zum Aktivieren von AWS STS finden Sie unter Verwalten von AWS STS in einer AWS-Region im IAM-Benutzerhandbuch.

Einrichten der CloudWatch-API-Protokollierung über die API Gateway-Konsole

Zum Einrichten der CloudWatch-API-Protokollierung müssen Sie die API für eine Stufe bereitgestellt haben. Sie müssen auch einen geeigneten CloudWatch Logs-Rollen-ARN für Ihr Konto konfiguriert haben.

Melden Sie sich bei der API Gateway-Konsole unter https://console.aws.amazon.com/apigateway an.
Wählen Sie im Hauptnavigationsbereich Settings (Einstellungen) und dann unter Logging (Protokollierung) die Option Edit (Bearbeiten) aus.
Geben Sie in CloudWatch log role ARN (CloudWatch-Protokollrollen) einen ARN für eine IAM-Rolle mit den entsprechenden Berechtigungen ein. Sie müssen dies einmal für jeden AWS-Konto tun, der APIs mithilfe von API Gateway erstellt.
Klicken Sie im Hauptnavigationsbereich auf APIs und führen Sie eine der folgenden Aktionen aus:
1. Wählen Sie eine vorhandene API und anschließend eine Stufe aus.
2. Erstellen Sie eine API und stellen Sie diese dann einer Stufe bereit.
Klicken Sie im Hauptnavigationsbereich auf Stages (Stufen).
Wählen Sie im Abschnitt Logs and tracing (Protokolle und Nachverfolgung) die Option Edit (Bearbeiten) aus.
So aktivieren Sie die Ausführungsprotokollierung:
1. Wählen Sie im Dropdown-Menü CloudWatch Logs (CloudWatch-Protokolle) eine Protokollierungsebene aus.
  
  Warnung
  Full Request and Response Logs (Vollständige Anforderungs- und Antwortprotokolle) kann zur Fehlerbehebung bei APIs hilfreich sein, kann aber dazu führen, dass sensible Daten protokolliert werden. Es wird empfohlen, Full Request and Response Logs (Vollständige Anforderungs- und Antwortprotokolle) nicht zu verwenden.
2. Falls gewünscht, wählen Sie Detailed metrics (Detaillierte Metriken) aus, um detaillierte CloudWatch-Metriken zu aktivieren.
Weitere Informationen zu CloudWatch-Metriken finden Sie unter Überwachung von REST-API-Ausführung mit Amazon CloudWatch-Metriken.
So aktivieren Sie die Zugriffsprotokollierung:
1. Aktivieren Sie die Option Custom access logging (Benutzerdefinierte Zugriffsprotokollierung).
2. Geben Sie den ARN einer Protokollgruppe in Access Log Destination ARN (Ziel-ARN des Zugriffsprotokolls) ein. Das ARN-Format ist arn:aws:logs:{region}:{account-id}:log-group:log-group-name.
3. Geben Sie unter Log Format (Protokollformat) ein Protokollformat ein. Sie können zwischen CLF, JSON, XML oder CSV wählen. Weitere Informationen zu Beispielprotokollformaten finden Sie unter CloudWatch-Protokollformate für API Gateway.
Wählen Sie Änderungen speichern.

Anmerkung

Sie können die Ausführungs- und Zugriffsprotokollierung unabhängig voneinander aktivieren.

API Gateway kann nun Anforderungen an Ihre API protokollieren. Sie müssen die API nicht erneut bereitstellen, wenn Sie die Stufeneinstellungen, Protokolle oder Stufenvariablen aktualisieren.

CloudWatch-API-Protokollierung mit AWS CloudFormation einrichten

Verwenden Sie die folgende AWS CloudFormation-Beispielvorlage, um eine Amazon-CloudWatch-Logs-Protokollgruppe zu erstellen und die Ausführungs- und Zugriffsprotokollierung für eine Stufe zu konfigurieren. Um CloudWatch Logs zu aktivieren, müssen Sie die API Gateway-Berechtigung zum Lesen und Schreiben von Protokollen in CloudWatch für Ihr Konto erteilen. Weitere Informationen finden Sie unter Konto mit IAM-Rolle verknüpfen im AWS CloudFormation-Benutzerhandbuch.


  TestStage:
    Type: AWS::ApiGateway::Stage
    Properties:
      StageName: test
      RestApiId: !Ref MyAPI
      DeploymentId: !Ref Deployment
      Description: "test stage description"
      MethodSettings:
        - ResourcePath: "/*"
          HttpMethod: "*"
          LoggingLevel: INFO
      AccessLogSetting:
        DestinationArn: !GetAtt MyLogGroup.Arn
        Format: $context.extendedRequestId $context.identity.sourceIp $context.identity.caller $context.identity.user [$context.requestTime] "$context.httpMethod $context.resourcePath $context.protocol" $context.status $context.responseLength $context.requestId
  MyLogGroup:
    Type: AWS::Logs::LogGroup
    Properties:
      LogGroupName: !Join
        - '-'
        - - !Ref MyAPI
          - access-logs

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

Überwachungstools in AWS

Firehose