Häufige Szenarien mit dem Agenten CloudWatch

In den folgenden Abschnitten wird beschrieben, wie allgemeine Konfigurations- und Anpassungsaufgaben für den CloudWatch Agenten ausgeführt werden.

Den CloudWatch Agenten unter einem anderen Benutzer ausführen

Auf Linux-Servern CloudWatch wird der standardmäßig als Root-Benutzer ausgeführt. Damit der Agent unter einem anderen Benutzer ausgeführt wird, verwenden Sie den run_as_user Parameter im agent Abschnitt in der CloudWatch Agenten-Konfigurationsdatei. Diese Option ist nur auf Linux-Servern verfügbar.

Wenn Sie den Agenten bereits mit dem Root-Benutzer ausführen und zu einem anderen Benutzer wechseln möchten, gehen Sie wie folgt vor.

Um den CloudWatch Agenten unter einem anderen Benutzer auf einer EC2-Instance unter Linux auszuführen

1. Laden Sie ein neues CloudWatch Agentenpaket herunter und installieren Sie es. Weitere Informationen finden Sie unter Laden Sie das CloudWatch Agentenpaket herunter.

2. Erstellen Sie einen neuen Linux-Benutzer oder verwenden Sie den Standardbenutzer cwagent, der die RPM- oder DEB-Datei erstellt hat.

3. Geben Sie auf eine der folgenden Arten Anmeldeinformationen für diesen Benutzer an:

   • Wenn die Datei im Home-Verzeichnis des Root-Benutzers .aws/credentials vorhanden ist, müssen Sie eine Anmeldeinformationsdatei für den Benutzer erstellen, mit dem Sie den CloudWatch Agenten ausführen möchten. Diese Datei mit den Anmeldeinformationen lautet /home/username/.aws/credentials. Setzen Sie dann den Wert des Parameters shared_credential_file in common-config.toml auf den Pfadnamen der Anmeldedatei. Weitere Informationen finden Sie unter (Optional) Ändern der gemeinsamen Konfiguration für Proxy- oder Regionsangaben.

   • Wenn die Datei .aws/credentials nicht im Heim-Verzeichnis des Stammbenutzers vorhanden ist, können Sie einen der folgenden Schritte ausführen:

     • Erstellen Sie eine Anmeldeinformationsdatei für den Benutzer, den Sie zum Ausführen des CloudWatch Agenten verwenden werden. Diese Datei mit den Anmeldeinformationen lautet /home/username/.aws/credentials. Setzen Sie dann den Wert des Parameters shared_credential_file in common-config.toml auf den Pfadnamen der Anmeldedatei. Weitere Informationen finden Sie unter (Optional) Ändern der gemeinsamen Konfiguration für Proxy- oder Regionsangaben.

     • Anstatt eine Datei mit Anmeldeinformationen zu erstellen, fügen Sie der Instance eine IAM-Rolle hinzu. Der Agent verwendet diese Rolle als Anmeldeprovider.

4. Fügen Sie in der CloudWatch Agent-Konfigurationsdatei im agent Abschnitt die folgende Zeile hinzu:

   "run_as_user": "username"

   Nehmen Sie bei Bedarf weitere Änderungen an der Konfigurationsdatei vor. Weitere Informationen finden Sie unter Erstellen Sie die CloudWatch Agent-Konfigurationsdatei.

5. Erteilen Sie dem Benutzer die erforderlichen Berechtigungen. Der Benutzer muss über Lese-(r)-Berechtigungen für die zu erfassenden Protokolldateien und über Execute-(x)-Berechtigung für jedes Verzeichnis im Pfad der Protokolldateien verfügen.

6. Starten Sie den Agenten mit der Konfigurationsdatei, die Sie gerade geändert haben.

   sudo /opt/aws/amazon-cloudwatch-agent/bin/amazon-cloudwatch-agent-ctl -a fetch-config -m ec2 -s -c file:configuration-file-path

Um den CloudWatch Agenten unter einem anderen Benutzer auf einem lokalen Server unter Linux auszuführen

1. Laden Sie ein neues CloudWatch Agentenpaket herunter und installieren Sie es. Weitere Informationen finden Sie unter Laden Sie das CloudWatch Agentenpaket herunter.

2. Erstellen Sie einen neuen Linux-Benutzer oder verwenden Sie den Standardbenutzer cwagent, der die RPM- oder DEB-Datei erstellt hat.

