Richten Sie die CloudWatch Protokollierung für REST-APIs in API Gateway ein

Um Probleme im Zusammenhang mit der Ausführung von Anfragen oder dem Client-Zugriff auf Ihre API zu beheben, können Sie Amazon CloudWatch Logs zur Protokollierung von API-Aufrufen aktivieren. Weitere Informationen zu finden Sie CloudWatch unterÜberwachen Sie REST API die Ausführung mit CloudWatch Amazon-Metriken.

CloudWatch Protokollformate für API Gateway

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

Zu den protokollierten Daten gehören Fehler oder Ausführungsspuren (wie Anforderungs- oder Antwortparameterwerte oder Payloads), von Lambda-Autorisierern (früher bekannt als benutzerdefinierte Autorisierer) verwendete Daten, ob API-Schlüssel erforderlich sind, ob Nutzungspläne aktiviert sind und andere Informationen. API Gateway redigiert Autorisierungsheader, API-Schlüsselwerte und ähnliche sensible Anforderungsparameter aus den protokollierten Daten.

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 $contextVariablen, ein Protokollformat und ein Protokollgruppenziel aus.

Das Zugriffsprotokoll-Format muss mindestens $context.requestId oder $context.extendedRequestId enthalten. Es hat sich bewährt, $context.requestId und $context.extendedRequestId in Ihr Protokollformat aufzunehmen.

$context.requestId

Dadurch wird der Wert in der x-amzn-RequestId Kopfzeile protokolliert. 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 das Format einer UUID haben, durch UUID_REPLACED_INVALID_REQUEST_ID in Ihren Zugriffsprotokollen.

$context.extendedRequestId

Die 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. Möglicherweise müssen Sie diesen Wert dem AWS Support zur Verfügung stellen, um die Fehlerbehebung für Ihre API zu unterstützen. Weitere Informationen finden Sie unter $contextVariablen für Datenmodelle, Autorisierer, Zuordnungsvorlagen und CloudWatch Zugriffsprotokollierung.

Anmerkung

Es werden nur $context Variablen unterstützt.

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 ARN der Protokollgruppe in der Eigenschaft accessLogSettings/DestinationArn auf der Bühne fest. Sie können einen Protokollgruppen-ARN in der CloudWatch Konsole abrufen. Um das Format des Zugriffsprotokolls zu definieren, legen Sie in der Eigenschaft accessLogSetting/format auf der Bühne 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

• 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" }

• 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

Berechtigungen für die Protokollierung CloudWatch

Um CloudWatch Logs zu aktivieren, müssen Sie API Gateway die Erlaubnis erteilen, Logs CloudWatch für Ihr Konto zu lesen und zu schreiben. 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 zu übernehmen. Stellen Sie also sicher, dass diese für die Region aktiviert AWS STS ist. Weitere Informationen finden Sie unter AWS STS in einer AWS Region verwalten.

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

Wenn Sie beim Einstellen des ARN für die IAM-Rolle eine Fehlermeldung erhalten, überprüfen Sie Ihre AWS Security Token Service Kontoeinstellungen, um sicherzustellen, dass diese in der Region, die Sie verwenden, aktiviert AWS STS ist. Weitere Informationen zur Aktivierung AWS STS finden Sie im IAM-Benutzerhandbuch unter AWS STS in einer AWS Region verwalten.

CloudWatch API-Protokollierung mit der API Gateway Gateway-Konsole einrichten

Um die CloudWatch API-Protokollierung einzurichten, müssen Sie die API in einer Phase bereitgestellt haben. Sie müssen auch einen entsprechenden CloudWatch Logs-Rollen-ARN für Ihr Konto konfiguriert haben.

1. Melden Sie sich bei der API-Gateway-Konsole unter https://console.aws.amazon.com/apigateway an.

2. Wählen Sie im Hauptnavigationsbereich Settings (Einstellungen) und dann unter Logging (Protokollierung) die Option Edit (Bearbeiten) aus.

3. Geben Sie für die CloudWatch Protokollrolle ARN einen ARN einer IAM-Rolle mit den entsprechenden Berechtigungen ein. Sie müssen dies einmal für jeden tun AWS-Konto , der APIs mithilfe von API Gateway erstellt.

4. 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.

5. Klicken Sie im Hauptnavigationsbereich auf Stages (Stufen).

6. Wählen Sie im Abschnitt Logs and tracing (Protokolle und Nachverfolgung) die Option Edit (Bearbeiten) aus.

7. So aktivieren Sie die Ausführungsprotokollierung:

   1. Wählen Sie im Dropdownmenü Protokolle eine CloudWatch Protokollierungsebene aus. Die Protokollierungsebenen sind die folgenden:

      • Aus — Die Protokollierung ist für diese Phase nicht aktiviert.

      • Nur Fehler — Die Protokollierung ist nur für Fehler aktiviert.

      • Fehler und Informationsprotokolle — Die Protokollierung ist für alle Ereignisse aktiviert.

      • Vollständige Anfrage- und Antwortprotokolle — Die detaillierte Protokollierung ist für alle Ereignisse aktiviert. Dies kann zur Fehlerbehebung bei APIs hilfreich sein, kann aber dazu führen, dass sensible Daten protokolliert werden.

        Anmerkung

        Es wird empfohlen, Full Request and Response Logs (Vollständige Anforderungs- und Antwortprotokolle) nicht zu verwenden.

   2. Falls gewünscht, wählen Sie Detaillierte Metriken aus, um detaillierte CloudWatch Metriken zu aktivieren.

   Weitere Informationen zu CloudWatch Metriken finden Sie unterÜberwachen Sie REST API die Ausführung mit CloudWatch Amazon-Metriken.

8. 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.

9. Wählen Sie Änderungen speichern aus.

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.

Richten Sie die CloudWatch API-Protokollierung ein mit AWS CloudFormation

Verwenden Sie die folgende AWS CloudFormation Beispielvorlage, um eine Amazon CloudWatch Logs-Protokollgruppe zu erstellen und die Ausführungs- und Zugriffsprotokollierung für eine Phase zu konfigurieren. Um CloudWatch Logs zu aktivieren, müssen Sie API Gateway die Erlaubnis erteilen, Logs CloudWatch für Ihr Konto zu lesen und zu schreiben. 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