As traduções são geradas por tradução automática. Em caso de conflito entre o conteúdo da tradução e da versão original em inglês, a versão em inglês prevalecerá.
# Enviando registros usando o endpoint HLC (HLC Logs)
O endpoint do HLC Logs (`/services/collector/event`) é baseado no formato HTTP Log Collector (HLC).
Se você estiver usando a autenticação do token do portador, conclua as etapas de configuração [Configurando a autenticação do token do portador](CWL_HTTP_Endpoints_BearerTokenAuth.md) antes de continuar.
## Modos de entrada
Cada evento é um objeto JSON com um `"event"` campo obrigatório. Campos de metadados opcionais:`"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/agrupados (sem invólucro de matriz):**
```
{"event":"msg1","time":1486683865.0}{"event":"msg2","time":1486683866.0}
```
## Campo do evento (obrigatório)
O `"event"` campo é obrigatório. Seu valor pode ser qualquer tipo de JSON:
```
{"event":"a string message"}
{"event":{"message":"structured data","severity":"INFO"}}
{"event":42}
{"event":true}
```
Objetos sem um `"event"` campo são ignorados silenciosamente:
```
{"message":"this is skipped — no event field"}
```
## Campo de hora (opcional)
O `"time"` campo está em segundos de época (não em milissegundos), com decimal opcional para precisão de menos de um segundo.
| Formato | Exemplo | Interpretada como |
| --- | --- | --- |
| Float | "time":1486683865.500 | 148683865.500 ms |
| Inteiro | "time":1486683865 | 1486683865.000 ms |
| Corda (flutuação) | "time":"1486683865.500" | 148683865.500 ms |
| Cadeia de caracteres (inteiro) | "time":"1486683865" | 1486683865.000 ms |
| Missing (Ausente) | (sem campo de hora) | Hora atual do servidor |
| Inválido | "time":"invalid" | Hora atual do servidor |
## Content-Type
Só `application/json` é aceito.
## Tipos de valores JSON aceitos
| Tipo de nível superior | Comportamento |
| --- | --- |
| Objeto com "event" | Aceito |
| Objeto sem "event" | Ignorado |
| Matriz de objetos | Cada elemento processado individualmente |
| Objetos concatenados | Cada objeto processado individualmente |
| Primitivo (string, número, booleano, nulo) | Ignorado |
## Formato do endpoint
O URL do endpoint do HLC segue este formato:
```
https://logs..amazonaws.com/services/collector/event?logGroup=&logStream=[&entityName=&entityEnvironment=]
```
**Parâmetros necessários:**
+ ``— AWS Região (por exemplo,`us-east-1`,`eu-west-1`)
+ `logGroup`— Nome do grupo de registros codificado por URL
+ `logStream`— Nome do fluxo de log codificado por URL
**Parâmetros opcionais:**
Opcionalmente, você pode associar seus eventos de log a uma `Service` entidade incluindo os seguintes parâmetros de consulta. Como os registros enviados pelo endpoint do HLC são telemetria personalizada, eles não são associados automaticamente a uma entidade. Ao fornecer esses parâmetros, o CloudWatch Logs cria uma entidade com `KeyAttributes.Type` set to `Service` e a associa aos seus eventos de registro. Isso permite que o recurso **relacionado ao Explore** correlacione esses registros com outras telemetrias (métricas, rastreamentos e registros) do mesmo serviço, facilitando a solução de problemas e o monitoramento de seus aplicativos em diferentes tipos de sinal. CloudWatch Para obter mais informações sobre entidades e telemetria relacionada, consulte [Adicionar informações relacionadas à telemetria personalizada](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/adding-your-own-related-telemetry.html).
+ `entityName`— O nome da entidade de serviço a ser associada aos eventos de log. Esse valor é armazenado como a entidade `KeyAttributes.Name` (por exemplo, `my-application` ou`api.myservice.com`).
+ `entityEnvironment`— O ambiente em que o serviço está hospedado ou ao qual ele pertence. Esse valor é armazenado como a entidade `KeyAttributes.Environment` (por exemplo`production`,`ec2:default`, ou`eks:my-cluster/default`).
## Formato de solicitação
Envie registros usando HTTP POST com os seguintes cabeçalhos e corpo:
**Cabeçalhos:**
+ `Authorization: Bearer `
+ `Content-Type: application/json`
**Formato do corpo:**
O corpo da solicitação deve estar no formato JSON com uma matriz 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"
}
]
}
```
**Descrições de campo:**
+ `time`— Timestamp da época do Unix em segundos, com decimal opcional para precisão de menos de um segundo (opcional)
+ `event`— A mensagem de registro ou os dados do evento (obrigatório)
+ `host`— Nome do host ou identificador de origem (opcional)
+ `source`— Identificador da fonte de log (opcional)
Campos personalizados adicionais podem ser incluídos conforme necessário.
## Exemplo de solicitação
```
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áticas recomendadas
### eventos em lotes
Para melhor desempenho e eficiência:
+ Agrupe vários eventos em uma única solicitação, quando possível
+ Tamanho de lote recomendado: 10 a 100 eventos por solicitação
+ Tamanho máximo da solicitação: 1 MB
### Tratamento de erros
Implemente o tratamento adequado de erros em seu aplicativo. Códigos de status HTTP comuns:
+ `200 OK`— Registros ingeridos com sucesso
+ `400 Bad Request`— Formato ou parâmetros de solicitação inválidos
+ `401 Unauthorized`— Token de portador inválido ou expirado
+ `403 Forbidden`— Permissões insuficientes
+ `404 Not Found`— O grupo de log ou stream não existe
+ `429 Too Many Requests`— Limite de taxa excedido
+ `500 Internal Server Error`— Erro de serviço (tente novamente com recuo exponencial)
## Limitações
+ Tamanho máximo do evento: 256 KB por evento
+ Tamanho máximo da solicitação: 1 MB
+ Máximo de eventos por solicitação: 10.000
+ Os nomes dos grupos de registros devem seguir as convenções de nomenclatura de CloudWatch registros
+ A autenticação do token do portador deve ser ativada no grupo de registros se a autenticação do token do portador for usada.