3. Speichern Sie die Anmeldeinformationen dieses Benutzers in einem Pfad, auf den der Benutzer zugreifen kann, z. B. /home/username/.aws/credentials.

4. Setzen Sie den Wert des Parameters shared_credential_file in common-config.toml auf den Pfadnamen der Anmeldedatei. Weitere Informationen finden Sie unter (Optional) Ändern der gemeinsamen Konfiguration für Proxy- oder Regionsangaben.

5. Fügen Sie in der CloudWatch Agent-Konfigurationsdatei die folgende Zeile in den agent Abschnitt ein:

   "run_as_user": "username"

   Nehmen Sie bei Bedarf weitere Änderungen an der Konfigurationsdatei vor. Weitere Informationen finden Sie unter Erstellen Sie die CloudWatch Agent-Konfigurationsdatei.

6. Erteilen Sie dem Benutzer erforderliche Berechtigungen. Der Benutzer muss über Lese-(r)-Berechtigungen für die zu erfassenden Protokolldateien und über Execute-(x)-Berechtigung für jedes Verzeichnis im Pfad der Protokolldateien verfügen.

7. Starten Sie den Agenten mit der Konfigurationsdatei, die Sie gerade geändert haben.

   sudo /opt/aws/amazon-cloudwatch-agent/bin/amazon-cloudwatch-agent-ctl -a fetch-config -m ec2 -s -c file:configuration-file-path

Wie der CloudWatch Agent mit spärlichen Protokolldateien umgeht

Sparse-Dateien sind Dateien mit leeren Blöcken und echten Inhalten. Eine Sparse-Datei verwendet Speicherplatz effizienter, indem anstelle der tatsächlichen Null-Bytes, aus denen der Block besteht, kurze Informationen, die die leeren Blöcke darstellen, auf die Festplatte geschrieben werden. Dadurch wird die tatsächliche Größe einer Sparse-Datei in der Regel viel kleiner als die scheinbare Größe.

Der CloudWatch Agent behandelt Dateien mit geringer Dichte jedoch nicht anders als normale Dateien. Wenn der Agent eine Sparse-Datei liest, werden die leeren Blöcke als „echte“ Blöcke behandelt, die mit Null-Bytes gefüllt sind. Aus diesem Grund veröffentlicht der CloudWatch Agent so viele Byte, wie die scheinbare Größe einer Datei mit geringer Dichte entspricht. CloudWatch

Wenn der CloudWatch Agent so konfiguriert wird, dass er eine Datei mit geringer Dichte veröffentlicht, kann dies zu höheren CloudWatch Kosten als erwartet führen. Wir empfehlen daher, dies nicht zu tun. Beispielsweise handelt es /var/logs/lastlog sich unter Linux normalerweise um eine Datei mit sehr geringer Dichte, und wir empfehlen, sie nicht in zu veröffentlichen. CloudWatch

Hinzufügen benutzerdefinierter Dimensionen zu den vom Agenten gesammelten Metriken CloudWatch

Um benutzerdefinierte Dimensionen wie Tags zu Metriken hinzuzufügen, die vom Agent erfasst werden, fügen Sie das Feld append_dimensions dem Abschnitt der Agent-Konfigurationsdatei hinzu, in dem diese Metriken aufgelistet sind.

Beispiel: Der folgende Beispielabschnitt der Konfigurationsdatei fügt eine benutzerdefinierte Dimension mit dem Namen stackName und dem Wert Prod zu den vom Agenten gesammelten Metriken cpu und disk hinzu.

"cpu":{  
  "resources":[  
    "*"
  ],
  "measurement":[  
    "cpu_usage_guest",
    "cpu_usage_nice",
    "cpu_usage_idle"
  ],
  "totalcpu":false,
  "append_dimensions":{  
    "stackName":"Prod"
  }
},
"disk":{  
  "resources":[  
    "/",
    "/tmp"
  ],
  "measurement":[  
    "total",
    "used"
  ],
  "append_dimensions":{  
    "stackName":"Prod"
  }
}

Beachten Sie, dass Sie den Agenten bei jeder Änderung der Agentenkonfigurationsdatei neu starten müssen, damit die Änderungen wirksam werden.

Mehrere CloudWatch Agenten-Konfigurationsdateien

