CloudWatch Logging für REST APIs in API Gateway einrichten

Um Probleme im Zusammenhang mit der Ausführung von Anfragen oder dem Client-Zugriff auf Ihre zu behebenAPI, können Sie Amazon CloudWatch Logs zur Protokollierung von API Anrufen 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. APIGateway entfernt Autorisierungsheader, API Schlüsselwerte und ähnliche sensible Anforderungsparameter aus den protokollierten Daten.

Wenn Sie eine bereitstellenAPI, erstellt API Gateway eine Protokollgruppe und protokolliert 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.

Bei der Zugriffsprotokollierung möchten Sie als API Entwickler protokollieren, wer auf Ihre Daten zugegriffen hat API und wie der Anrufer auf die API zugegriffen hat. Sie können Ihre eigene Protokollgruppe erstellen oder eine vorhandene Protokollgruppe auswählen, die von API Gateway verwaltet werden könnte. 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 im x-amzn-RequestId Header protokolliert. Clients können den Wert im x-amzn-RequestId Header mit einem Wert im Format eines universell eindeutigen Bezeichners (UUID) überschreiben. APIGateway gibt diese Anforderungs-ID im x-amzn-RequestId Antwort-Header zurück. APIGateway ersetzt überschriebene AnfragenIDs, die nicht das Format A haben, UUID_REPLACED_INVALID_REQUEST_ID in Ihren UUID Zugriffsprotokollen durch.

$context.extendedRequestId

Die extendedRequest ID ist eine eindeutige ID, die API Gateway generiert. APIGateway gibt diese Anforderungs-ID im x-amz-apigw-id Antwort-Header zurück. Ein API Anrufer kann diese Anforderungs-ID nicht angeben oder überschreiben. Möglicherweise müssen Sie diesen Wert dem AWS Support zur Verfügung stellen, um Probleme mit Ihrem Problem zu behebenAPI. 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, das auch von Ihrem Analyse-Backend übernommen wird, z. B. Common Log Format (CLF), JSONXML, 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 die Protokollgruppe in der destinationArn Eigenschaft accessLogSettings/ARNauf der Bühne fest. Sie können eine Protokollgruppe 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 angezeigt und sind 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 CloudWatch Protokollierung

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 Wert vonarn: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

APIGateway ruft AWS Security Token Service auf, um die IAM Rolle zu übernehmen. Stellen Sie also sicher, dass sie für die Region aktiviert AWS STS ist. Weitere Informationen finden Sie unter Verwaltung AWS STS in einer AWS Region.

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 vorherige Richtlinie hinzu und legen Sie die IAM Rolle ARN in der Eigenschaft cloudWatchRoleArn Ihres Kontos 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 Einstellen der IAM Rolle eine Fehlermeldung erhaltenARN, ü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 AWS STSim IAMBenutzerhandbuch unter Verwaltung in einer AWS Region.

Richten Sie die CloudWatch API Protokollierung mithilfe der API Gateway-Konsole ein

Um die CloudWatch API Protokollierung einzurichten, müssen Sie das API in einer Phase bereitgestellt haben. Sie müssen auch eine entsprechende CloudWatch Logs-Rolle ARN für Ihr Konto konfiguriert haben.

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

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

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

4. Wählen Sie im Hauptnavigationsbereich eine der folgenden Optionen aus APIs, und führen Sie dann eine der folgenden Aktionen aus:

   1. Wählen Sie eine vorhandene API Phase und anschließend eine Phase aus.

   2. Erstellen Sie eine API und stellen Sie sie dann in einer Phase 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. Es gibt folgende Protokollierungsstufen:

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

   2. (Optional) Wählen Sie Datenverfolgung aus, um die Datenprotokollierung für Ihre Phase zu aktivieren. Dies kann bei der Fehlerbehebung nützlich seinAPIs, kann jedoch dazu führen, dass vertrauliche Daten protokolliert werden.

      Anmerkung

      Wir empfehlen, die Datenverfolgung nicht für die Produktion APIs zu verwenden.

   3. (Optional) 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 als Ziel für ARN das Zugriffsprotokoll den ARN Namen einer Protokollgruppe ein. Das ARN Format istarn:aws:logs:{region}:{account-id}:log-group:log-group-name.

   3. Geben Sie unter Log Format (Protokollformat) ein Protokollformat ein. Sie können CLF, JSONXML, oder wählen CSV. Weitere Informationen zu Beispielprotokollformaten finden Sie unter CloudWatch Protokollformate für API Gateway.

9. Wählen Sie Änderungen speichern.

Anmerkung

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

APIGateway ist jetzt bereit, Anfragen an Ihren zu protokollierenAPI. Sie müssen die nicht erneut bereitstellen, API 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 im AWS CloudFormation Benutzerhandbuch unter Konto mit IAM Rolle verknüpfen.

  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