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.
# 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.