Sowohl auf Linux- als auch auf Windows-Servern können Sie den CloudWatch Agenten so einrichten, dass er mehrere Konfigurationsdateien verwendet. Sie können zum Beispiel eine gemeinsame Konfigurationsdatei verwenden, die eine Reihe von Metriken, Protokollen und Ablaufverfolgungen sammelt, die Sie immer von allen Servern in Ihrer Infrastruktur sammeln möchten. Anschließend können Sie zusätzliche Konfigurationsdateien verwenden, die Metriken aus bestimmten Anwendungen oder in bestimmten Situationen erfassen.

Um dies einzurichten, erstellen Sie zunächst die Konfigurationsdateien, die Sie verwenden möchten. Alle Konfigurationsdateien, die gemeinsam auf demselben Server benutzt werden, müssen unterschiedliche Dateinamen haben. Sie können die Konfigurationsdateien auf Servern oder in Parameter Store speichern.

Starten Sie den CloudWatch Agenten mit der fetch-config Option und geben Sie die erste Konfigurationsdatei an. Um die zweite Konfigurationsdatei an den ausgeführten Agent anzufügen, verwenden Sie denselben Befehl, aber mit der append-config-Option. Alle Metriken, Protokolle und Ablaufverfolgungen, die in einer der beiden Konfigurationsdateien aufgeführt sind, werden gesammelt. Die folgenden Beispielbefehle veranschaulichen dieses Szenario mithilfe von Konfigurationen, die als Dateien gespeichert werden. Die erste Zeile startet den Agent mithilfe der infrastructure.json-Konfigurationsdatei und die zweite Zeile fügt die app.json-Konfigurationsdatei an.

Die folgenden Beispielbefehle gelten für Linux.

/opt/aws/amazon-cloudwatch-agent/bin/amazon-cloudwatch-agent-ctl -a fetch-config -m ec2 -s -c file:/tmp/infrastructure.json

/opt/aws/amazon-cloudwatch-agent/bin/amazon-cloudwatch-agent-ctl -a append-config -m ec2 -s -c file:/tmp/app.json

Die folgenden Beispielbefehle gelten für Windows Server.

& "C:\Program Files\Amazon\AmazonCloudWatchAgent\amazon-cloudwatch-agent-ctl.ps1" -a fetch-config -m ec2 -s -c file:"C:\Program Files\Amazon\AmazonCloudWatchAgent\infrastructure.json"

& "C:\Program Files\Amazon\AmazonCloudWatchAgent\amazon-cloudwatch-agent-ctl.ps1" -a append-config -m ec2 -s -c file:"C:\Program Files\Amazon\AmazonCloudWatchAgent\app.json"

Die folgenden Beispiel-Konfigurationsdateien veranschaulichen eine Nutzung für dieses Feature. Die erste Konfigurationsdatei wird für alle Server in der Infrastruktur verwendet, und die zweite erfasst nur Protokolle von einer bestimmten Anwendung und wird an Server angehängt, die die Anwendung ausführen.

infrastructure.json

{
  "metrics": {
    "metrics_collected": {
      "cpu": {
        "resources": [
          "*"
        ],
        "measurement": [
          "usage_active"
        ],
        "totalcpu": true
      },
      "mem": {
         "measurement": [
           "used_percent"
        ]
      }
    }
  },
  "logs": {
    "logs_collected": {
      "files": {
        "collect_list": [
          {
            "file_path": "/opt/aws/amazon-cloudwatch-agent/logs/amazon-cloudwatch-agent.log",
            "log_group_name": "amazon-cloudwatch-agent.log"
          },
          {
            "file_path": "/var/log/messages",
            "log_group_name": "/var/log/messages"
          }
        ]
      }
    }
  }
}

app.json

{
    "logs": {
        "logs_collected": {
            "files": {
                "collect_list": [
                    {
                        "file_path": "/app/app.log*",
                        "log_group_name": "/app/app.log"
                    }
                ]
            }
        }
    }
}

Die Dateinamen aller Konfigurationsdateien, die an die Konfiguration angehängt werden, müssen sich voneinander und vom Namen der anfänglichen Konfigurationsdatei unterscheiden. Wenn Sie append-config mit einer Konfigurationsdatei mit dem selben Dateinamen wie eine Konfigurationsdatei verwenden, die der Agent bereits verwendet, überschreibt der Append-Befehl die Informationen aus der ersten Konfigurationsdatei, anstatt Inhalte anzuhängen. Dies gilt auch, wenn sich zwei Konfigurationsdateien mit demselben Dateinamen in verschiedenen Dateipfaden befinden.

