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 Die REST-API-Ausführung mit Amazon-CloudWatch-Metriken überwachen.

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 mehr. API Gateway redigiert Genehmigungs-Header, 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. Wählen Sie $context-Variablen, ein Protokollformat und eine Protokollgruppe als Ziel aus, um die Zugriffsdetails anzugeben.

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

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. Einen Protokollgruppen-ARN erhalten Sie in der CloudWatch-Konsole. 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.

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. AmazonAPIGatewayPushToCloudWatchLogs verfügt über alle erforderlichen Berechtigungen.

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.

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