Las traducciones son generadas a través de traducción automática. En caso de conflicto entre la traducción y la version original de inglés, prevalecerá la version en inglés.
# Ingesta de registros a través de puntos finales HTTP
Amazon CloudWatch Logs proporciona puntos de enlace HTTP que le permiten enviar registros directamente a CloudWatch Logs mediante simples solicitudes HTTP POST. Estos puntos de enlace admiten tanto la autenticación mediante SigV4 como la autenticación mediante token portador.
**importante**
Recomendamos utilizar la autenticación SigV4 para todas las cargas de trabajo de producción en las que sea posible la integración del SDK AWS . SigV4 utiliza credenciales a corto plazo y proporciona la mejor postura de seguridad. La autenticación con token portador (clave de API) está pensada para situaciones en las que SigV4 no es factible, como los reenviadores de registros de terceros que no admiten la integración con el SDK. AWS Para obtener más información, consulte [Alternativas a las claves de acceso a largo plazo](https://docs.aws.amazon.com/IAM/latest/UserGuide/best-practices.html#bp-workloads-use-roles) en la Guía del usuario de *IAM*.
CloudWatch Logs admite los siguientes puntos finales de ingesta de HTTP:
| Punto de conexión | Ruta | Contenido-Tipo | Formato |
| --- | --- | --- | --- |
| [OpenTelemetry Logs](CWL_HTTP_Endpoints_OTLP.md) | /v1/logs | application/json o application/x-protobuf | OTTP, JSON o Protobug |
| [HLC Logs](CWL_HLC_Endpoint.md) | /services/collector/event | application/json | Formato HLC |
| [ND-JSON Logs](CWL_HTTP_Endpoints_NDJSON.md) | /ingest/bulk | application/json o application/x-ndjson | JSON delimitado por saltos de línea |
| [Structured JSON Logs](CWL_HTTP_Endpoints_StructuredJSON.md) | /ingest/json | application/json | Objeto o matriz JSON |
## Comportamiento común
Todos los puntos finales de ingestión de HTTP comparten el siguiente comportamiento:
**Autenticación**
Todos los puntos finales admiten la autenticación mediante SigV4 y la autenticación mediante token portador:
+ **SigV4 (recomendado)**: AWS firma estándar, versión 4. Utilice SigV4 siempre que su aplicación o infraestructura sea compatible con el AWS SDK o pueda firmar solicitudes. SigV4 utiliza credenciales de corta duración y es el método de autenticación más seguro.
+ **Token de portador**: usa el `Authorization: Bearer ` encabezado.
+ El token debe ser un token portador de la ACWL válido. Para obtener instrucciones de configuración, consulte. [Configuración de la autenticación por token de portador](CWL_HTTP_Endpoints_BearerTokenAuth.md)
+ Requiere los permisos `logs:PutLogEvents` e `logs:CallWithBearerToken` IAM.
**Grupo de registros y flujo de registros**
+ Se proporciona mediante encabezados: `x-aws-log-group` y `x-aws-log-stream`
+ Los parámetros de consulta también `?logGroup=&logStream=` se admiten en todos los puntos finales excepto en OTLP.
+ No puede utilizar tanto los parámetros de consulta como los encabezados para el mismo parámetro.
+ Se requieren tanto el grupo de registros como el flujo de registros.
**Respuesta**
+ Éxito: `HTTP 200` con cuerpo `{}`
+ Errores de validación: `HTTP 400`
+ Fallos de autenticación: `HTTP 401`
# Configuración de la autenticación por token de portador
Antes de poder enviar los registros mediante la autenticación por token portador con cualquiera de los puntos de enlace de ingestión de HTTP, debe:
+ Cree un usuario de IAM con permisos de registro CloudWatch
+ Genere credenciales específicas del servicio (token de portador)
+ Cree un grupo de registros y un flujo de registros
+ Habilite la autenticación por token portador en el grupo de registros
**importante**
Siempre que sea posible, recomendamos utilizar la autenticación SigV4 con credenciales a corto plazo para todas las cargas de trabajo. SigV4 proporciona la postura de seguridad más sólida. Restrinja el uso de claves de API (símbolos portadores) a situaciones en las que la autenticación basada en credenciales a corto plazo no sea factible. Cuando esté preparado para incorporar los CloudWatch registros en aplicaciones con mayores requisitos de seguridad, debería cambiar a credenciales de corta duración. Para obtener más información, consulte [Alternativas a las claves de acceso a largo plazo](https://docs.aws.amazon.com/IAM/latest/UserGuide/best-practices.html#bp-workloads-use-roles) en la *Guía del usuario de IAM*.
## Opción 1: Inicio rápido a utilizar la consola AWS
La consola AWS de administración proporciona un flujo de trabajo simplificado para generar claves de API para el acceso a los puntos de conexión HTTP.
**Para configurar el acceso al punto final HTTP mediante la consola**
1. Inicie sesión en la consola AWS de administración.
1. Vaya a **CloudWatch**> **Configuración** > **Registros**.
1. En la sección Claves de API, selecciona **Generar clave de API**.
1. Para **Expiración de la clave de API**, realice una de las siguientes acciones:
+ Selecciona una duración de caducidad de la clave de API de **1**, **5**, **30**, **90** o **365** días.
+ Elija **Duración personalizada** para especificar una fecha de expiración personalizada de la clave de API.
+ Selecciona **Nunca caduca** (no se recomienda).
1. Seleccione **Generar clave de API**.
La consola automáticamente:
+ Crea un nuevo usuario de IAM con los permisos adecuados
+ Adjunta la política de [CloudWatchLogsAPIKeyacceso](https://docs.aws.amazon.com/aws-managed-policy/latest/reference/CloudWatchLogsAPIKeyAccess.html) gestionado (incluye `logs:PutLogEvents` y `logs:CallWithBearerToken` permisos)
+ Genera credenciales específicas del servicio (clave de API)
1. Copie y guarde de forma segura las credenciales mostradas:
+ ID **de clave de API (ID** de credencial específica del servicio)
+ **Secreto de clave de API** (token de portador)
**importante**
Guarde el secreto de la clave de la API inmediatamente. no la puede recuperar en otro momento. Si la pierdes, tendrás que generar una nueva clave de API.
1. Crea el grupo de registros y el flujo de registros donde se almacenarán tus registros:
```
# 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. Habilite la autenticación por token de portador en el grupo de registros:
```
aws logs put-bearer-token-authentication \
--log-group-identifier /aws/hlc-logs/my-application \
--bearer-token-authentication-enabled \
--region us-east-1
```
Verifique la configuración:
```
aws logs describe-log-groups \
--log-group-name-prefix /aws/hlc-logs/my-application \
--region us-east-1
```
**Permisos incluidos:** el usuario de IAM creado automáticamente tendrá los siguientes permisos:
+ `logs:PutLogEvents`— Enviar los eventos del registro a CloudWatch los registros
+ `logs:CallWithBearerToken`— Autenticarse con un token de portador
+ `kms:Describe*`,`kms:GenerateDataKey*`, `kms:Decrypt` — Acceda a grupos de registros cifrados con KMS (con la condición de que se limite al servicio de registros)
## Opción 2: configuración manual
Si prefiere tener más control sobre la configuración de IAM o necesita personalizar los permisos, puede configurar el acceso al punto final HTTP de forma manual.
### Paso 1: Crear un usuario de IAM
Cree un usuario de IAM que se utilizará para la ingesta de registros:
1. Inicie sesión en la consola de AWS administración y vaya a IAM.
1. En el panel de navegación izquierdo, elija **Usuarios**.
1. Seleccione la opción **Crear un usuario**.
1. Introduzca un nombre de usuario (por ejemplo,`cloudwatch-logs-hlc-user`).
1. Elija **Siguiente**.
1. Adjunte una de las siguientes políticas de IAM:
**Opción A: utilizar la política gestionada (recomendada)**
Adjunte la política de [CloudWatchLogsAPIKeyacceso](https://docs.aws.amazon.com/aws-managed-policy/latest/reference/CloudWatchLogsAPIKeyAccess.html) gestionado.
**Opción B: crear una política personalizada**
Cree y adjunte la siguiente política de IAM:
```
{
"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. Seleccione **Siguiente** y, a continuación, **Crear usuario**.
**nota**
Los permisos de KMS son necesarios si planea enviar registros a grupos de registros cifrados con KMS. La condición restringe el acceso al KMS únicamente a las claves utilizadas a través CloudWatch del servicio de registros.
### Paso 2: Generar credenciales específicas del servicio (clave de API)
Genere la clave CloudWatch de API de Logs mediante la [CreateServiceSpecificCredential](https://docs.aws.amazon.com/IAM/latest/APIReference/API_CreateServiceSpecificCredential.html)API. También puede utilizar el comando [create-service-specific-credential](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/iam/create-service-specific-credential.html)CLI. En cuanto a la antigüedad de las credenciales, puede especificar un valor entre 1 y 36600 días. Si no especifica una antigüedad de la credencial, la clave de API no caducará.
Para generar una clave de API con una caducidad de 30 días:
```
aws iam create-service-specific-credential \
--user-name cloudwatch-logs-hlc-user \
--service-name logs.amazonaws.com \
--credential-age-days 30
```
La respuesta es un [ServiceSpecificCredential](https://docs.aws.amazon.com/IAM/latest/APIReference/API_ServiceSpecificCredential.html)objeto. El `ServiceCredentialSecret` valor es tu clave de API de CloudWatch Logs (token portador).
**importante**
Guarde el valor `ServiceCredentialSecret` de forma segura, ya que no podrá recuperarlo más tarde. Si lo pierdes, tendrás que generar una nueva clave de API.
### Paso 3: Crear un grupo de registros y un flujo de registros
Cree el grupo de registros y el flujo de registros donde se almacenarán sus registros:
```
# 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
```
### Paso 4: Habilite la autenticación por token portador
Habilite la autenticación por token portador en el grupo de registros:
```
aws logs put-bearer-token-authentication \
--log-group-identifier /aws/hlc-logs/my-application \
--bearer-token-authentication-enabled \
--region us-east-1
```
Verifique la configuración:
```
aws logs describe-log-groups \
--log-group-name-prefix /aws/hlc-logs/my-application \
--region us-east-1
```
## Controle los permisos para generar y usar las claves de API CloudWatch de Logs
La generación y el uso de las claves de la API de CloudWatch Logs se controlan mediante claves de acción y condición tanto en los servicios de CloudWatch Logs como de IAM.
### Controlar la generación de claves de API de CloudWatch Logs
La CreateServiceSpecificCredential acción [iam:](https://docs.aws.amazon.com/service-authorization/latest/reference/list_awsidentityandaccessmanagementiam.html#awsidentityandaccessmanagementiam-actions-as-permissions) controla la generación de una clave específica del servicio (como una clave de API de CloudWatch Logs). Puede limitar esta acción a los usuarios de IAM como una forma de restringir el número de usuarios para los que se puede generar una clave.
Puede utilizar las siguientes claves de condición para imponer condiciones al permiso de la acción `iam:CreateServiceSpecificCredential`:
+ [iam: ServiceSpecificCredentialAgeDays](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_policies_iam-condition-keys.html#ck_ServiceSpecificCredentialAgeDays) — Permite especificar, en esta condición, el tiempo de caducidad de la clave en días. Por ejemplo, puede utilizar esta clave de condición para permitir únicamente la creación de claves de API que caduquen en 90 días.
+ [iam: ServiceSpecificCredentialServiceName](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_policies_iam-condition-keys.html#ck_ServiceSpecificCredentialAgeDays) — Permite especificar, en la condición, el nombre de un servicio. Por ejemplo, puedes usar esta clave de condición para permitir solo la creación de claves de API para CloudWatch los registros y no para otros servicios.
### Controlar el uso de las claves de API de CloudWatch Logs
La `logs:CallWithBearerToken` acción controla el uso de una clave de API de CloudWatch Logs. Para evitar que una identidad utilice las claves de la API de CloudWatch Logs, adjunte una política que deniegue la `logs:CallWithBearerToken` acción al usuario de IAM asociado a la clave.
### Ejemplos de políticas
#### Impida que una identidad genere y utilice las claves de la API CloudWatch de Logs
```
{
"Version": "2012-10-17",
"Statement": [
{
"Sid": "DenyCWLAPIKeys",
"Effect": "Deny",
"Action": [
"iam:CreateServiceSpecificCredential",
"logs:CallWithBearerToken"
],
"Resource": "*"
}
]
}
```
**aviso**
Esta política impedirá la creación de credenciales para todos los AWS servicios que admiten la creación de credenciales específicas de un servicio. Para obtener más información, consulte [Credenciales específicas del servicio para los usuarios de IAM](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_credentials_service-specific-creds.html).
#### Impida que una identidad utilice las claves de la API de CloudWatch Logs
```
{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Deny",
"Action": "logs:CallWithBearerToken",
"Resource": "*"
}
]
}
```
#### Permita la creación de claves de CloudWatch registro solo si caducan en un plazo de 90 días
```
{
"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"
}
}
}
]
}
```
## Claves de API rotativas
La rotación regular de las claves de API reduce el riesgo de acceso no autorizado. Te recomendamos establecer un programa de rotación que se ajuste a las políticas de seguridad de tu organización.
### Proceso de rotación
Para rotar una clave de API sin interrumpir la entrega de registros, siga este procedimiento:
1. Cree una nueva credencial (secundaria) para el usuario de IAM:
```
aws iam create-service-specific-credential \
--user-name cloudwatch-logs-hlc-user \
--service-name logs.amazonaws.com \
--credential-age-days 90
```
1. (Opcional) Guarde la nueva credencial AWS Secrets Manager para recuperarla de forma segura y rotarla automáticamente.
1. Importe la nueva credencial al portal de su proveedor o actualice la configuración de la aplicación para usar la nueva clave de API.
1. Defina la credencial original como inactiva:
```
aws iam update-service-specific-credential \
--user-name cloudwatch-logs-hlc-user \
--service-specific-credential-id ACCA1234EXAMPLE1234 \
--status Inactive
```
1. Compruebe que la entrega de registros no se vea afectada supervisando la `IncomingBytes` métrica de su grupo de registros. CloudWatch Para obtener más información, consulte [Supervisión con CloudWatch métricas](https://docs.aws.amazon.com/AmazonCloudWatch/latest/logs/CloudWatch-Logs-Monitoring-CloudWatch-Metrics.html).
1. Tras confirmar que la entrega se ha realizado correctamente con la nueva clave, elimine la credencial anterior:
```
aws iam delete-service-specific-credential \
--service-specific-credential-id ACCA1234EXAMPLE1234
```
### Supervisión del vencimiento de la clave
Para comprobar la fecha de creación y el estado de tus claves de API existentes, usa el [list-service-specific-credentials](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/iam/list-service-specific-credentials.html)comando:
```
aws iam list-service-specific-credentials \
--user-name cloudwatch-logs-hlc-user \
--service-name logs.amazonaws.com
```
La respuesta incluye `CreateDate` y `Status` para cada credencial. Utilice esta información para identificar las claves que están a punto de caducar o que han estado activas durante más tiempo del permitido por su política de rotación.
## Responder a una clave de API comprometida
Si sospechas que una clave de API se ha visto comprometida, sigue los siguientes pasos de inmediato:
1. **Desactiva la clave inmediatamente** para evitar que se siga utilizando sin autorización:
```
aws iam update-service-specific-credential \
--user-name cloudwatch-logs-hlc-user \
--service-specific-credential-id ACCA1234EXAMPLE1234 \
--status Inactive
```
1. **Revise CloudTrail los registros** para determinar el alcance del acceso no autorizado. Consulte [Registrar el uso de las claves de API con CloudTrail](#CWL_HTTP_Endpoints_CloudTrail_Logging) para saber cómo habilitar la auditoría del uso de las claves de API.
1. **Cree una clave de reemplazo** siguiendo el proceso de rotación descrito en[Proceso de rotación](#CWL_HTTP_Endpoints_Rotation_Process).
1. **Elimine la clave dañada** una vez que se haya realizado la sustitución:
```
aws iam delete-service-specific-credential \
--service-specific-credential-id ACCA1234EXAMPLE1234
```
1. **Adjunta una política de denegación** si necesitas bloquear inmediatamente todo acceso al token portador para el usuario de IAM mientras investigas:
```
{
"Version": "2012-10-17",
"Statement": {
"Effect": "Deny",
"Action": "logs:CallWithBearerToken",
"Resource": "*"
}
}
```
**nota**
Para llevar a cabo estas acciones a través de la API, debes autenticarte con AWS credenciales y no con una clave de API de CloudWatch Logs.
También puedes utilizar las siguientes operaciones de la API de IAM para gestionar las claves comprometidas:
+ [ResetServiceSpecificCredential](https://docs.aws.amazon.com/IAM/latest/APIReference/API_ResetServiceSpecificCredential.html)— Restablezca la clave para generar una nueva contraseña sin eliminar la credencial. La clave no debe haber caducado.
## Prácticas recomendadas de seguridad para las claves de API
Sigue estas prácticas recomendadas para proteger tus claves de API de CloudWatch Logs:
+ **Nunca insertes claves de API en el código fuente.** No codifique las claves de API en el código de la aplicación ni las consigne en los sistemas de control de versiones. Si una clave se guarda accidentalmente en un repositorio público, es posible que el escaneo AWS automático la señale y, por lo tanto, debes rotarla inmediatamente.
+ **Usa un administrador de secretos.** Almacene las claves de API en una solución de administración de secretos equivalente [AWS Secrets Manager](https://docs.aws.amazon.com/secretsmanager/latest/userguide/intro.html)o en una solución equivalente. Esto permite el control de acceso centralizado, el registro de auditorías y la rotación automática.
+ **Establezca una caducidad para todas las claves.** Especifique siempre un `--credential-age-days` valor al crear las claves de API. Para garantizar una vida útil máxima de las claves en toda su organización, utilice la clave de condición de `iam:ServiceSpecificCredentialAgeDays` IAM. Para ver un ejemplo, consulta [Permita la creación de claves de CloudWatch registro solo si caducan en un plazo de 90 días](#CWL_HTTP_Endpoints_Allow_Expire_90).
+ **Aplica permisos con privilegios mínimos.** Limite los permisos del usuario de IAM únicamente a los grupos de registros y las acciones necesarias. Utilice la política de [CloudWatchLogsAPIKeyacceso](https://docs.aws.amazon.com/aws-managed-policy/latest/reference/CloudWatchLogsAPIKeyAccess.html) gestionado como punto de partida y restrinja aún más según sea necesario.
+ **Habilite CloudTrail el registro.** Audite el uso de las claves de la API habilitando CloudTrail los eventos de datos para`AWS::Logs::LogGroupAuthorization`. Consulte [Registrar el uso de las claves de API con CloudTrail](#CWL_HTTP_Endpoints_CloudTrail_Logging).
+ **Supervise con IAM Access Analyzer.** Utilice [IAM Access Analyzer](https://docs.aws.amazon.com/IAM/latest/UserGuide/what-is-access-analyzer.html) para identificar las credenciales no utilizadas y las políticas excesivamente permisivas asociadas a los usuarios de IAM clave de la API.
+ **Gire las claves con regularidad.** Establezca un programa de rotación y siga el proceso descrito en[Claves de API rotativas](#CWL_HTTP_Endpoints_Rotating_Keys).
## Registrar el uso de las claves de API con CloudTrail
Se puede utilizar AWS CloudTrail para registrar eventos de datos para el uso de la clave de la API de CloudWatch Logs. CloudWatch Los registros emiten eventos de `AWS::Logs::LogGroupAuthorization` datos para `CallWithBearerToken` las llamadas, lo que te permite auditar cuándo y cómo se utilizan las claves de API para enviar los registros.
Para habilitar el CloudTrail registro para el uso de las claves CloudWatch de la API de Logs:
**nota**
El bucket de S3 que especifique para la ruta debe tener una política de bucket que permita CloudTrail escribir archivos de registro en él. Para obtener más información, consulte la [política de bucket de Amazon S3 para CloudTrail](https://docs.aws.amazon.com/awscloudtrail/latest/userguide/create-s3-bucket-policy-for-cloudtrail.html).
1. Cree una ruta:
```
aws cloudtrail create-trail \
--name cloudwatch-logs-api-key-audit \
--s3-bucket-name my-cloudtrail-bucket \
--region us-east-1
```
1. Configure selectores de eventos avanzados para capturar CloudWatch los eventos de autorización de grupos de registros:
```
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. Inicie el registro de rutas:
```
aws cloudtrail start-logging \
--name cloudwatch-logs-api-key-audit \
--region us-east-1
```
# Envío de registros mediante el punto final OTLP (OpenTelemetry registros)
El punto final de OpenTelemetry Logs (`/v1/logs`) acepta datos de registro OpenTelemetry del Protocolo (OTLP) codificados en JSON o Protobuf. Para obtener información detallada sobre el punto final de OTLP, incluida la configuración y el uso, consulte [Enviar métricas y](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/CloudWatch-OTLPEndpoint.html) seguimientos a with. CloudWatch OpenTelemetry
Si utiliza la autenticación mediante token de portador, complete los pasos de configuración [Configuración de la autenticación por token de portador](CWL_HTTP_Endpoints_BearerTokenAuth.md) antes de continuar.
## Formato de las solicitudes
+ Método: `POST`
+ Tipo de contenido: o `application/json` `application/x-protobuf`
+ Grupo de registros: solo `x-aws-log-group` encabezado (no se admite el parámetro de consulta)
+ Flujo de registro: `x-aws-log-stream` encabezado
## Ejemplo de solicitud
```
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" }
}
]
}
]
}
]
}
]
}'
```
## Respuestas
**Éxito (se aceptan todos los eventos):**
```
HTTP 200 OK
{}
```
**Éxito parcial (algunos eventos rechazados):**
```
{
"partialSuccess": {
"rejectedLogRecords": 5,
"errorMessage": "{\"tooOldLogEventCount\": 3, \"tooNewLogEventCount\": 1, \"expiredLogEventCount\": 1}"
}
}
```
Cuando la solicitud es Content-Type`application/x-protobuf`, la respuesta se devuelve como un mensaje `ExportLogsServiceResponse` protobuf serializado con los mismos campos.
## Comportamientos específicos de OTLP
Los siguientes comportamientos son específicos del punto final de OTLP y no están presentes en los otros puntos de enlace de ingestión de HTTP:
+ **Encabezado Retry-After**: se incluye en las respuestas 503 y 429 para indicar cuándo el cliente debe volver a intentarlo.
# Envío de registros mediante el punto final de HLC (registros de HLC)
El punto final de HLC Logs (`/services/collector/event`) se basa en el formato HTTP Log Collector (HLC).
Si utiliza la autenticación mediante token de portador, complete los pasos de configuración antes de continuar. [Configuración de la autenticación por token de portador](CWL_HTTP_Endpoints_BearerTokenAuth.md)
## Modos de entrada
Cada evento es un objeto JSON con un `"event"` campo obligatorio. Campos de metadatos opcionales:`"time"`,`"host"`,`"source"`,`"sourcetype"`,`"index"`.
**Evento único:**
```
{"event":"Hello world!","time":1486683865.0}
```
**Matriz de eventos JSON:**
```
[
{"event":"msg1","time":1486683865.0},
{"event":"msg2","time":1486683866.0}
]
```
**Eventos concatenados o por lotes (sin contenedor de matrices):**
```
{"event":"msg1","time":1486683865.0}{"event":"msg2","time":1486683866.0}
```
## Campo de evento (obligatorio)
El `"event"` campo es obligatorio. Su valor puede ser de cualquier tipo de JSON:
```
{"event":"a string message"}
{"event":{"message":"structured data","severity":"INFO"}}
{"event":42}
{"event":true}
```
Los objetos sin un `"event"` campo se omiten silenciosamente:
```
{"message":"this is skipped — no event field"}
```
## Campo de tiempo (opcional)
El `"time"` campo está expresado en segundos de época (no en milisegundos), con decimales opcionales para una precisión inferior a un segundo.
| Formato | Ejemplo | Interpretado como |
| --- | --- | --- |
| Flotante | "time":1486683865.500 | 1486683865500 ms |
| Entero | "time":1486683865 | 1486683865000 ms |
| Cadena (flotante) | "time":"1486683865.500" | 1486683865500 ms |
| Cadena (entero) | "time":"1486683865" | 1486683865000 ms |
| Missing (Ausente) | (sin campo de tiempo) | Hora actual del servidor |
| Invalid (No válido) | "time":"invalid" | Hora actual del servidor |
## Contenido-Tipo
Solo `application/json` se acepta.
## Tipos de valores JSON aceptados
| Tipo de nivel superior | Comportamiento |
| --- | --- |
| Objeto con "event" | Aceptada |
| Objeto sin "event" | Omitido |
| Matriz de objetos | Cada elemento procesado individualmente |
| Objetos concatenados | Cada objeto se procesa de forma individual |
| Primitivo (cadena, número, booleano, nulo) | Omitido |
## Formato de punto de conexión
La URL del punto final del HLC sigue este formato:
```
https://logs..amazonaws.com/services/collector/event?logGroup=&logStream=[&entityName=&entityEnvironment=]
```
**Parámetros necesarios:**
+ ``— AWS Región (por ejemplo,`us-east-1`,`eu-west-1`)
+ `logGroup`— Nombre del grupo de registros codificado en una URL
+ `logStream`— Nombre del flujo de registro codificado en una URL
**Parámetros opcionales:**
Si lo desea, puede asociar sus eventos de registro a una `Service` entidad mediante la inclusión de los siguientes parámetros de consulta. Como los registros enviados a través del punto final del HLC son telemetría personalizada, no se asocian automáticamente a una entidad. Al proporcionar estos parámetros, CloudWatch Logs crea una entidad con `KeyAttributes.Type` set en `Service` y la asocia a sus eventos de registro. Esto permite que la función **relacionada con Explore** CloudWatch correlacione estos registros con otros datos de telemetría (métricas, trazas y registros) del mismo servicio, lo que facilita la resolución de problemas y la supervisión de las aplicaciones en diferentes tipos de señales. Para obtener más información sobre las entidades y la telemetría relacionada, consulte [Añadir](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/adding-your-own-related-telemetry.html) información relacionada a la telemetría personalizada.
+ `entityName`— El nombre de la entidad de servicio que se va a asociar al registro de eventos. Este valor se almacena como entidad `KeyAttributes.Name` (por ejemplo, `my-application` o`api.myservice.com`).
+ `entityEnvironment`— El entorno en el que se aloja el servicio o al que pertenece. Este valor se almacena como entidad `KeyAttributes.Environment` (por ejemplo,`production`,`ec2:default`, o`eks:my-cluster/default`).
## Formato de las solicitudes
Envíe los registros mediante HTTP POST con los siguientes encabezados y cuerpo:
**Encabezados:**
+ `Authorization: Bearer `
+ `Content-Type: application/json`
**Formato de cuerpo:**
El cuerpo de la solicitud debe estar en formato JSON con una serie de eventos:
```
{
"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"
}
]
}
```
**Descripciones de los campos:**
+ `time`— Marca temporal de época de Unix en segundos, con decimal opcional para una precisión inferior a un segundo (opcional)
+ `event`— El mensaje de registro o los datos del evento (obligatorio)
+ `host`— Nombre de host o identificador de origen (opcional)
+ `source`— Identificador de la fuente del registro (opcional)
Se pueden incluir campos personalizados adicionales según sea necesario.
## Ejemplo de solicitud
```
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"}'
```
## Prácticas recomendadas
### Agrupación de eventos por lotes
Para un mejor rendimiento y eficiencia:
+ Batch varios eventos en una sola solicitud cuando sea posible
+ Tamaño de lote recomendado: de 10 a 100 eventos por solicitud
+ Tamaño máximo de la solicitud: 1 MB
### Gestión de errores
Implemente una gestión de errores adecuada en su aplicación. Códigos de estado HTTP comunes:
+ `200 OK`— Los registros se ingirieron correctamente
+ `400 Bad Request`— Formato o parámetros de solicitud no válidos
+ `401 Unauthorized`— Token de portador no válido o caducado
+ `403 Forbidden`— Permisos insuficientes
+ `404 Not Found`— El grupo de registros o la transmisión no existen
+ `429 Too Many Requests`— Se ha superado el límite de velocidad
+ `500 Internal Server Error`— Error de servicio (reintento con un retraso exponencial)
## Limitaciones
+ Tamaño máximo del evento: 256 KB por evento
+ Tamaño máximo de solicitud: 1 MB
+ Número máximo de eventos por solicitud: 10 000
+ Los nombres de los grupos de registros deben seguir las convenciones CloudWatch de nomenclatura de los registros
+ La autenticación por token de portador debe estar habilitada en el grupo de registros si se utiliza la autenticación por token de portador.
# Envío de registros mediante el punto final NDJSON (registros ND-JSON)
El punto final de registros de ND-JSON (`/ingest/bulk`) acepta registros en formato [NDJSON](https://github.com/ndjson/ndjson-spec) (JSON delimitado por nueva línea). Cada línea contiene exactamente un valor JSON, separado por caracteres de nueva línea.
Si utiliza la autenticación mediante token de portador, complete los pasos de configuración [Configuración de la autenticación por token de portador](CWL_HTTP_Endpoints_BearerTokenAuth.md) antes de continuar.
## Formato de las solicitudes
Envía un valor JSON por línea, separado por `\n` (LF) o `\r\n` (CRLF). Las líneas vacías se ignoran silenciosamente.
```
{"timestamp":1771007942000,"message":"event one","level":"INFO"}
{"timestamp":1771007943000,"message":"event two","level":"ERROR"}
{"timestamp":1771007944000,"message":"event three","level":"DEBUG"}
```
Ambas `application/json` `application/x-ndjson` se aceptan como tipo de contenido.
## Tipos de valores JSON aceptados
Según la especificación NDJSON (RFC 8259), se acepta cualquier valor JSON válido en cada línea.
**Objetos JSON (los más comunes):**
```
{"timestamp":1771007942000,"message":"User logged in","service":"auth"}
{"timestamp":1771007943000,"error":"Connection timeout","service":"api"}
```
**Matrices JSON (agrupadas en eventos individuales):**
```
[{"timestamp":1000,"message":"a"},{"timestamp":2000,"message":"b"}]
```
Esta única línea produce 2 eventos. Cada elemento de la matriz se convierte en un evento de registro independiente.
**Valores primitivos:**
```
"a plain string log message"
42
true
null
```
Cada primitivo se convierte en su propio evento con la marca de tiempo actual del servidor.
**Tipos mixtos:**
```
{"timestamp":1771007942000,"message":"structured event"}
"unstructured string message"
42
{"timestamp":1771007943000,"error":"something failed"}
```
Las 4 líneas se aceptan como eventos válidos.
| Contenido de la línea | Comportamiento |
| --- | --- |
| Objeto JSON | Aceptado, se extrae la marca de tiempo si está presente |
| matriz JSON | Aplanado: cada elemento se convierte en un evento independiente |
| Matriz vacía [] | Aceptado, produce 0 eventos |
| Cadena JSON | Aceptado como mensaje de evento |
| Número JSON | Aceptado como mensaje de evento |
| Booleano JSON | Aceptado como mensaje de evento |
| JSON nulo | Aceptado como mensaje de evento |
| JSON no válido | Omitido (contado, el procesamiento continúa) |
| Línea vacía | Ignorada (no se cuenta como omitida) |
## Campo de fecha y hora
El `"timestamp"` campo está expresado en milisegundos de época (no segundos).
| Formato | Ejemplo | Interpretado como |
| --- | --- | --- |
| Numérico (milis) | "timestamp":1771007942000 | 1771007942000 ms |
| Missing (Ausente) | (sin campo de marca de tiempo) | Hora actual del servidor |
| No numérico | "timestamp":"invalid" | Hora actual del servidor |
| Línea que no es de objetos | "hello", 42, true | Hora actual del servidor |
## Líneas no válidas
Las líneas que no son JSON válidas se omiten y se cuentan de forma silenciosa. El procesamiento continúa con la siguiente línea.
```
{"message":"valid event"}
this is not valid json
{"message":"another valid event"}
```
Resultado: 2 eventos ingeridos y 1 omitido. Devuelve `HTTP 200`.
Si todas las líneas no son válidas, devuelve `HTTP 400` con. `"All events were invalid"`
## Ejemplo de solicitud
```
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"}'
```
## Respuestas
**Éxito (se aceptan todos los eventos):**
```
HTTP 200 OK
{}
```
**Éxito parcial (algunos eventos rechazados):**
```
{
"partialSuccess": {
"rejectedLogRecords": 5,
"errorMessage": "{\"tooOldLogEventCount\": 3, \"tooNewLogEventCount\": 1, \"expiredLogEventCount\": 1}"
}
}
```
El `rejectedLogRecords` campo es el número total de eventos rechazados. El `errorMessage` campo contiene un desglose codificado en JSON por motivo de rechazo:
+ `tooOldLogEventCount`— Eventos con marcas de tiempo anteriores al período de retención
+ `tooNewLogEventCount`— Eventos con marcas de tiempo demasiado lejanas en el futuro
+ `expiredLogEventCount`— Eventos que caducaron durante el procesamiento
## Prácticas recomendadas
### Agrupación de eventos por lotes
Para un mejor rendimiento y eficiencia:
+ Batch varios eventos en una sola solicitud cuando sea posible
+ Tamaño de lote recomendado: de 10 a 100 eventos por solicitud
+ Tamaño máximo de la solicitud: 1 MB
### Gestión de errores
Implemente una gestión de errores adecuada en su aplicación. Códigos de estado HTTP comunes:
+ `200 OK`— Los registros se ingirieron correctamente
+ `400 Bad Request`— Formato o parámetros de solicitud no válidos
+ `401 Unauthorized`— Token de portador no válido o caducado
+ `403 Forbidden`— Permisos insuficientes
+ `404 Not Found`— El grupo de registros o la transmisión no existen
+ `429 Too Many Requests`— Se ha superado el límite de velocidad
+ `500 Internal Server Error`— Error de servicio (reintento con un retraso exponencial)
## Limitaciones
+ Tamaño máximo del evento: 256 KB por evento
+ Tamaño máximo de solicitud: 1 MB
+ Número máximo de eventos por solicitud: 10 000
+ Los nombres de los grupos de registros deben seguir las convenciones CloudWatch de nomenclatura de los registros
+ La autenticación por token de portador debe estar habilitada en el grupo de registros si se utiliza la autenticación por token de portador.
# Envío de registros mediante el punto final de Structured JSON (Structured JSON Logs)
El punto final de Structured JSON Logs (`/ingest/json`) acepta JSON estándar, ya sea un único objeto JSON o una matriz de objetos JSON. Este punto final está diseñado para datos de registro estructurados en los que cada evento es un objeto JSON.
Si utiliza la autenticación por token de portador, complete los pasos de configuración [Configuración de la autenticación por token de portador](CWL_HTTP_Endpoints_BearerTokenAuth.md) antes de continuar.
## Formato de las solicitudes
Solo `application/json` se acepta como tipo de contenido.
**Objeto JSON único:**
```
{"timestamp":1771007942000,"message":"single event","level":"INFO"}
```
**Matriz de objetos JSON:**
```
[
{"timestamp":1771007942000,"message":"event one","level":"INFO"},
{"timestamp":1771007943000,"message":"event two","level":"ERROR"}
]
```
## Tipos de valores JSON aceptados
Este punto final es estricto: solo los objetos JSON se aceptan como eventos.
| Input | Comportamiento |
| --- | --- |
| Objeto JSON único | Se acepta como un solo evento |
| Matriz de objetos JSON | Cada objeto se convierte en un evento independiente |
| Matriz vacía [] | Aceptado, produce 0 eventos |
| No es un objeto en la matriz (cadena, número, etc.) | Omitido |
| Primitiva de nivel superior ("hello",) 42 | Omitido |
| Objetos concatenados \$1...\$1\$1...\$1 | Solo se analizó el primer objeto |
**Ejemplo: matriz con tipos mixtos:**
```
[
{"timestamp":1771007942000,"message":"valid object"},
"just a string",
42,
{"timestamp":1771007943000,"message":"another valid object"}
]
```
Resultado: 2 eventos ingeridos (los objetos) y 2 omitidos (la cadena y el número).
## Campo de fecha y hora
El `"timestamp"` campo está expresado en milisegundos de época, igual que el punto final NDJSON.
| Formato | Ejemplo | Interpretado como |
| --- | --- | --- |
| Numérico (milis) | "timestamp":1771007942000 | 1771007942000 ms |
| Missing (Ausente) | (sin campo de marca de tiempo) | Hora actual del servidor |
| No numérico | "timestamp":"invalid" | Hora actual del servidor |
## Ejemplo de solicitud
```
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"}]'
```
## Respuestas
**Éxito (se aceptan todos los eventos):**
```
HTTP 200 OK
{}
```
**Éxito parcial (algunos eventos rechazados):**
```
{
"partialSuccess": {
"rejectedLogRecords": 5,
"errorMessage": "{\"tooOldLogEventCount\": 3, \"tooNewLogEventCount\": 1, \"expiredLogEventCount\": 1}"
}
}
```
El `rejectedLogRecords` campo es el número total de eventos rechazados. El `errorMessage` campo contiene un desglose codificado en JSON por motivo de rechazo:
+ `tooOldLogEventCount`— Eventos con marcas de tiempo anteriores al período de retención
+ `tooNewLogEventCount`— Eventos con marcas de tiempo demasiado lejanas en el futuro
+ `expiredLogEventCount`— Eventos que caducaron durante el procesamiento
## Prácticas recomendadas
### Agrupación de eventos por lotes
Para un mejor rendimiento y eficiencia:
+ Batch varios eventos en una sola solicitud cuando sea posible
+ Tamaño de lote recomendado: de 10 a 100 eventos por solicitud
+ Tamaño máximo de la solicitud: 1 MB
### Gestión de errores
Implemente una gestión de errores adecuada en su aplicación. Códigos de estado HTTP comunes:
+ `200 OK`— Los registros se ingirieron correctamente
+ `400 Bad Request`— Formato o parámetros de solicitud no válidos
+ `401 Unauthorized`— Token de portador no válido o caducado
+ `403 Forbidden`— Permisos insuficientes
+ `404 Not Found`— El grupo de registros o la transmisión no existen
+ `429 Too Many Requests`— Se ha superado el límite de velocidad
+ `500 Internal Server Error`— Error de servicio (reintento con un retraso exponencial)
## Limitaciones
+ Tamaño máximo del evento: 256 KB por evento
+ Tamaño máximo de solicitud: 1 MB
+ Número máximo de eventos por solicitud: 10 000
+ Los nombres de los grupos de registros deben seguir las convenciones CloudWatch de nomenclatura de los registros
+ La autenticación por token de portador debe estar habilitada en el grupo de registros si se utiliza la autenticación por token de portador.
## Comparación de los puntos finales de ingestión de HTTP
| Característica | Registros de HLC | Registros de ND-JSON | Registros JSON estructurados | OpenTelemetry Registros |
| --- | --- | --- | --- | --- |
| Ruta | /services/collector/event | /ingest/bulk | /ingest/json | /v1/logs |
| Contenido-Tipo | application/json | application/json o application/x-ndjson | application/json | application/json o application/x-protobuf |
| Campo de fecha y hora | "time" (segundos) | "timestamp"(milisegundos) | "timestamp"(milisegundos) | "timeUnixNano"(nanosegundos) |
| Campos obligatorios | "event" | Ninguno | Ninguno | Estructura OTP () "resourceLogs" |
| Respuesta de éxito parcial | No | Sí | Sí | Sí |
| Compatibilidad con parámetros de consulta | Sí | Sí | Sí | No (solo encabezados) |
| Metadatos de entidad | Sí | Sí | Sí | No |
| Acepta primitivas | No | Sí | No | No |
| Análisis basado en líneas | No | Sí | No | No |
| Soporte para Protobug | No | No | No | Sí |
| Encabezado Retry-After | No | No | No | Sí |
## Elegir un punto final
+ **¿Utiliza el formato HLC?** Utilice los registros de HLC. Sus cargas útiles de HLC actuales funcionan con cambios mínimos.
+ **¿Registros de streaming? line-by-line** Utilice los registros de ND-JSON. Ideal para canalizaciones de registro que emiten un evento por línea. El más flexible: acepta cualquier tipo de valor JSON.
+ **¿Envía cargas útiles JSON estructuradas?** Utilice registros JSON estructurados. Ideal para aplicaciones que producen matrices o objetos JSON bien formados.
+ **¿Ya lo estás usando? OpenTelemetry** Usa OpenTelemetry registros. Acepta el formato OTLP, JSON o Protobuf y admite respuestas de éxito parcial con semántica de reintentos.