Das vorstehende Beispiel zeigt die Verwendung von zwei Konfigurationsdateien. Es gibt jedoch keine Beschränkungen hinsichtlich der Anzahl der Konfigurationsdateien, die Sie an die Agentenkonfiguration anhängen können. Sie können auch die Nutzung von Konfigurationsdateien auf Servern und Konfigurationen in Parameter Store kombinieren.

Aggregation oder Zusammenfassung der vom Agenten gesammelten Metriken CloudWatch

Um vom Agenten erfasste Metriken zu aggregieren oder zusammenzufassen, fügen Sie im Abschnitt für die betreffende Metrik in der Agentenkonfigurationsdatei das Feld aggregation_dimensions hinzu.

Beispielsweise fasst der folgende Abschnitt der Konfigurationsdatei Metriken in der AutoScalingGroupName-Dimension zusammen. Die Metriken aus allen Instances in der jeweiligen Auto-Scaling-Gruppe werden aggregiert und können als Ganzes angezeigt werden.

"metrics": {
  "cpu":{...}
  "disk":{...}
  "aggregation_dimensions" : [["AutoScalingGroupName"]]
}

Wenn Sie zusätzlich zum Zusammenfassen im Auto-Scaling-Gruppennamen auch die Kombination der einzelnen InstanceId- und InstanceType-Dimensionen zusammenfassen möchten, können Sie Folgendes hinzufügen.

"metrics": {
  "cpu":{...}
  "disk":{...}
  "aggregation_dimensions" : [["AutoScalingGroupName"], ["InstanceId", "InstanceType"]]
}

Wenn Sie stattdessen Metriken in einer Sammlung zusammenfassen möchten, verwenden Sie [].

"metrics": {
  "cpu":{...}
  "disk":{...}
  "aggregation_dimensions" : [[]]
}

Beachten Sie, dass Sie den Agenten bei jeder Änderung der Agentenkonfigurationsdatei neu starten müssen, damit die Änderungen wirksam werden.

Erfassung hochauflösender Metriken mit dem Agenten CloudWatch

Das metrics_collection_interval-Feld gibt das Zeitintervall für die erfassten Metriken in Sekunden an. Durch Angabe eines Werts von weniger als 60 für dieses Feld werden die Metriken als hochauflösende Metriken erfasst.

Beispiel: Wenn Sie möchten, dass alle Ihre Metriken hochauflösend sind und alle 10 Sekunden erfasst werden, geben Sie als Wert für metrics_collection_interval im Abschnitt agent „10“ als Intervall für die globale Erfassung von Metriken an.

"agent": {
  "metrics_collection_interval": 10
}

Alternativ wird im folgenden Beispiel festgelegt, dass die cpu-Metriken jede Sekunde erfasst werden, während andere Metriken jede Minute erfasst werden.

"agent":{  
  "metrics_collection_interval": 60
},
"metrics":{  
  "metrics_collected":{  
    "cpu":{  
      "resources":[  
        "*"
      ],
      "measurement":[  
        "cpu_usage_guest"
      ],
      "totalcpu":false,
      "metrics_collection_interval": 1
    },
    "disk":{  
      "resources":[  
        "/",
        "/tmp"
      ],
      "measurement":[  
        "total",
        "used"
      ]
    }
  }
}

Beachten Sie, dass Sie den Agenten bei jeder Änderung der Agentenkonfigurationsdatei neu starten müssen, damit die Änderungen wirksam werden.

Metriken, Protokolle und Ablaufverfolgungen an ein anderes Konto senden

Damit der CloudWatch Agent die Metriken, Logs oder Traces an ein anderes Konto sendet, geben Sie einen role_arn Parameter in der Agenten-Konfigurationsdatei auf dem sendenden Server an. Der role_arn-Wert legt eine IAM-Rolle im Zielkonto fest, die der Agent beim Senden von Daten an das Zielkonto verwendet. Diese Rolle ermöglicht dem sendenden Konto, eine entsprechende Rolle im Zielkonto anzunehmen, wenn die Metriken oder Protokolle für das Zielkonto bereitgestellt werden.

