Verwenden des awslogs-Protokolltreibers - Amazon Elastic Container Service

Verwenden des awslogs-Protokolltreibers

Sie können die Container in Ihren Aufgaben so konfigurieren, dass sie Protokollinformationen an CloudWatch Logs senden. Wenn Sie den Starttyp Fargate für Ihre Aufgaben verwenden, können Sie die Protokolle von Ihren Container einsehen. Wenn Sie den EC2-Starttyp verwenden, können Sie verschiedene Protokolle Ihrer Container bequem an einem Ort aufrufen und es wird verhindert, dass Ihre Containerprotokolle Speicherplatz in Ihren Container-Instances belegen.In diesem Thema finden Sie Informationen zu den ersten Schritten mit dem awslogs-Protokolltreiber in Ihren Aufgabendefinitionen.

Anmerkung

Der Typ der Informationen, die von den Containern in Ihrer Aufgabe protokolliert werden, hängt sehr stark von ihrem ENTRYPOINT-Befehl ab. Standardmäßig zeigen die erfassten Protokolle die Befehlsausgabe an, die Sie normalerweise in einem interaktiven Terminal sehen würden, wenn Sie den Container lokal ausführen. Dabei handelt es sich um die STDOUT- und STDERR-E/A-Streams. Der Protokolltreiber awslogs leitet diese Protokolle einfach von Docker an CloudWatch Logs weiter. Weitere Informationen dazu, wie Docker-Protokolle verarbeitet werden, einschließlich alternativer Möglichkeiten zum Erfassen unterschiedlicher Dateidaten oder Streams, finden Sie unter Anzeigen von Protokollen für einen Container oder Service in der Docker-Dokumentation.

Informationen zum Senden von Systemprotokollen von Ihren Amazon ECS-Container-Instances an CloudWatch Logs finden Sie unter Überwachen Ihrer Container-Instances. Weitere Informationen zu CloudWatch Logs finden Sie unter Überwachen von Protokolldateien und CloudWatch-Logs-Kontingente im Benutzerhandbuch zu Amazon CloudWatch Logs.

Aktivieren des awslogs-Protokolltreibers für Ihre Container

Wenn Sie den Starttyp Fargate für Ihre Aufgaben verwenden, müssen Sie für die Aktivierung des logConfiguration-Protokolltreibers nur die erforderlichen awslogs-Parameter in Ihre Aufgabendefinition einfügen. Weitere Informationen finden Sie unter Festlegen einer Protokollkonfiguration in Ihrer Aufgabendefinition.

Wenn Sie den Starttyp EC2 für Ihre Aufgaben verwenden und den Protokolltreiber awslogs aktivieren möchten, benötigen Ihre Amazon ECS Container-Instances mindestens Version 1.9.0 des Container-Agenten. Informationen zum Überprüfen Ihrer Agenten-Version und zum Aktualisieren auf die neueste Version finden Sie unter Überprüfen des Amazon ECS-Container-Agenten.

Anmerkung

Falls Sie kein Amazon ECS-optimiertes AMI (mindestens Version 1.9.0-1 des ecs-init-Pakets) für Ihre Container-Instances verwenden, dann müssen Sie ebenfalls angeben, dass der Protokolltreiber awslogs auf der Container-Instance verfügbar ist, wenn Sie den Agenten mit der folgenden Umgebungsvariable in Ihrer docker run-Anweisung oder in der Umgebungsvariablendatei starten. Weitere Informationen finden Sie unter Installieren des Amazon ECS-Container-Agenten.

ECS_AVAILABLE_LOGGING_DRIVERS='["json-file","awslogs"]'

Ihre Amazon ECS-Container-Instances benötigen auch eine logs:CreateLogStream- und logs:PutLogEvents-Berechtigung für die IAM-Rolle, mit der Sie Ihre Container-Instances starten. Wenn Sie die Amazon ECS-Container-Instance-Rolle erstellt haben, bevor die Unterstützung des Protokolltreibers awslogs in Amazon ECS aktiviert war, müssen Sie diese Berechtigung eventuell hinzufügen. Die ecsTaskExecutionRole wird verwendet, wenn sie der Aufgabe zugewiesen ist und wahrscheinlich die richtigen Berechtigungen enthält. Informationen zum Überprüfen Ihrer Aufgabenausführungsrolle finden Sie unter So prüfen Sie ecsTaskExecutionRole in der IAM-Konsole. Wenn Ihre Container-Instances die verwaltete IAM-Richtlinie für Container-Instances verwenden, verfügen sie wahrscheinlich über die korrekten Berechtigungen. Informationen zum Überprüfen Ihrer Amazon ECS-Container-Instance-Rolle und zum Anfügen der verwalteten IAM-Richtlinie für Container-Instances finden Sie unter So prüfen Sie ecsInstanceRole in der IAM-Konsole.

