Die vorliegende Übersetzung wurde maschinell erstellt. Im Falle eines Konflikts oder eines Widerspruchs zwischen dieser übersetzten Fassung und der englischen Fassung (einschließlich infolge von Verzögerungen bei der Übersetzung) ist die englische Fassung maßgeblich.
# Erfassung von Protokollen über HTTP-Endpunkte
Amazon CloudWatch Logs bietet HTTP-Endpunkte, mit denen Sie CloudWatch Protokolle mithilfe einfacher HTTP-POST-Anfragen direkt an Logs senden können. Diese Endpunkte unterstützen sowohl die SigV4-Authentifizierung als auch die Bearer-Token-Authentifizierung.
**Wichtig**
Wir empfehlen die Verwendung der SigV4-Authentifizierung für alle Produktionsworkloads, bei denen AWS eine SDK-Integration möglich ist. SigV4 verwendet kurzfristige Anmeldeinformationen und bietet die stärkste Sicherheitslage. Die Bearer-Token-Authentifizierung (API-Schlüssel) ist für Szenarien vorgesehen, in denen SigV4 nicht durchführbar ist, z. B. für Log-Forwarder von Drittanbietern, die die SDK-Integration nicht unterstützen. AWS Weitere Informationen finden Sie unter [Alternativen zu langfristigen Zugriffsschlüsseln](https://docs.aws.amazon.com/IAM/latest/UserGuide/best-practices.html#bp-workloads-use-roles) im *IAM-Benutzerhandbuch*.
CloudWatch Logs unterstützt die folgenden Endpunkte für die HTTP-Erfassung:
| Endpoint | Pfad | Content-Type | Format |
| --- | --- | --- | --- |
| [OpenTelemetry Logs](CWL_HTTP_Endpoints_OTLP.md) | /v1/logs | application/json oder application/x-protobuf | OTLP-JSON oder Protobuf |
| [HLC Logs](CWL_HLC_Endpoint.md) | /services/collector/event | application/json | HLC-Format |
| [ND-JSON Logs](CWL_HTTP_Endpoints_NDJSON.md) | /ingest/bulk | application/json oder application/x-ndjson | JSON |
| [Structured JSON Logs](CWL_HTTP_Endpoints_StructuredJSON.md) | /ingest/json | application/json | JSON-Objekt oder -Array |
## Gemeinsames Verhalten
Alle HTTP-Ingestion-Endpunkte weisen das folgende Verhalten auf:
**Authentifizierung**
Alle Endpunkte unterstützen sowohl die SigV4-Authentifizierung als auch die Bearer-Token-Authentifizierung:
+ **Sigv4 (empfohlen)** — Signierung mit AWS Standardsignatur Version 4. Verwenden Sie SigV4 immer dann, wenn Ihre Anwendung oder Infrastruktur das AWS SDK unterstützt oder Anfragen signieren kann. SigV4 verwendet kurzfristige Anmeldeinformationen und ist die sicherste Authentifizierungsmethode.
+ **Bearer-Token** — Verwenden Sie den `Authorization: Bearer ` Header.
+ Das Token muss ein gültiges ACWL-Bearer-Token sein. Anweisungen zur Einrichtung finden Sie unter. [Einrichtung der Bearer-Token-Authentifizierung](CWL_HTTP_Endpoints_BearerTokenAuth.md)
+ Erfordert die `logs:PutLogEvents` und `logs:CallWithBearerToken` IAM-Berechtigungen.
**Protokollgruppe und Protokollstream**
+ Wird über Header bereitgestellt: `x-aws-log-group` und `x-aws-log-stream`
+ Abfrageparameter `?logGroup=&logStream=` werden auch auf allen Endpunkten außer OTLP unterstützt.
+ Sie können nicht sowohl Abfrageparameter als auch Header für denselben Parameter verwenden.
+ Sowohl die Protokollgruppe als auch der Protokollstream sind erforderlich.
**Antwort**
+ Erfolg: `HTTP 200` mit Körper `{}`
+ Fehler bei der Validierung: `HTTP 400`
+ Fehler bei der Authentifizierung: `HTTP 401`
# Einrichtung der Bearer-Token-Authentifizierung
Bevor Sie Protokolle mithilfe der Bearer-Token-Authentifizierung mit einem der HTTP-Ingestion-Endpunkte senden können, müssen Sie:
+ Erstellen Sie einen IAM-Benutzer mit Logs-Berechtigungen CloudWatch
+ Generieren Sie dienstspezifische Anmeldeinformationen (Bearer-Token)
+ Erstellen Sie eine Protokollgruppe und einen Protokollstream
+ Aktivieren Sie die Bearer-Token-Authentifizierung für die Protokollgruppe
**Wichtig**
Wir empfehlen, für alle Workloads, bei denen dies möglich ist, die SigV4-Authentifizierung mit kurzfristigen Anmeldeinformationen zu verwenden. SigV4 bietet die stärkste Sicherheitslage. Beschränken Sie die Verwendung von API-Schlüsseln (Bearer-Token) auf Szenarien, in denen eine kurzfristige Authentifizierung auf der Grundlage von Anmeldeinformationen nicht möglich ist. Wenn Sie bereit sind, CloudWatch Logs in Anwendungen mit höheren Sicherheitsanforderungen zu integrieren, sollten Sie auf kurzfristige Anmeldedaten umsteigen. Weitere Informationen finden Sie unter [Alternativen zu langfristigen Zugriffsschlüsseln](https://docs.aws.amazon.com/IAM/latest/UserGuide/best-practices.html#bp-workloads-use-roles) im *IAM-Benutzerhandbuch*.
## Option 1: Schnellstart mit der Konsole AWS
Die AWS Management Console bietet einen optimierten Arbeitsablauf zur Generierung von API-Schlüsseln für den HTTP-Endpunktzugriff.
**So richten Sie den HTTP-Endpunktzugriff mithilfe der Konsole ein**
1. Melden Sie sich bei der AWS Management Console an.
1. Navigieren Sie zu **CloudWatch**> **Einstellungen** > **Protokolle**.
1. Wählen Sie im Abschnitt API-Schlüssel die Option **API-Schlüssel generieren** aus.
1. Für den **Ablauf des API-Schlüssels** haben Sie folgende Möglichkeiten:
+ Wählen Sie eine Ablaufdauer für den API-Schlüssel von **1**, **5**, **30**, **90** oder **365** Tagen aus.
+ Wählen Sie **Benutzerdefinierte Dauer** aus, um ein benutzerdefiniertes Ablaufdatum für den API-Schlüssel festzulegen.
+ Wählen Sie **Nie abläuft** aus (nicht empfohlen).
1. Wählen Sie **API-Schlüssel generieren** aus.
Die Konsole automatisch:
+ Erstellt einen neuen IAM-Benutzer mit den entsprechenden Berechtigungen
+ Hängt die verwaltete [CloudWatchLogsAPIKeyAccess-Richtlinie](https://docs.aws.amazon.com/aws-managed-policy/latest/reference/CloudWatchLogsAPIKeyAccess.html) an (einschließlich `logs:PutLogEvents` und `logs:CallWithBearerToken` Berechtigungen)
+ Generiert dienstspezifische Anmeldeinformationen (API-Schlüssel)
1. Kopieren Sie die angezeigten Anmeldeinformationen und speichern Sie sie sicher:
+ **API-Schlüssel-ID** (dienstspezifische Anmeldeinformations-ID)
+ **Geheimer API-Schlüssel** (Inhaber-Token)
**Wichtig**
Speichern Sie das API-Schlüsselgeheimnis sofort. Er kann später nicht mehr abgerufen werden. Wenn Sie ihn verlieren, müssen Sie einen neuen API-Schlüssel generieren.
1. Erstellen Sie die Protokollgruppe und den Protokollstream, in denen Ihre Protokolle gespeichert werden:
```
# Create the log group
aws logs create-log-group \
--log-group-name /aws/hlc-logs/my-application \
--region us-east-1
# Create the log stream
aws logs create-log-stream \
--log-group-name /aws/hlc-logs/my-application \
--log-stream-name application-stream-001 \
--region us-east-1
```
1. Aktivieren Sie die Bearer-Token-Authentifizierung für die Protokollgruppe:
```
aws logs put-bearer-token-authentication \
--log-group-identifier /aws/hlc-logs/my-application \
--bearer-token-authentication-enabled \
--region us-east-1
```
Überprüfen Sie die Konfiguration:
```
aws logs describe-log-groups \
--log-group-name-prefix /aws/hlc-logs/my-application \
--region us-east-1
```
**Enthaltene Berechtigungen:** Der automatisch erstellte IAM-Benutzer verfügt über die folgenden Berechtigungen:
+ `logs:PutLogEvents`— Sendet Protokollereignisse an CloudWatch Logs
+ `logs:CallWithBearerToken`— Authentifizieren Sie sich mit dem Bearer-Token
+ `kms:Describe*`,`kms:GenerateDataKey*`, `kms:Decrypt` — Greifen Sie auf KMS-verschlüsselte Protokollgruppen zu (mit einer Bedingung, die auf den Protokolldienst beschränkt ist)
## Option 2: Manuelle Einrichtung
Wenn Sie mehr Kontrolle über die IAM-Konfiguration bevorzugen oder die Berechtigungen anpassen müssen, können Sie den HTTP-Endpunktzugriff manuell einrichten.
### Schritt 1: Erstellen Sie einen IAM-Benutzer
Erstellen Sie einen IAM-Benutzer, der für die Protokollaufnahme verwendet wird:
1. Melden Sie sich bei der AWS Management Console an und navigieren Sie zu IAM.
1. Wählen Sie im linken Navigationsbereich **Benutzer** aus.
1. Wählen Sie **Create user** (Benutzer erstellen) aus.
1. Geben Sie einen Benutzernamen ein (z. B.`cloudwatch-logs-hlc-user`).
1. Wählen Sie **Weiter** aus.
1. Fügen Sie eine der folgenden IAM-Richtlinien hinzu:
**Option A: Verwenden Sie die verwaltete Richtlinie (empfohlen)**
Hängen Sie die verwaltete [CloudWatchLogsAPIKeyAccess-Richtlinie](https://docs.aws.amazon.com/aws-managed-policy/latest/reference/CloudWatchLogsAPIKeyAccess.html) an.
**Option B: Erstellen Sie eine benutzerdefinierte Richtlinie**
Erstellen Sie die folgende IAM-Richtlinie und fügen Sie sie an:
```
{
"Version": "2012-10-17",
"Statement": [
{
"Sid": "LogsAPIs",
"Effect": "Allow",
"Action": [
"logs:CallWithBearerToken",
"logs:PutLogEvents"
],
"Resource": "*"
},
{
"Sid": "KMSAPIs",
"Effect": "Allow",
"Action": [
"kms:Describe*",
"kms:GenerateDataKey*",
"kms:Decrypt"
],
"Condition": {
"StringEquals": {
"kms:ViaService": [
"logs.*.amazonaws.com"
]
}
},
"Resource": "arn:aws:kms:*:*:key/*"
}
]
}
```
1. Wählen Sie **Weiter** und dann **Benutzer erstellen**.
**Anmerkung**
Die KMS-Berechtigungen sind erforderlich, wenn Sie Protokolle an KMS-verschlüsselte Protokollgruppen senden möchten. Die Bedingung beschränkt den KMS-Zugriff nur auf Schlüssel, die über CloudWatch den Logs-Dienst verwendet werden.
### Schritt 2: Generieren Sie dienstspezifische Anmeldeinformationen (API-Schlüssel)
Generieren Sie den CloudWatch Logs-API-Schlüssel mithilfe der [CreateServiceSpecificCredential](https://docs.aws.amazon.com/IAM/latest/APIReference/API_CreateServiceSpecificCredential.html)API. Sie können auch den [create-service-specific-credential](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/iam/create-service-specific-credential.html)CLI-Befehl verwenden. Für das Alter der Anmeldeinformationen können Sie einen Wert zwischen 1—36600 Tagen angeben. Wenn Sie keine Gültigkeitsdauer für die Anmeldeinformationen angeben, läuft der API-Schlüssel nicht ab.
Um einen API-Schlüssel mit einem Ablauf von 30 Tagen zu generieren:
```
aws iam create-service-specific-credential \
--user-name cloudwatch-logs-hlc-user \
--service-name logs.amazonaws.com \
--credential-age-days 30
```
Die Antwort ist ein [ServiceSpecificCredential](https://docs.aws.amazon.com/IAM/latest/APIReference/API_ServiceSpecificCredential.html)Objekt. Der `ServiceCredentialSecret` Wert ist Ihr CloudWatch Logs-API-Schlüssel (Bearer-Token).
**Wichtig**
Speichern Sie den Wert „`ServiceCredentialSecret`“ sicher, da Sie ihn später nicht mehr abrufen können. Wenn Sie ihn verlieren, müssen Sie einen neuen API-Schlüssel generieren.
### Schritt 3: Erstellen Sie eine Protokollgruppe und einen Protokollstream
Erstellen Sie die Protokollgruppe und den Protokollstream, in denen Ihre Protokolle gespeichert werden:
```
# Create the log group
aws logs create-log-group \
--log-group-name /aws/hlc-logs/my-application \
--region us-east-1
# Create the log stream
aws logs create-log-stream \
--log-group-name /aws/hlc-logs/my-application \
--log-stream-name application-stream-001 \
--region us-east-1
```
### Schritt 4: Aktivieren Sie die Bearer-Token-Authentifizierung
Aktivieren Sie die Bearer-Token-Authentifizierung für die Protokollgruppe:
```
aws logs put-bearer-token-authentication \
--log-group-identifier /aws/hlc-logs/my-application \
--bearer-token-authentication-enabled \
--region us-east-1
```
Überprüfen Sie die Konfiguration:
```
aws logs describe-log-groups \
--log-group-name-prefix /aws/hlc-logs/my-application \
--region us-east-1
```
## Steuern Sie die Berechtigungen für die Generierung und Verwendung von CloudWatch Logs-API-Schlüsseln
Die Generierung und Verwendung von CloudWatch Logs-API-Schlüsseln wird durch Aktionen und Bedingungsschlüssel sowohl in den CloudWatch Logs- als auch in den IAM-Diensten gesteuert.
### Steuerung der Generierung von CloudWatch Logs-API-Schlüsseln
Die CreateServiceSpecificCredential Aktion [iam:](https://docs.aws.amazon.com/service-authorization/latest/reference/list_awsidentityandaccessmanagementiam.html#awsidentityandaccessmanagementiam-actions-as-permissions) steuert die Generierung eines dienstspezifischen Schlüssels (z. B. eines CloudWatch Logs-API-Schlüssels). Sie können diese Aktion auf IAM-Benutzer als Ressource beschränken, um die Anzahl der Benutzer einzuschränken, für die ein Schlüssel generiert werden kann.
Mit den folgenden Bedingungsschlüsseln können Sie Bedingungen mit der Berechtigung für die Aktion `iam:CreateServiceSpecificCredential` verknüpfen:
+ [iam: ServiceSpecificCredentialAgeDays](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_policies_iam-condition-keys.html#ck_ServiceSpecificCredentialAgeDays) — Ermöglicht es Ihnen, in der Bedingung die Ablaufzeit des Schlüssels in Tagen anzugeben. Sie können diesen Bedingungsschlüssel zum Beispiel verwenden, um nur das Erstellen von API-Schlüsseln zu erlauben, die innerhalb von 90 Tagen ablaufen.
+ [iam: ServiceSpecificCredentialServiceName](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_policies_iam-condition-keys.html#ck_ServiceSpecificCredentialAgeDays) — Ermöglicht es Ihnen, in der Bedingung den Namen eines Dienstes anzugeben. Sie können diesen Bedingungsschlüssel beispielsweise verwenden, um nur die Erstellung von API-Schlüsseln für CloudWatch Logs und nicht für andere Dienste zuzulassen.
### Steuerung der Verwendung von CloudWatch Logs-API-Schlüsseln
Die `logs:CallWithBearerToken` Aktion steuert die Verwendung eines CloudWatch Logs-API-Schlüssels. Um zu verhindern, dass eine Identität CloudWatch Logs-API-Schlüssel verwendet, fügen Sie eine Richtlinie hinzu, die dem IAM-Benutzer, der dem Schlüssel zugeordnet ist, die `logs:CallWithBearerToken` Aktion verweigert.
### Beispielrichtlinien
#### Verhindern Sie, dass eine Identität CloudWatch Logs-API-Schlüssel generiert und verwendet
```
{
"Version": "2012-10-17",
"Statement": [
{
"Sid": "DenyCWLAPIKeys",
"Effect": "Deny",
"Action": [
"iam:CreateServiceSpecificCredential",
"logs:CallWithBearerToken"
],
"Resource": "*"
}
]
}
```
**Warnung**
Diese Richtlinie verhindert die Erstellung von Anmeldeinformationen für alle AWS Dienste, die die Erstellung dienstspezifischer Anmeldeinformationen unterstützen. Weitere Informationen finden Sie unter [Servicespezifische Anmeldeinformationen für IAM-Benutzer](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_credentials_service-specific-creds.html).
#### Verhindern Sie, dass eine Identität CloudWatch Logs-API-Schlüssel verwendet
```
{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Deny",
"Action": "logs:CallWithBearerToken",
"Resource": "*"
}
]
}
```
#### Erlauben Sie die Erstellung von CloudWatch Logs-Schlüsseln nur, wenn sie innerhalb von 90 Tagen ablaufen
```
{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": "iam:CreateServiceSpecificCredential",
"Resource": "arn:aws:iam::123456789012:user/username",
"Condition": {
"StringEquals": {
"iam:ServiceSpecificCredentialServiceName": "logs.amazonaws.com"
},
"NumericLessThanEquals": {
"iam:ServiceSpecificCredentialAgeDays": "90"
}
}
}
]
}
```
## Rotierende API-Schlüssel
Durch die regelmäßige Rotation Ihrer API-Schlüssel wird das Risiko eines unbefugten Zugriffs verringert. Wir empfehlen, einen Rotationsplan aufzustellen, der den Sicherheitsrichtlinien Ihres Unternehmens entspricht.
### Rotationsprozess
Gehen Sie wie folgt vor, um einen API-Schlüssel zu rotieren, ohne die Protokollzustellung zu unterbrechen:
1. Erstellen Sie einen neuen (sekundären) Berechtigungsnachweis für den IAM-Benutzer:
```
aws iam create-service-specific-credential \
--user-name cloudwatch-logs-hlc-user \
--service-name logs.amazonaws.com \
--credential-age-days 90
```
1. (Optional) Speichern Sie die neuen Anmeldeinformationen AWS Secrets Manager für einen sicheren Abruf und eine automatische Rotation.
1. Importieren Sie die neuen Anmeldeinformationen in das Portal Ihres Anbieters oder aktualisieren Sie Ihre Anwendungskonfiguration, um den neuen API-Schlüssel zu verwenden.
1. Setzen Sie die ursprünglichen Anmeldeinformationen auf inaktiv:
```
aws iam update-service-specific-credential \
--user-name cloudwatch-logs-hlc-user \
--service-specific-credential-id ACCA1234EXAMPLE1234 \
--status Inactive
```
1. Stellen Sie sicher, dass die Protokollzustellung nicht beeinträchtigt wird, indem Sie die `IncomingBytes` Metrik für Ihre Protokollgruppe in überwachen. CloudWatch Weitere Informationen finden Sie unter [Überwachung mit CloudWatch Metriken](https://docs.aws.amazon.com/AmazonCloudWatch/latest/logs/CloudWatch-Logs-Monitoring-CloudWatch-Metrics.html).
1. Nachdem Sie die erfolgreiche Zustellung mit dem neuen Schlüssel bestätigt haben, löschen Sie die vorherigen Anmeldeinformationen:
```
aws iam delete-service-specific-credential \
--service-specific-credential-id ACCA1234EXAMPLE1234
```
### Ablauf des Schlüssels überwachen
Verwenden Sie den folgenden [list-service-specific-credentials](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/iam/list-service-specific-credentials.html)Befehl, um das Erstellungsdatum und den Status Ihrer vorhandenen API-Schlüssel zu überprüfen:
```
aws iam list-service-specific-credentials \
--user-name cloudwatch-logs-hlc-user \
--service-name logs.amazonaws.com
```
Die Antwort beinhaltet `CreateDate` und `Status` für jeden Berechtigungsnachweis. Verwenden Sie diese Informationen, um Schlüssel zu identifizieren, die bald ablaufen oder die schon länger aktiv sind, als es Ihre Rotationsrichtlinie zulässt.
## Reaktion auf einen kompromittierten API-Schlüssel
Wenn Sie vermuten, dass ein API-Schlüssel kompromittiert wurde, führen Sie sofort die folgenden Schritte durch:
1. **Deaktivieren Sie den Schlüssel sofort**, um eine weitere unbefugte Verwendung zu verhindern:
```
aws iam update-service-specific-credential \
--user-name cloudwatch-logs-hlc-user \
--service-specific-credential-id ACCA1234EXAMPLE1234 \
--status Inactive
```
1. **Überprüfen Sie die CloudTrail Protokolle**, um den Umfang des unbefugten Zugriffs zu ermitteln. Weitere Informationen [Protokollierung der Verwendung von API-Schlüsseln mit CloudTrail](#CWL_HTTP_Endpoints_CloudTrail_Logging) zur Aktivierung der Überwachung der API-Schlüsselnutzung finden Sie unter.
1. **Erstellen Sie nach dem unter beschriebenen Rotationsprozess einen Ersatzschlüssel**[Rotationsprozess](#CWL_HTTP_Endpoints_Rotation_Process).
1. **Löschen Sie den kompromittierten Schlüssel**, nachdem der Ersatzschlüssel installiert wurde:
```
aws iam delete-service-specific-credential \
--service-specific-credential-id ACCA1234EXAMPLE1234
```
1. **Fügen Sie eine Ablehnungsrichtlinie** hinzu, wenn Sie sofort den gesamten Zugriff auf Inhaber-Tokens für den IAM-Benutzer sperren müssen, während Sie die folgenden Untersuchungen durchführen:
```
{
"Version": "2012-10-17",
"Statement": {
"Effect": "Deny",
"Action": "logs:CallWithBearerToken",
"Resource": "*"
}
}
```
**Anmerkung**
Um diese Aktionen über die API auszuführen, müssen Sie sich mit AWS Anmeldeinformationen und nicht mit einem CloudWatch Logs-API-Schlüssel authentifizieren.
Sie können auch die folgenden IAM-API-Operationen verwenden, um kompromittierte Schlüssel zu verwalten:
+ [ResetServiceSpecificCredential](https://docs.aws.amazon.com/IAM/latest/APIReference/API_ResetServiceSpecificCredential.html)— Setzen Sie den Schlüssel zurück, um ein neues Passwort zu generieren, ohne die Anmeldeinformationen zu löschen. Der Schlüssel darf nicht abgelaufen sein.
## Bewährte Sicherheitsmethoden für API-Schlüssel
Folgen Sie diesen bewährten Methoden, um Ihre CloudWatch Logs-API-Schlüssel zu schützen:
+ **Betten Sie niemals API-Schlüssel in den Quellcode ein.** Codieren Sie API-Schlüssel nicht fest im Anwendungscode und übergeben Sie sie nicht an Versionskontrollsysteme. Wenn ein Schlüssel versehentlich in ein öffentliches Repository übertragen wird, wird er möglicherweise AWS durch automatisiertes Scannen gekennzeichnet. Sie sollten den Schlüssel sofort wechseln.
+ **Verwenden Sie einen Secrets-Manager.** Speichern Sie API-Schlüssel in [AWS Secrets Manager](https://docs.aws.amazon.com/secretsmanager/latest/userguide/intro.html)oder einer gleichwertigen Lösung zur Verwaltung von Geheimnissen. Dies ermöglicht eine zentrale Zugriffskontrolle, Auditprotokollierung und automatisierte Rotation.
+ **Legen Sie für alle Schlüssel ein Ablaufdatum fest.** Geben Sie beim Erstellen von API-Schlüsseln immer einen `--credential-age-days` Wert an. Verwenden Sie den `iam:ServiceSpecificCredentialAgeDays` IAM-Bedingungsschlüssel, um eine maximale Gültigkeitsdauer von Schlüsseln in Ihrer Organisation durchzusetzen. Ein Beispiel finden Sie unter [Erlauben Sie die Erstellung von CloudWatch Logs-Schlüsseln nur, wenn sie innerhalb von 90 Tagen ablaufen](#CWL_HTTP_Endpoints_Allow_Expire_90).
+ **Wenden Sie Berechtigungen mit den geringsten Rechten an.** Beschränken Sie die Berechtigungen des IAM-Benutzers nur auf die erforderlichen Protokollgruppen und Aktionen. Verwenden Sie die Managed [CloudWatchLogsAPIKeyAccess-Richtlinie](https://docs.aws.amazon.com/aws-managed-policy/latest/reference/CloudWatchLogsAPIKeyAccess.html) als Ausgangspunkt und schränken Sie sie bei Bedarf weiter ein.
+ **Aktivieren Sie die CloudTrail Protokollierung.** Überwachen Sie die Verwendung von API-Schlüsseln, indem Sie CloudTrail Datenereignisse für aktivieren`AWS::Logs::LogGroupAuthorization`. Siehe [Protokollierung der Verwendung von API-Schlüsseln mit CloudTrail](#CWL_HTTP_Endpoints_CloudTrail_Logging).
+ **Überwachen Sie mit IAM Access Analyzer.** Verwenden Sie [IAM Access Analyzer](https://docs.aws.amazon.com/IAM/latest/UserGuide/what-is-access-analyzer.html), um ungenutzte Anmeldeinformationen und übermäßig freizügige Richtlinien im Zusammenhang mit Ihren API-Schlüssel-IAM-Benutzern zu identifizieren.
+ **Wechseln Sie die Schlüssel regelmäßig.** Legen Sie einen Rotationsplan fest und folgen Sie dem unter beschriebenen Verfahren[Rotierende API-Schlüssel](#CWL_HTTP_Endpoints_Rotating_Keys).
## Protokollierung der Verwendung von API-Schlüsseln mit CloudTrail
Sie können AWS CloudTrail es verwenden, um Datenereignisse für die Verwendung von CloudWatch Logs API-Schlüsseln zu protokollieren. CloudWatch Logs sendet `AWS::Logs::LogGroupAuthorization` Datenereignisse für `CallWithBearerToken` Aufrufe aus, sodass Sie überprüfen können, wann und wie API-Schlüssel zum Senden von Protokollen verwendet werden.
So aktivieren Sie die CloudTrail Protokollierung für die Verwendung von CloudWatch Logs-API-Schlüsseln:
**Anmerkung**
Der S3-Bucket, den Sie für den Trail angeben, muss über eine Bucket-Richtlinie verfügen, die CloudTrail das Schreiben von Protokolldateien in ihn ermöglicht. Weitere Informationen finden Sie unter [Amazon S3 S3-Bucket-Richtlinie für CloudTrail](https://docs.aws.amazon.com/awscloudtrail/latest/userguide/create-s3-bucket-policy-for-cloudtrail.html).
1. Erstellen Sie einen Trail:
```
aws cloudtrail create-trail \
--name cloudwatch-logs-api-key-audit \
--s3-bucket-name my-cloudtrail-bucket \
--region us-east-1
```
1. Konfigurieren Sie erweiterte Event-Selektoren, um Logs zu CloudWatch protokollieren, Gruppenautorisierungsereignisse zu protokollieren:
```
aws cloudtrail put-event-selectors \
--region us-east-1 \
--trail-name cloudwatch-logs-api-key-audit \
--advanced-event-selectors '[{
"Name": "CloudWatch Logs API key authorization events",
"FieldSelectors": [
{ "Field": "eventCategory", "Equals": ["Data"] },
{ "Field": "resources.type", "Equals": ["AWS::Logs::LogGroupAuthorization"] }
]
}]'
```
1. Starten Sie die Trailprotokollierung:
```
aws cloudtrail start-logging \
--name cloudwatch-logs-api-key-audit \
--region us-east-1
```
# Senden von Protokollen über den OTLP-Endpunkt (OpenTelemetry Logs)
Der OpenTelemetry Logs-Endpunkt (`/v1/logs`) akzeptiert OpenTelemetry Protokolldaten des Protokolls (OTLP) entweder in JSON- oder Protobuf-Kodierung. Ausführliche Informationen zum OTLP-Endpunkt, einschließlich Konfiguration und Verwendung, finden [Sie unter Metriken und Traces an mit senden](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/CloudWatch-OTLPEndpoint.html). CloudWatch OpenTelemetry
Wenn Sie die Bearer-Token-Authentifizierung verwenden, schließen Sie die Einrichtungsschritte unter ab, [Einrichtung der Bearer-Token-Authentifizierung](CWL_HTTP_Endpoints_BearerTokenAuth.md) bevor Sie fortfahren.
## Anforderungsformat
+ Methode: `POST`
+ Inhaltstyp: oder `application/json` `application/x-protobuf`
+ Protokollgruppe: nur `x-aws-log-group` Header (Abfrageparameter nicht unterstützt)
+ Protokollstream: `x-aws-log-stream` Header
## Beispielanforderung
```
curl -X POST "https://logs..amazonaws.com/v1/logs" \
-H "Authorization: Bearer ACWL" \
-H "Content-Type: application/json" \
-H "x-aws-log-group: MyLogGroup" \
-H "x-aws-log-stream: MyLogStream" \
-d '{
"resourceLogs": [
{
"resource": {
"attributes": [
{
"key": "service.name",
"value": { "stringValue": "my-service" }
}
]
},
"scopeLogs": [
{
"scope": {
"name": "my-library",
"version": "1.0.0"
},
"logRecords": [
{
"timeUnixNano": "1741900000000000000",
"severityNumber": 9,
"severityText": "INFO",
"body": {
"stringValue": "User logged in successfully"
},
"attributes": [
{
"key": "user.id",
"value": { "stringValue": "12345" }
}
]
}
]
}
]
}
]
}'
```
## Antworten
**Erfolgreich (alle Ereignisse wurden akzeptiert):**
```
HTTP 200 OK
{}
```
**Teilweise erfolgreich (einige Ereignisse wurden abgelehnt):**
```
{
"partialSuccess": {
"rejectedLogRecords": 5,
"errorMessage": "{\"tooOldLogEventCount\": 3, \"tooNewLogEventCount\": 1, \"expiredLogEventCount\": 1}"
}
}
```
Wenn die Anfrage Content-Type lautet`application/x-protobuf`, wird die Antwort als serialisierte `ExportLogsServiceResponse` Protobuf-Nachricht mit denselben Feldern zurückgegeben.
## OTLP-spezifisches Verhalten
Die folgenden Verhaltensweisen sind spezifisch für den OTLP-Endpunkt und nicht auf den anderen HTTP-Ingestion-Endpunkten vorhanden:
+ **Retry-After-Header** — In den Antworten 503 und 429 enthalten und gibt an, wann der Client es erneut versuchen sollte.
# Senden von Protokollen über den HLC-Endpunkt (HLC Logs)
Der HLC Logs-Endpunkt (`/services/collector/event`) basiert auf dem HTTP Log Collector (HLC) -Format.
Wenn Sie die Bearer-Token-Authentifizierung verwenden, schließen Sie die Einrichtungsschritte unter ab, bevor Sie fortfahren. [Einrichtung der Bearer-Token-Authentifizierung](CWL_HTTP_Endpoints_BearerTokenAuth.md)
## Eingabemodi
Jedes Ereignis ist ein JSON-Objekt mit einem erforderlichen `"event"` Feld. Optionale Metadatenfelder: `"time"``"host"`,`"source"`,,`"sourcetype"`,`"index"`.
**Einzelnes Ereignis:**
```
{"event":"Hello world!","time":1486683865.0}
```
**JSON-Array von Ereignissen:**
```
[
{"event":"msg1","time":1486683865.0},
{"event":"msg2","time":1486683866.0}
]
```
**Verkettete/gebündelte Ereignisse (kein Array-Wrapper):**
```
{"event":"msg1","time":1486683865.0}{"event":"msg2","time":1486683866.0}
```
## Feld „Ereignis“ (erforderlich)
Das `"event"` Feld ist ein Pflichtfeld. Sein Wert kann ein beliebiger JSON-Typ sein:
```
{"event":"a string message"}
{"event":{"message":"structured data","severity":"INFO"}}
{"event":42}
{"event":true}
```
Objekte ohne `"event"` Feld werden stillschweigend übersprungen:
```
{"message":"this is skipped — no event field"}
```
## Zeitfeld (optional)
Das `"time"` Feld wird in Epochensekunden (nicht in Millisekunden) angegeben, mit optionaler Dezimalzahl für eine Genauigkeit unter einer Sekunde.
| Format | Beispiel | Interpretiert als |
| --- | --- | --- |
| Gleitkommazahl | "time":1486683865.500 | 1486683865500 ms |
| Ganzzahl | "time":1486683865 | 1486683865000 ms |
| Zeichenfolge (Float) | "time":"1486683865.500" | 1486683865500 ms |
| Zeichenfolge (Ganzzahl) | "time":"1486683865" | 1486683865000 ms |
| Fehlen | (kein Zeitfeld) | Aktuelle Uhrzeit des Servers |
| Ungültig | "time":"invalid" | Aktuelle Uhrzeit des Servers |
## Content-Type
Nur `application/json` wird akzeptiert.
## Akzeptierte JSON-Werttypen
| Typ der obersten Ebene | Behavior |
| --- | --- |
| Objekt mit "event" | Accepted (Akzeptiert) |
| Objekt ohne "event" | Übersprungen |
| Array von -Objekten. | Jedes Element wird einzeln verarbeitet |
| Verkettete Objekte | Jedes Objekt wird einzeln verarbeitet |
| Primitiv (Zeichenfolge, Zahl, Boolean, Null) | Übersprungen |
## Endpunkt-Format
Die URL des HLC-Endpunkts folgt diesem Format:
```
https://logs..amazonaws.com/services/collector/event?logGroup=&logStream=[&entityName=&entityEnvironment=]
```
**Erforderliche Parameter:**
+ ``— AWS Region (zum Beispiel`us-east-1`,`eu-west-1`)
+ `logGroup`— URL-codierter Name der Protokollgruppe
+ `logStream`— URL-codierter Name des Protokolldatenstroms
**Optionale Parameter:**
Sie können Ihre Protokollereignisse optional einer `Service` Entität zuordnen, indem Sie die folgenden Abfrageparameter angeben. Da es sich bei den über den HLC-Endpunkt gesendeten Protokollen um benutzerdefinierte Telemetrie handelt, werden sie nicht automatisch einer Entität zugeordnet. Durch die Angabe dieser Parameter erstellt CloudWatch Logs eine Entität mit der `KeyAttributes.Type` Einstellung auf `Service` und ordnet sie Ihren Protokollereignissen zu. Auf diese Weise kann die **zugehörige CloudWatch Explore-Funktion** diese Protokolle mit anderen Telemetriedaten (Metriken, Traces und Logs) desselben Dienstes korrelieren, was die Fehlerbehebung und Überwachung Ihrer Anwendungen bei verschiedenen Signaltypen erleichtert. Weitere Informationen zu Entitäten und verwandter Telemetrie finden Sie unter [Hinzufügen verwandter Informationen zur](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/adding-your-own-related-telemetry.html) benutzerdefinierten Telemetrie.
+ `entityName`— Der Name der Dienstentität, die den Protokollereignissen zugeordnet werden soll. Dieser Wert wird als Entität gespeichert `KeyAttributes.Name` (z. B. `my-application` oder`api.myservice.com`).
+ `entityEnvironment`— Die Umgebung, in der der Dienst gehostet wird oder zu der er gehört. Dieser Wert wird als Entität gespeichert `KeyAttributes.Environment` (z. B.`production`,`ec2:default`, oder`eks:my-cluster/default`).
## Anforderungsformat
Senden Sie Protokolle mithilfe von HTTP POST mit den folgenden Headern und dem folgenden Hauptteil:
**Kopfzeilen:**
+ `Authorization: Bearer `
+ `Content-Type: application/json`
**Körperformat:**
Der Hauptteil der Anfrage sollte im JSON-Format mit einer Reihe von Ereignissen vorliegen:
```
{
"event": [
{
"time": 1730141374.001,
"event": "Application started successfully",
"host": "web-server-1",
"source": "application.log",
"severity": "info"
},
{
"time": 1730141374.457,
"event": "User login successful",
"host": "web-server-1",
"source": "auth.log",
"user": "john.doe"
}
]
}
```
**Feldbeschreibungen:**
+ `time`— Zeitstempel der Unix-Epoche in Sekunden, mit optionaler Dezimalzahl für eine Genauigkeit unter einer Sekunde (optional)
+ `event`— Die Protokollnachricht oder die Ereignisdaten (erforderlich)
+ `host`— Hostname oder Kennung der Quelle (optional)
+ `source`— Kennung der Protokollquelle (optional)
Zusätzliche benutzerdefinierte Felder können nach Bedarf hinzugefügt werden.
## Beispielanforderung
```
curl -X POST "https://logs..amazonaws.com/services/collector/event?logGroup=MyLogGroup&logStream=MyStream" \
-H "Authorization: Bearer ACWL" \
-H "Content-Type: application/json" \
-d '{"event":{"message":"User logged in","user_id":"u-123"},"time":1486683865.0,"host":"web-01","source":"auth-service"}'
```
## Best Practices
### Ereignisse stapeln
Für mehr Leistung und Effizienz:
+ Wenn möglich, mehrere Ereignisse in einer einzigen Anfrage bündeln
+ Empfohlene Batchgröße: 10—100 Ereignisse pro Anfrage
+ Maximale Anforderungsgröße: 1 MB
### Fehlerbehandlung
Implementieren Sie die richtige Fehlerbehandlung in Ihrer Anwendung. Allgemeine HTTP-Statuscodes:
+ `200 OK`— Protokolle wurden erfolgreich aufgenommen
+ `400 Bad Request`— Ungültiges Anforderungsformat oder ungültige Parameter
+ `401 Unauthorized`— Ungültiges oder abgelaufenes Inhaber-Token
+ `403 Forbidden`— Unzureichende Berechtigungen
+ `404 Not Found`— Protokollgruppe oder Stream existiert nicht
+ `429 Too Many Requests`— Ratenlimit überschritten
+ `500 Internal Server Error`— Servicefehler (erneuter Versuch mit exponentiellem Backoff)
## Einschränkungen
+ Maximale Ereignisgröße: 256 KB pro Ereignis
+ Maximale Anforderungsgröße: 1 MB
+ Maximale Anzahl von Ereignissen pro Anfrage: 10.000
+ Die Namen der Protokollgruppen müssen den Benennungskonventionen für CloudWatch Protokolle entsprechen
+ Wenn die Bearer-Token-Authentifizierung verwendet wird, muss die Bearer-Token-Authentifizierung für die Protokollgruppe aktiviert sein.
# Senden von Protokollen mithilfe des NDJSON-Endpunkts (ND-JSON-Protokolle)
Der Endpunkt ND-JSON Logs (`/ingest/bulk`) akzeptiert Protokolle im [NDJSON-Format](https://github.com/ndjson/ndjson-spec) (Newline Delimited JSON). Jede Zeile enthält genau einen JSON-Wert, getrennt durch Zeilenumbruchzeichen.
Wenn Sie die Bearer-Token-Authentifizierung verwenden, schließen Sie die Einrichtungsschritte unter ab, [Einrichtung der Bearer-Token-Authentifizierung](CWL_HTTP_Endpoints_BearerTokenAuth.md) bevor Sie fortfahren.
## Anforderungsformat
Senden Sie einen JSON-Wert pro Zeile, getrennt durch `\n` (LF) oder `\r\n` (CRLF). Leere Zeilen werden stillschweigend ignoriert.
```
{"timestamp":1771007942000,"message":"event one","level":"INFO"}
{"timestamp":1771007943000,"message":"event two","level":"ERROR"}
{"timestamp":1771007944000,"message":"event three","level":"DEBUG"}
```
`application/json`Sowohl als auch `application/x-ndjson` werden als Content-Type akzeptiert.
## Akzeptierte JSON-Werttypen
Gemäß der NDJSON-Spezifikation (RFC 8259) wird jeder gültige JSON-Wert in jeder Zeile akzeptiert.
**JSON-Objekte (am häufigsten):**
```
{"timestamp":1771007942000,"message":"User logged in","service":"auth"}
{"timestamp":1771007943000,"error":"Connection timeout","service":"api"}
```
**JSON-Arrays (auf einzelne Ereignisse reduziert):**
```
[{"timestamp":1000,"message":"a"},{"timestamp":2000,"message":"b"}]
```
Diese einzelne Zeile erzeugt 2 Ereignisse. Jedes Array-Element wird zu einem separaten Protokollereignis.
**Primitive Werte:**
```
"a plain string log message"
42
true
null
```
Jedes Primitiv wird zu einem eigenen Ereignis mit dem aktuellen Zeitstempel des Servers.
**Gemischte Typen:**
```
{"timestamp":1771007942000,"message":"structured event"}
"unstructured string message"
42
{"timestamp":1771007943000,"error":"something failed"}
```
Alle 4 Zeilen werden als gültige Ereignisse akzeptiert.
| Inhalt der Zeile | Behavior |
| --- | --- |
| JSON-Objekt | Akzeptiert, Zeitstempel extrahiert, falls vorhanden |
| JSON-Array | Reduziert — jedes Element wird zu einem separaten Ereignis |
| Leeres Array [] | Akzeptiert, erzeugt 0 Ereignisse |
| JSON-Zeichenfolge | Als Ereignisnachricht akzeptiert |
| JSON-Nummer | Als Ereignisnachricht akzeptiert |
| Boolescher JSON-Wert | Als Ereignisnachricht akzeptiert |
| JSON ist null | Als Ereignisnachricht akzeptiert |
| Ungültige JSON | Übersprungen (gezählt, Verarbeitung wird fortgesetzt) |
| Leere Zeile | Ignoriert (wird nicht als übersprungen gezählt) |
## Zeitstempel-Feld
Das `"timestamp"` Feld ist in Epochen-Millisekunden (nicht Sekunden) angegeben.
| Format | Beispiel | Interpretiert als |
| --- | --- | --- |
| Numerisch (Millis) | "timestamp":1771007942000 | 1771007942000 ms |
| Fehlen | (kein Zeitstempelfeld) | Aktuelle Uhrzeit des Servers |
| Nicht numerisch | "timestamp":"invalid" | Aktuelle Uhrzeit des Servers |
| Zeile, die kein Objekt ist | "hello", 42, true | Aktuelle Uhrzeit des Servers |
## Ungültige Zeilen
Zeilen, die kein gültiges JSON-Format sind, werden automatisch übersprungen und gezählt. Die Verarbeitung wird mit der nächsten Zeile fortgesetzt.
```
{"message":"valid event"}
this is not valid json
{"message":"another valid event"}
```
Ergebnis: 2 Ereignisse wurden aufgenommen, 1 wurde übersprungen. Gibt `HTTP 200` zurück.
Wenn alle Zeilen ungültig sind, wird mit zurückgegeben`HTTP 400`. `"All events were invalid"`
## Beispielanforderung
```
curl -X POST "https://logs..amazonaws.com/ingest/bulk?logGroup=MyLogGroup&logStream=MyStream" \
-H "Authorization: Bearer ACWL" \
-H "Content-Type: application/x-ndjson" \
-d '{"timestamp":1771007942000,"message":"User logged in","level":"INFO"}
{"timestamp":1771007943000,"message":"Query took 42ms","level":"DEBUG"}
{"timestamp":1771007944000,"error":"Connection refused","level":"ERROR"}'
```
## Antworten
**Erfolgreich (alle Ereignisse wurden akzeptiert):**
```
HTTP 200 OK
{}
```
**Teilweise erfolgreich (einige Ereignisse wurden abgelehnt):**
```
{
"partialSuccess": {
"rejectedLogRecords": 5,
"errorMessage": "{\"tooOldLogEventCount\": 3, \"tooNewLogEventCount\": 1, \"expiredLogEventCount\": 1}"
}
}
```
Das `rejectedLogRecords` Feld gibt die Gesamtzahl der abgelehnten Ereignisse an. Das `errorMessage` Feld enthält eine JSON-kodierte Aufschlüsselung nach Ablehnungsgründen:
+ `tooOldLogEventCount`— Ereignisse, deren Zeitstempel älter als der Aufbewahrungszeitraum sind
+ `tooNewLogEventCount`— Ereignisse mit Zeitstempeln, die zu weit in der future liegen
+ `expiredLogEventCount`— Ereignisse, die während der Verarbeitung abgelaufen sind
## Best Practices
### Ereignisse werden gebündelt
Für mehr Leistung und Effizienz:
+ Wenn möglich, mehrere Ereignisse in einer einzigen Anfrage bündeln
+ Empfohlene Batchgröße: 10—100 Ereignisse pro Anfrage
+ Maximale Anforderungsgröße: 1 MB
### Fehlerbehandlung
Implementieren Sie die richtige Fehlerbehandlung in Ihrer Anwendung. Allgemeine HTTP-Statuscodes:
+ `200 OK`— Protokolle wurden erfolgreich aufgenommen
+ `400 Bad Request`— Ungültiges Anforderungsformat oder ungültige Parameter
+ `401 Unauthorized`— Ungültiges oder abgelaufenes Trägertoken
+ `403 Forbidden`— Unzureichende Berechtigungen
+ `404 Not Found`— Protokollgruppe oder Stream existiert nicht
+ `429 Too Many Requests`— Ratenlimit überschritten
+ `500 Internal Server Error`— Servicefehler (erneuter Versuch mit exponentiellem Backoff)
## Einschränkungen
+ Maximale Ereignisgröße: 256 KB pro Ereignis
+ Maximale Anforderungsgröße: 1 MB
+ Maximale Anzahl von Ereignissen pro Anfrage: 10.000
+ Die Namen der Protokollgruppen müssen den Benennungskonventionen für CloudWatch Protokolle entsprechen
+ Wenn die Bearer-Token-Authentifizierung verwendet wird, muss die Bearer-Token-Authentifizierung für die Protokollgruppe aktiviert sein.
# Senden von Protokollen mithilfe des strukturierten JSON-Endpunkts (Strukturierte JSON-Protokolle)
Der Endpunkt Structured JSON Logs (`/ingest/json`) akzeptiert Standard-JSON — entweder ein einzelnes JSON-Objekt oder ein JSON-Array von Objekten. Dieser Endpunkt ist für strukturierte Protokolldaten konzipiert, bei denen jedes Ereignis ein JSON-Objekt ist.
Wenn Sie die Bearer-Token-Authentifizierung verwenden, schließen Sie die Einrichtungsschritte unter ab, [Einrichtung der Bearer-Token-Authentifizierung](CWL_HTTP_Endpoints_BearerTokenAuth.md) bevor Sie fortfahren.
## Anforderungsformat
`application/json`Wird nur als Content-Type akzeptiert.
**Einzelnes JSON-Objekt:**
```
{"timestamp":1771007942000,"message":"single event","level":"INFO"}
```
**JSON-Array von Objekten:**
```
[
{"timestamp":1771007942000,"message":"event one","level":"INFO"},
{"timestamp":1771007943000,"message":"event two","level":"ERROR"}
]
```
## Akzeptierte JSON-Werttypen
Dieser Endpunkt ist streng — nur JSON-Objekte werden als Ereignisse akzeptiert.
| Input | Behavior |
| --- | --- |
| Einzelnes JSON-Objekt | Als ein Ereignis akzeptiert |
| JSON-Array von Objekten | Jedes Objekt wird zu einem separaten Ereignis |
| Leeres Array [] | Akzeptiert, erzeugt 0 Ereignisse |
| Kein Objekt im Array (Zeichenfolge, Zahl usw.) | Übersprungen |
| Primitiv der obersten Ebene ("hello",) 42 | Übersprungen |
| Verkettete Objekte \$1...\$1\$1...\$1 | Nur das erste Objekt wurde analysiert |
**Beispiel — Array mit gemischten Typen:**
```
[
{"timestamp":1771007942000,"message":"valid object"},
"just a string",
42,
{"timestamp":1771007943000,"message":"another valid object"}
]
```
Ergebnis: 2 Ereignisse wurden aufgenommen (die Objekte), 2 übersprungen (die Zeichenfolge und die Zahl).
## Feld „Zeitstempel“
Das `"timestamp"` Feld wird in Epochen-Millisekunden angegeben, genau wie der NDJSON-Endpunkt.
| Format | Beispiel | Interpretiert als |
| --- | --- | --- |
| Numerisch (Millis) | "timestamp":1771007942000 | 1771007942000 ms |
| Fehlen | (kein Zeitstempelfeld) | Aktuelle Uhrzeit des Servers |
| Nicht numerisch | "timestamp":"invalid" | Aktuelle Uhrzeit des Servers |
## Beispielanforderung
```
curl -X POST "https://logs..amazonaws.com/ingest/json?logGroup=MyLogGroup&logStream=MyStream" \
-H "Authorization: Bearer ACWL" \
-H "Content-Type: application/json" \
-d '[{"timestamp":1771007942000,"message":"User logged in","user_id":"u-123"},{"timestamp":1771007943000,"message":"Order placed","order_id":"o-456"}]'
```
## Antworten
**Erfolgreich (alle Ereignisse wurden akzeptiert):**
```
HTTP 200 OK
{}
```
**Teilweise erfolgreich (einige Ereignisse wurden abgelehnt):**
```
{
"partialSuccess": {
"rejectedLogRecords": 5,
"errorMessage": "{\"tooOldLogEventCount\": 3, \"tooNewLogEventCount\": 1, \"expiredLogEventCount\": 1}"
}
}
```
Das `rejectedLogRecords` Feld gibt die Gesamtzahl der abgelehnten Ereignisse an. Das `errorMessage` Feld enthält eine JSON-kodierte Aufschlüsselung nach Ablehnungsgründen:
+ `tooOldLogEventCount`— Ereignisse, deren Zeitstempel älter als der Aufbewahrungszeitraum sind
+ `tooNewLogEventCount`— Ereignisse mit Zeitstempeln, die zu weit in der future liegen
+ `expiredLogEventCount`— Ereignisse, die während der Verarbeitung abgelaufen sind
## Best Practices
### Ereignisse werden gebündelt
Für mehr Leistung und Effizienz:
+ Wenn möglich, mehrere Ereignisse in einer einzigen Anfrage bündeln
+ Empfohlene Batchgröße: 10—100 Ereignisse pro Anfrage
+ Maximale Anforderungsgröße: 1 MB
### Fehlerbehandlung
Implementieren Sie die richtige Fehlerbehandlung in Ihrer Anwendung. Allgemeine HTTP-Statuscodes:
+ `200 OK`— Protokolle wurden erfolgreich aufgenommen
+ `400 Bad Request`— Ungültiges Anforderungsformat oder ungültige Parameter
+ `401 Unauthorized`— Ungültiges oder abgelaufenes Trägertoken
+ `403 Forbidden`— Unzureichende Berechtigungen
+ `404 Not Found`— Protokollgruppe oder Stream existiert nicht
+ `429 Too Many Requests`— Ratenlimit überschritten
+ `500 Internal Server Error`— Servicefehler (erneuter Versuch mit exponentiellem Backoff)
## Einschränkungen
+ Maximale Ereignisgröße: 256 KB pro Ereignis
+ Maximale Anforderungsgröße: 1 MB
+ Maximale Anzahl von Ereignissen pro Anfrage: 10.000
+ Die Namen der Protokollgruppen müssen den Benennungskonventionen für CloudWatch Protokolle entsprechen
+ Wenn die Bearer-Token-Authentifizierung verwendet wird, muss die Bearer-Token-Authentifizierung für die Protokollgruppe aktiviert sein.
## Vergleich der Endpunkte für die HTTP-Erfassung
| Feature | HLC-Protokolle | ND-JSON-Protokolle | Strukturierte JSON-Protokolle | OpenTelemetry Logs |
| --- | --- | --- | --- | --- |
| Pfad | /services/collector/event | /ingest/bulk | /ingest/json | /v1/logs |
| Content-Type | application/json | application/json oder application/x-ndjson | application/json | application/json oder application/x-protobuf |
| Feld „Zeitstempel“ | "time"(Sekunden) | "timestamp"(Millisekunden) | "timestamp"(Millisekunden) | "timeUnixNano"(Nanosekunden) |
| Pflichtfelder | "event" | Keine | Keine | OTLP-Struktur () "resourceLogs" |
| Teilweise erfolgreiche Antwort | Nein | Ja | Ja | Ja |
| Unterstützung von Abfrageparametern | Ja | Ja | Ja | Nein (nur Kopfzeilen) |
| Metadaten der Entität | Ja | Ja | Ja | Nein |
| Akzeptiert Primitive | Nein | Ja | Nein | Nein |
| Zeilenbasiertes Parsen | Nein | Ja | Nein | Nein |
| Protobuf-Unterstützung | Nein | Nein | Nein | Ja |
| Header „Nach einem erneuten Versuch“ | Nein | Nein | Nein | Ja |
## Einen Endpunkt auswählen
+ **Verwenden Sie das HLC-Format?** Verwenden Sie HLC-Protokolle. Ihre vorhandenen HLC-Payloads funktionieren mit minimalen Änderungen.
+ **Protokolle streamen? line-by-line** Verwenden Sie ND-JSON-Protokolle. Am besten für Protokoll-Pipelines geeignet, die ein Ereignis pro Zeile ausgeben. Am flexibelsten — akzeptiert jeden JSON-Wertetyp.
+ **Strukturierte JSON-Nutzlasten senden?** Verwenden Sie strukturierte JSON-Protokolle. Am besten für Anwendungen geeignet, die wohlgeformte JSON-Objekte oder -Arrays erzeugen.
+ **Benutzen Sie es bereits? OpenTelemetry** Verwenden Sie OpenTelemetry Logs. Akzeptiert das OTLP-JSON- oder Protobuf-Format und unterstützt teilweise erfolgreiche Antworten mit Wiederholungssemantik.