Sie können in der Konfigurationsdatei des Agenten auch separate role_arn-Zeichenfolgen angeben: eine für das Senden von Metriken, eine für das Senden von Protokollen und eine für das Senden von Ablaufverfolgungen.

Das folgende Beispiel für einen Teil des agent-Abschnitts in der Konfigurationsdatei legt fest, dass der Agent CrossAccountAgentRole verwendet, wenn er Daten an ein anderes Konto sendet.

{
  "agent": {
    "credentials": {
      "role_arn": "arn:aws:iam::123456789012:role/CrossAccountAgentRole"
    }
  },
  .....
}

Alternativ dazu können Sie im folgenden Beispiel verschiedene Rollen für das sendende Konto festlegen, um Metriken, Protokolle und Ablaufverfolgungen zu senden:

"metrics": {
    "credentials": {
     "role_arn": "RoleToSendMetrics"
    },
    "metrics_collected": {....

"logs": {
    "credentials": {
    "role_arn": "RoleToSendLogs"
    },
    ....

Erforderliche Richtlinien

Wenn Sie in der Agenten-Konfigurationsdatei einen Wert für role_arn festlegen, müssen Sie auch sicherstellen, dass die IAM-Rollen des sendenden Kontos und des Zielkontos über bestimmte Richtlinien verfügen. In den Rollen sowohl im sendenden als auch im Zielkonto muss CloudWatchAgentServerPolicy enthalten sein. Weitere Informationen zum Zuweisen dieser Richtlinie zu einer Rolle finden Sie unter Erstellen Sie IAM-Rollen zur Verwendung mit dem CloudWatch Agenten auf Amazon EC2 EC2-Instances.

Die Rolle im sendenden Konto muss außerdem die folgende Richtlinie enthalten. Sie fügen diese Richtlinie auf der Registerkarte Permissions (Berechtigungen) in der IAM-Konsole hinzu, wenn Sie die Rolle bearbeiten.

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Effect": "Allow",
            "Action": [
                "sts:AssumeRole"
            ],
            "Resource": [
                "arn:aws:iam::target-account-ID:role/agent-role-in-target-account"
            ]
        }
    ]
}

Die Rolle im Zielkonto muss die folgende Richtlinie enthalten, damit es die vom sendenden Konto verwendete IAM-Rolle erkennen kann. Sie fügen diese Richtlinie auf der Registerkarte Trust relationships (Vertrauensstellungen) in der IAM-Konsole hinzu, wenn Sie die Rolle bearbeiten. Die Rolle im Zielkonto, zu der Sie diese Richtlinie hinzufügen, ist die Rolle, die Sie unter Erstellen Sie IAM-Rollen und -Benutzer für die Verwendung mit dem Agenten CloudWatch erstellt haben. Dabei handelt es sich um die Rolle, die Sie unter agent-role-in-target-account in der Richtlinie angegebenen haben, die vom sendenden Konto verwendet wird.

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Principal": {
        "AWS": [
          "arn:aws:iam::sending-account-ID:role/role-in-sender-account"
        ]
      },
      "Action": "sts:AssumeRole"
    }
  ]
}

Zeitstempelunterschiede zwischen dem Unified CloudWatch Agent und dem früheren CloudWatch Logs-Agenten

Der CloudWatch Agent unterstützt im Vergleich zum früheren CloudWatch Logs-Agent einen anderen Satz von Symbolen für Zeitstempelformate. Diese Unterschiede sind in der folgenden Tabelle aufgeführt.

Von beiden Agenten unterstützte Symbole	Symbole, die nur von Unified CloudWatch Agent unterstützt werden	Symbole, die nur von früheren CloudWatch Logs-Agenten unterstützt wurden
%A, %a, %b, %B, %d, %f, %H, %l, %m, %M, %p, %S, %y, %Y, %Z, %z	%-d, %-l, %-m, %-M, %-S	%c,%j, %U, %W, %w

Weitere Informationen zu den Bedeutungen der vom neuen CloudWatch Agenten unterstützten Symbole finden Sie unter CloudWatch Agenten-Konfigurationsdatei: Abschnitt Protokolle im CloudWatch Amazon-Benutzerhandbuch. Informationen zu den vom CloudWatch Logs-Agenten unterstützten Symbolen finden Sie in der Agent-Konfigurationsdatei im Amazon CloudWatch Logs-Benutzerhandbuch.