Erstellen einer Protokollgruppe

Der Protokolltreiber awslogs kann Protokollstreams an eine vorhandene Protokollgruppe in Amazon CloudWatch Logs senden oder in Ihrem Namen eine neue Protokollgruppe erstellen. Die AWS Management Console bietet eine automatische Konfigurationsoption, die in Ihrem Namen eine Protokollgruppe erstellt. Dabei wird der Name der Aufgabendefinitionsfamilie mit dem Präfix ecs verwendet. Alternativ können Sie Ihre Protokollkonfigurationsoptionen manuell angeben und die Option awslogs-create-group mit dem Wert true angeben, damit die Protokollgruppen in Ihrem Namen erstellt werden.

Anmerkung

Um die Option awslogs-create-group zum Erstellen Ihrer Protokollgruppe verwenden zu können, muss Ihre IAM-Richtlinie die Berechtigung logs:CreateLogGroup enthalten.

Der folgende Code zeigt, wie die Option awslogs-create-group festgelegt wird.

{ "containerDefinitions": [ { "logConfiguration": { "logDriver": "awslogs", "options": { "awslogs-group": "firelens-container", "awslogs-region": "us-west-2", "awslogs-create-group": "true", "awslogs-stream-prefix": "firelens" } } }

Verwendung der Funktion zur automatischen Konfiguration, um eine Protokollgruppe zu erstellen

Wenn Sie eine Aufgabendefinition in der Amazon ECS-Konsole registrieren, haben Sie die Möglichkeit, Amazon ECS zu erlauben, Ihre CloudWatch-Protokolle automatisch zu konfigurieren. Dadurch wird eine Protokollgruppe in Ihrem Namen erstellt. Dabei wird der Name der Aufgabendefinitionsfamilie mit dem Präfix ecs verwendet.

So verwenden Sie die Option zur automatischen Konfiguration der Protokollgruppe in der Amazon ECS-Konsole

  1. Öffnen Sie die Amazon ECS-Konsole unter https://console.aws.amazon.com/ecs/.

  2. Wählen Sie im linken Navigationsbereich Task Definitions, Create new Task Definition.

  3. Wählen Sie Ihre Kompatibilitätsoption aus und klicken auf Next Step (Nächster Schritt).

  4. Wählen Sie Add container aus.

  5. Wählen Sie im Abschnitt Storage and Logging (Speicher und Protokollierung) für Log configuration (Protokollkonfiguration) die Option Auto-configure CloudWatch Logs (CloudWatch Logs automatisch konfigurieren) aus.

  6. Geben Sie die Optionen für Ihren awslogs-Protokolltreiber ein. Weitere Informationen finden Sie unter Festlegen einer Protokollkonfiguration in Ihrer Aufgabendefinition.

  7. Setzen Sie den Assistenten für die Aufgabendefinition fort.

Verfügbare awslogs-Protokolltreiberoptionen

Der awslogs-Protokolltreiber unterstützt die folgenden Optionen in Amazon-ECS-Aufgabendefinitionen. Weitere Informationen finden Sie im CloudWatch Logs Protokolltreiber.

awslogs-create-group

Erforderlich: Nein

Geben Sie an, ob die Protokollgruppe automatisch erstellt werden soll. Wenn diese Option nicht angegeben ist, gilt standardmäßig false.

Anmerkung

Ihre IAM-Richtlinie muss die logs:CreateLogGroup-Berechtigung umfassen, bevor Sie awslogs-create-group zu nutzen versuchen.

awslogs-region

Erforderlich: Ja

Legen Sie die AWS-Region fest, an die der awslogs-Protokolltreiber Ihre Docker-Protokolle senden soll. Sie können auswählen, dass alle Protokolle von Clustern in verschiedenen Regionen an eine einzige Region in Amazon CloudWatch Logs gesendet werden. Dann sind alle an einem Standort sichtbar. Andernfalls können Sie sie nach Region aufteilen, um eine höhere Granularität zu erzielen. Vergewissern Sie sich, dass die angegebene Protokollgruppe in der Region vorhanden ist, die Sie mit dieser Option festlegen.

awslogs-group

Erforderlich: Ja

Sie müssen eine Protokollgruppe angeben, an die der awslogs-Protokolltreiber seine Protokoll-Streams sendet. Weitere Informationen finden Sie unter Erstellen einer Protokollgruppe.

awslogs-stream-prefix

Erforderlich: Optional für den EC2-Launchtyp, erforderlich für den Fargate-Launchtyp.

Mit der awslogs-stream-prefix-Option können Sie einen Protokoll-Stream mit dem angegebenen Präfix, dem Containernamen und der ID der Amazon-ECS-Aufgabe verknüpfen, zu der der Container gehört. Wenn Sie einen Präfix mit dieser Option angeben, weist der Protokoll-Stream das folgende Format auf:

prefix-name/container-name/ecs-task-id

Wenn Sie keinen Präfix mit dieser Option angeben, wird der Protokoll-Stream nach der Container-ID benannt, die vom Docker-Daemon auf der Container-Instance zugewiesen wurde. Da es schwierig ist, Protokolle nur mit der Docker-Container-ID (die nur auf der Container-Instance verfügbar ist) zum Container zurückzuverfolgen, der sie gesendet hat, empfehlen wir, dass Sie einen Präfix mit dieser Option festlegen.

Für Amazon-ECS-Services können Sie den Servicenamen als Präfix verwenden. Damit können Sie Protokoll-Streams zum Service zurückverfolgen, sowie den Namen des Containers ermitteln, der sie gesendet hat, und die ID der Aufgabe feststellen, der der Container angehört.

Sie müssen ein Stream-Präfix für Ihre Protokolle angeben, damit Ihre Protokolle im Protokollfeld der Amazon ECS-Konsole angezeigt werden.

awslogs-datetime-format

Erforderlich: Nein

Diese Option definiert einen mehrzeiliges Startmuster im strftime-Format von Python. Eine Protokollmeldung besteht aus einer Zeile, die mit dem angegebenen Muster übereinstimmt, und allen folgenden Zeilen, die nicht dem Muster entsprechen. Die zugeordnete Zeile ist das Trennzeichen zwischen Protokollnachrichten.

Ein Beispiel für einen Anwendungsfall für die Nutzung dieses Formats ist die Ausgabenanalyse, z. B. einen Stack-Dump, der andernfalls möglicherweise mehrere Einträge protokolliert. Mit dem richtigen Muster kann es in nur einem Eintrag erfasst werden.

Weitere Informationen finden Sie unter awslogs-datetime-format.

Diese Option hat immer Vorrang, wenn sowohl awslogs-datetime-format als auch awslogs-multiline-pattern konfiguriert sind.

Anmerkung

Bei der mehrzeiligen Protokollierung wird eine regelmäßige Ausdrucksanalyse und die Übereinstimmung aller Protokollmeldungen ausgeführt. Dies kann negative Auswirkungen auf die Leistung der Protokollierung haben.

awslogs-multiline-pattern

Erforderlich: Nein

Diese Option definiert ein mehrzeiliges Startmuster mit einem regulären Ausdruck. Eine Protokollmeldung besteht aus einer Zeile, die mit dem angegebenen Muster übereinstimmt, und allen folgenden Zeilen, die nicht dem Muster entsprechen. Die zugeordnete Zeile ist das Trennzeichen zwischen Protokollnachrichten.

Weitere Informationen finden Sie unter awslogs-multiline-pattern.

Diese Option wird ignoriert, wenn awslogs-datetime-format ebenfalls konfiguriert ist.

Anmerkung

Bei der mehrzeiligen Protokollierung wird eine regelmäßige Ausdrucksanalyse und die Übereinstimmung aller Protokollmeldungen ausgeführt. Dies kann negative Auswirkungen auf die Leistung der Protokollierung haben.

mode

Erforderlich: Nein

Zulässige Werte: non-blocking | blocking

Standardwert: blocking

Der Zustellungsmodus von Protokollmeldungen aus dem Container nach awslogs. Weitere Informationen finden Sie unter Protokollierungstreiber konfigurieren.

max-buffer-size

Erforderlich: Nein

Standardwert: 1m

Wenn der non-blocking-Modus verwendet wird, steuert die max-buffer-size-Protokolloption die Größe des Ringpuffers, der für die Zwischenspeicherung von Nachrichten verwendet wird.

Festlegen einer Protokollkonfiguration in Ihrer Aufgabendefinition

Bevor Ihre Container Protokolle an CloudWatch senden, müssen Sie den awslogs-Protokolltreiber für Container in Ihrer Aufgabendefinition angeben. In diesem Abschnitt wird die Protokollkonfiguration für einen Container beschrieben, der den awslogs-Protokolltreiber verwenden soll. Weitere Informationen finden Sie unter Erstellen einer Aufgabendefinition mit der neuen Konsole.

Bei der unten gezeigten Aufgabendefinition JSON wurde ein logConfiguration-Objekt für jeden Container festgelegt. Eines für den WordPress-Container, der Protokolle an eine Protokollgruppe mit dem Namen awslogs-wordpress sendet. Das andere für einen MySQL-Container, der Protokolle an eine Protokollgruppe mit dem Namen awslogs-mysql sendet. Beide Container verwenden den Protokoll-Stream-Präfix awslogs-example.

{ "containerDefinitions": [ { "name": "wordpress", "links": [ "mysql" ], "image": "wordpress", "essential": true, "portMappings": [ { "containerPort": 80, "hostPort": 80 } ], "logConfiguration": { "logDriver": "awslogs", "options": { "awslogs-create-group": "true", "awslogs-group": "awslogs-wordpress", "awslogs-region": "us-west-2", "awslogs-stream-prefix": "awslogs-example" } }, "memory": 500, "cpu": 10 }, { "environment": [ { "name": "MYSQL_ROOT_PASSWORD", "value": "password" } ], "name": "mysql", "image": "mysql", "cpu": 10, "memory": 500, "essential": true, "logConfiguration": { "logDriver": "awslogs", "options": { "awslogs-create-group": "true", "awslogs-group": "awslogs-mysql", "awslogs-region": "us-west-2", "awslogs-stream-prefix": "awslogs-example" } } } ], "family": "awslogs-example" }

Nachdem Sie mit dem awslogs-Protokolltreiber eine Aufgabendefinition in der Protokollkonfiguration einer Containerdefinition registriert haben, können Sie eine Aufgabe ausführen oder einen Service mit dieser Aufgabendefinition erstellen, um mit dem Senden von Protokollen an CloudWatch Logs zu beginnen. Weitere Informationen finden Sie unter Ausführen einer eigenständigen Aufgabe und Erstellen eines Amazon-ECS-Services.

Anzeigen von awslogs-Containerprotokollen in CloudWatch Logs

Für Aufgaben, die den Starttyp EC2 verwenden, werden Ihre Containeragenten, nachdem Ihre Container-Instance-Rolle über die erforderlichen Berechtigungen zum Senden von Protokollen an CloudWatch Logs verfügt, auf mindestens die Version 1.9.0 aktualisiert und Sie haben eine Aufgabe konfiguriert und mit Containern gestartet, die den Protokolltreiber awslogs verwenden. Jetzt sollten Ihre konfigurierten Container ihre Protokolldaten an CloudWatch Logs senden. Sie können diese Protokolle in der Konsole aufrufen und durchsuchen.

So zeigen Sie Ihre CloudWatch Logs-Daten für einen Container über die Amazon ECS-Konsole an

  1. Öffnen Sie die Amazon ECS-Konsole unter https://console.aws.amazon.com/ecs/.

  2. Wählen Sie auf der Seite Clusters den Cluster aus, der die anzuzeigende Aufgabe enthält.

  3. Wählen Sie auf der Seite Cluster: cluster_name Tasks und danach die anzuzeigende Aufgabe aus.

  4. Erweitern Sie auf der Seite Task: task_id die Container-Ansicht, indem Sie den Pfeil links neben dem Container-Namen auswählen.

  5. Wählen Sie im Bereich Log Configuration View logs in CloudWatch aus. Daraufhin wird in der CloudWatch-Konsole der zugeordnete Protokollstream geöffnet.

    
							Aufgabendefinitionsansicht der Protokollkonfiguration

So zeigen Sie Ihre CloudWatch Logs-Daten in der CloudWatch-Konsole an

  1. Öffnen Sie die CloudWatch-Konsole unter https://console.aws.amazon.com/cloudwatch/.

  2. Wählen Sie im linken Navigationsbereich Protokolle aus.

  3. Wählen Sie die anzuzeigende Protokollgruppe aus. Sie sollten nun die Protokollgruppen sehen, die Sie unter Erstellen einer Protokollgruppe erstellt haben.

    
							Metrikansicht der awslogs-Konsole
  4. Wählen Sie einen Protokollstream aus, der angezeigt werden soll.

    
							Metrikansicht der awslogs-Konsole