Verwenden des awslogs-Protokolltreibers

Sie können die Container in Ihren Aufgaben so konfigurieren, dass Protokollinformationen an - CloudWatch Protokolle gesendet werden. 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 awslogs Protokolltreiber übergibt diese Protokolle einfach von Docker an CloudWatch Logs. 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 Protokolle finden Sie unter Überwachen von -Protokolldateien und CloudWatch Protokollkontingenten im Amazon- CloudWatch Logs-Benutzerhandbuch.

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 zur Aufgabenausführungsrolle finden Sie unter IAM-Rolle für die Amazon-ECS-Aufgabenausführung. Wenn Ihre Container-Instances die verwaltete IAM-Richtlinie für Container-Instances verwenden, verfügen sie wahrscheinlich über die korrekten Berechtigungen. Informationen zur verwalteten IAM-Richtlinie für Container-Instances finden Sie unter IAM-Rolle für Amazon-ECS-Container-Instance.

Erstellen einer Protokollgruppe

Der awslogs Protokolltreiber kann Protokollstreams an eine vorhandene Protokollgruppe in CloudWatch Logs senden oder in Ihrem Namen eine neue Protokollgruppe erstellen. Die AWS Management Console bietet eine Option zur automatischen Konfiguration, die in Ihrem Namen eine Protokollgruppe erstellt, die den Familiennamen der Aufgabendefinition mit ecs als Präfix 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 zur Erstellung Ihrer Protokollgruppe nutzen zu können, muss Ihre IAM-Rollenrichtlinie für die Aufgabenausführung oder Ihre EC2-Instance-Rollenrichtlinie die logs:CreateLogGroup-Berechtigung 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 des Features zur automatischen Konfiguration, um eine Protokollgruppe zu erstellen

Wenn Sie eine Aufgabendefinition in der Amazon-ECS-Konsole registrieren, können Sie Amazon ECS 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. Weitere Informationen finden Sie unter Erstellen einer Aufgabendefinition mit der Konsole.

Verfügbare awslogs-Protokolltreiberoptionen

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

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

Geben Sie die an AWS-Region , an die der awslogs Protokolltreiber Ihre Docker-Protokolle senden soll. Sie können alle Ihre Protokolle von Clustern in verschiedenen Regionen an eine einzelne Region in CloudWatch Logs senden. 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: Ja, wenn Sie den Fargate-Starttyp verwenden. Optional für den EC2-Starttyp, erforderlich für den Fargate-Starttyp.

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. So können Sie Protokollstreams zu dem Service zurückverfolgen, zu dem der Container gehört, den Namen des Containers ermitteln, der sie gesendet hat, und die ID der Aufgabe, zu der der Container gehö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.

Sie können nicht sowohl die Optionen awslogs-datetime-format und awslogs-multiline-pattern konfigurieren.

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.

Sie können nicht sowohl die Optionen awslogs-datetime-format und awslogs-multiline-pattern konfigurieren.

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

Diese Option definiert den Übermittlungsmodus von Protokollnachrichten vom Container an CloudWatch Logs. Der von Ihnen gewählte Bereitstellungsmodus wirkt sich auf die Anwendungsverfügbarkeit aus, wenn der Fluss von Protokollen vom Container zu unterbrochen CloudWatch wird.

Wenn Sie den blocking Standardmodus verwenden und der Fluss der Protokolle an unterbrochen CloudWatch wird, werden Aufrufe vom Containercode zum Schreiben in die stderr Streams stdout und blockiert. Der Logging-Thread der Anwendung wird daraufhin blockiert. Dies kann dazu führen, dass die Anwendung nicht mehr reagiert und die Container-Zustandsprüfung fehlschlägt.

Wenn Sie den non-blocking-Modus verwenden, werden die Protokolle des Containers stattdessen in einem mit der Option max-buffer-size konfigurierten Zwischenpuffer im Arbeitsspeicher gespeichert. Dadurch wird verhindert, dass die Anwendung nicht mehr reagiert, wenn Protokolle nicht an gesendet werden können CloudWatch. Wir empfehlen, diesen Modus zu verwenden, wenn Sie die Verfügbarkeit des Services sicherstellen möchten und einen gewissen Protokollverlust in Kauf nehmen möchten.

max-buffer-size

Erforderlich: Nein

Standardwert: 1m

Wenn der non-blocking-Modus verwendet wird, steuert die max-buffer-size-Protokolloption die Größe des Puffers, der für die Zwischenspeicherung von Nachrichten verwendet wird. Stellen Sie sicher, dass Sie eine für Ihre Anwendung angemessene Puffergröße angeben. Wenn der Puffer voll ist, können keine weiteren Protokolle gespeichert werden. Protokolle, die nicht gespeichert werden können, gehen verloren.

Festlegen einer Protokollkonfiguration in Ihrer Aufgabendefinition

Bevor Ihre Container Protokolle an senden können CloudWatch, 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 Konsole.

Bei der unten gezeigten Aufgabendefinition JSON wurde ein logConfiguration-Objekt für jeden Container festgelegt. Eine bezieht sich auf den WordPress Container, der Protokolle an eine Protokollgruppe namens sendetawslogs-wordpress. 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",
                    "mode": "non-blocking", 
                    "max-buffer-size": "25m" 
                }
            }
        }
    ],
    "family": "awslogs-example"
}

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