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á.
# Ingestão de registros por meio de endpoints HTTP
O Amazon CloudWatch Logs fornece endpoints HTTP que permitem que você envie registros diretamente para o CloudWatch Logs usando solicitações HTTP POST simples. Esses endpoints oferecem suporte à autenticação SigV4 e ao token do portador.
**Importante**
Recomendamos usar a autenticação SigV4 para todas as cargas de trabalho de produção em que a integração do AWS SDK é possível. O SigV4 usa credenciais de curto prazo e fornece a postura de segurança mais forte. A autenticação do token do portador (chave de API) é destinada a cenários em que o SigV4 não é viável, como encaminhadores de log de terceiros que não oferecem suporte à integração do SDK. AWS Para obter mais informações, consulte [Alternativas às chaves de acesso de longo prazo](https://docs.aws.amazon.com/IAM/latest/UserGuide/best-practices.html#bp-workloads-use-roles) no *Guia do usuário do IAM*.
CloudWatch O Logs é compatível com os seguintes endpoints de ingestão de HTTP:
| Endpoint | Path | Content-Type | Formato |
| --- | --- | --- | --- |
| [OpenTelemetry Logs](CWL_HTTP_Endpoints_OTLP.md) | /v1/logs | application/json ou application/x-protobuf | OTLP JSON ou Protobuf |
| [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 ou application/x-ndjson | JSON delimitado por Newline |
| [Structured JSON Logs](CWL_HTTP_Endpoints_StructuredJSON.md) | /ingest/json | application/json | Objeto ou matriz JSON |
## Comportamento comum
Todos os endpoints de ingestão de HTTP compartilham o seguinte comportamento:
**Autenticação**
Todos os endpoints oferecem suporte à autenticação SigV4 e ao token do portador:
+ **SigV4 (recomendado)** — AWS Assinatura padrão versão 4. Use o SigV4 sempre que seu aplicativo ou infraestrutura suportar o AWS SDK ou puder assinar solicitações. O SigV4 usa credenciais de curto prazo e é o método de autenticação mais seguro.
+ **Token do portador** — Use o `Authorization: Bearer ` cabeçalho.
+ O token deve ser um token portador de ACWL válido. Para obter instruções de configuração, consulte[Configurando a autenticação do token do portador](CWL_HTTP_Endpoints_BearerTokenAuth.md).
+ Requer as permissões `logs:CallWithBearerToken` do IAM `logs:PutLogEvents` e do IAM.
**Grupo de registros e fluxo de registros**
+ Fornecido por meio de cabeçalhos: `x-aws-log-group` e `x-aws-log-stream`
+ `?logGroup=&logStream=`Os parâmetros de consulta também são suportados em todos os endpoints, exceto OTLP.
+ Você não pode usar parâmetros de consulta e cabeçalhos para o mesmo parâmetro.
+ Tanto o grupo de registros quanto o fluxo de registros são obrigatórios.
**Resposta**
+ Sucesso: `HTTP 200` com corpo `{}`
+ Erros de validação: `HTTP 400`
+ Falhas de autenticação: `HTTP 401`
# Configurando a autenticação do token do portador
Antes de enviar registros usando a autenticação de token do portador com qualquer um dos endpoints de ingestão HTTP, você precisa:
+ Crie um usuário do IAM com permissões CloudWatch de registros
+ Gere credenciais específicas do serviço (token do portador)
+ Crie um grupo de registros e um fluxo de registros
+ Ativar a autenticação do token do portador no grupo de registros
**Importante**
Recomendamos usar a autenticação SigV4 com credenciais de curto prazo para todas as cargas de trabalho, sempre que possível. O SigV4 fornece a postura de segurança mais forte. Restrinja o uso de chaves de API (tokens portadores) a cenários em que a autenticação de curto prazo baseada em credenciais não seja viável. Quando estiver pronto para incorporar CloudWatch registros em aplicativos com maiores requisitos de segurança, você deve mudar para credenciais de curto prazo. Para obter mais informações, consulte [Alternativas às chaves de acesso de longo prazo](https://docs.aws.amazon.com/IAM/latest/UserGuide/best-practices.html#bp-workloads-use-roles) no *Guia do usuário do IAM*.
## Opção 1: início rápido usando o AWS console
O AWS Management Console fornece um fluxo de trabalho simplificado para gerar chaves de API para acesso ao endpoint HTTP.
**Para configurar o acesso ao endpoint HTTP usando o console**
1. Faça login no AWS Management Console.
1. Navegue até **CloudWatch**> **Configurações** > **Registros**.
1. Na seção Chaves de API, escolha **Gerar chave de API**.
1. Em **Validade da chave de API**, faça uma das seguintes opções:
+ Selecione uma duração de expiração da chave de API de **1**, **5**, **30**, **90** ou **365** dias.
+ Escolha **Duração personalizada** para especificar uma data de validade personalizada para a chave de API.
+ Selecione **Nunca expira** (não recomendado).
1. Escolha **Gerar chave de API**.
O console automaticamente:
+ Cria um novo usuário do IAM com as permissões apropriadas
+ Anexa a política gerenciada do [CloudWatchLogsAPIKeyAccess](https://docs.aws.amazon.com/aws-managed-policy/latest/reference/CloudWatchLogsAPIKeyAccess.html) (inclusões `logs:PutLogEvents` e `logs:CallWithBearerToken` permissões)
+ Gera credenciais específicas do serviço (chave de API)
1. Copie e salve com segurança as credenciais exibidas:
+ ID **da chave de API (ID** de credencial específica do serviço)
+ **Segredo da chave da API** (token do portador)
**Importante**
Salve o segredo da chave de API imediatamente. Ela não poderá ser recuperada posteriormente. Se você a perder, precisará gerar uma nova chave de API.
1. Crie o grupo de registros e o fluxo de registros em que seus registros serão armazenados:
```
# 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. Ative a autenticação do token do portador no 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 a configuração:
```
aws logs describe-log-groups \
--log-group-name-prefix /aws/hlc-logs/my-application \
--region us-east-1
```
**Permissões incluídas:** o usuário do IAM criado automaticamente terá as seguintes permissões:
+ `logs:PutLogEvents`— Enviar eventos de registro para CloudWatch Logs
+ `logs:CallWithBearerToken`— Autenticar usando o token do portador
+ `kms:Describe*`,`kms:GenerateDataKey*`, `kms:Decrypt` — Acesse grupos de registros criptografados pelo KMS (com condição restrita ao serviço de registros)
## Opção 2: configuração manual
Se você preferir ter mais controle sobre a configuração do IAM ou precisar personalizar as permissões, você pode configurar o acesso ao endpoint HTTP manualmente.
### Etapa 1: criar um usuário do IAM
Crie um usuário do IAM que será usado para ingestão de registros:
1. Faça login no AWS Management Console e navegue até o IAM.
1. No painel de navegação à esquerda, escolha **Usuários**.
1. Selecione **Criar usuário**.
1. Insira um nome de usuário (por exemplo,`cloudwatch-logs-hlc-user`).
1. Escolha **Próximo**.
1. Anexe uma das seguintes políticas do IAM:
**Opção A: usar a política gerenciada (recomendada)**
Anexe a política gerenciada do [CloudWatchLogsAPIKeyAccess](https://docs.aws.amazon.com/aws-managed-policy/latest/reference/CloudWatchLogsAPIKeyAccess.html).
**Opção B: criar uma política personalizada**
Crie e anexe a seguinte política do 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. Escolha **Avançar** e, em seguida, **Criar usuário**.
**nota**
As permissões do KMS são necessárias se você planeja enviar registros para grupos de registros criptografados pelo KMS. A condição restringe o acesso ao KMS somente às chaves usadas por meio do serviço de CloudWatch registros.
### Etapa 2: gerar credenciais específicas do serviço (chave de API)
Gere a chave da API CloudWatch Logs usando a [CreateServiceSpecificCredential](https://docs.aws.amazon.com/IAM/latest/APIReference/API_CreateServiceSpecificCredential.html)API. Você também pode usar o comando [create-service-specific-credential](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/iam/create-service-specific-credential.html)CLI. Para a idade da credencial, você pode especificar um valor entre 1 e 36600 dias. Se você não especificar o prazo de validade de uma credencial, a chave da API não expirará.
Para gerar uma chave de API com uma expiração de 30 dias:
```
aws iam create-service-specific-credential \
--user-name cloudwatch-logs-hlc-user \
--service-name logs.amazonaws.com \
--credential-age-days 30
```
A resposta é um [ServiceSpecificCredential](https://docs.aws.amazon.com/IAM/latest/APIReference/API_ServiceSpecificCredential.html)objeto. O `ServiceCredentialSecret` valor é sua chave da API CloudWatch Logs (token do portador).
**Importante**
Armazene o valor `ServiceCredentialSecret` em segurança, pois não será possível recuperá-lo mais tarde. Se você a perder, precisará gerar uma nova chave de API.
### Etapa 3: criar um grupo de registros e um fluxo de registros
Crie o grupo de registros e o fluxo de registros em que seus registros serão armazenados:
```
# 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
```
### Etapa 4: ativar a autenticação do token do portador
Ative a autenticação do token do portador no 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 a configuração:
```
aws logs describe-log-groups \
--log-group-name-prefix /aws/hlc-logs/my-application \
--region us-east-1
```
## Controle as permissões para gerar e usar CloudWatch as chaves da API Logs
A geração e o uso das chaves da API CloudWatch Logs são controlados por ações e chaves de condição nos serviços do CloudWatch Logs e do IAM.
### Controle da geração de chaves da API CloudWatch Logs
A CreateServiceSpecificCredential ação [iam:](https://docs.aws.amazon.com/service-authorization/latest/reference/list_awsidentityandaccessmanagementiam.html#awsidentityandaccessmanagementiam-actions-as-permissions) controla a geração de uma chave específica do serviço (como uma chave da API CloudWatch Logs). Você pode definir o escopo dessa ação para usuários do IAM como um recurso para limitar os usuários para os quais uma chave pode ser gerada.
É possível usar as seguintes chaves de condição para impor condições à permissão para a ação `iam:CreateServiceSpecificCredential`:
+ [iam: ServiceSpecificCredentialAgeDays](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_policies_iam-condition-keys.html#ck_ServiceSpecificCredentialAgeDays) — Permite especificar, na condição, o tempo de expiração da chave em dias. Por exemplo, é possível usar essa chave de condição para permitir somente a criação de chaves de API que expirem em noventa dias.
+ [iam: ServiceSpecificCredentialServiceName](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_policies_iam-condition-keys.html#ck_ServiceSpecificCredentialAgeDays) — Permite especificar, na condição, o nome de um serviço. Por exemplo, você pode usar essa chave de condição para permitir somente a criação de chaves de API para CloudWatch Logs e não para outros serviços.
### Controle do uso das chaves da API CloudWatch Logs
A `logs:CallWithBearerToken` ação controla o uso de uma chave da API CloudWatch Logs. Para evitar que uma identidade use as chaves da API CloudWatch Logs, anexe uma política que negue a `logs:CallWithBearerToken` ação ao usuário do IAM associado à chave.
### Exemplo de política
#### Impedir que uma identidade gere e use CloudWatch as chaves da API Logs
```
{
"Version": "2012-10-17",
"Statement": [
{
"Sid": "DenyCWLAPIKeys",
"Effect": "Deny",
"Action": [
"iam:CreateServiceSpecificCredential",
"logs:CallWithBearerToken"
],
"Resource": "*"
}
]
}
```
**Atenção**
Essa política impedirá a criação de credenciais para todos os AWS serviços que oferecem suporte à criação de credenciais específicas do serviço. Para ter mais informações, consulte [Credenciais específicas do serviço para usuários do IAM](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_credentials_service-specific-creds.html).
#### Impedir que uma identidade use CloudWatch as chaves da API Logs
```
{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Deny",
"Action": "logs:CallWithBearerToken",
"Resource": "*"
}
]
}
```
#### Permita a criação de chaves de CloudWatch registros somente se elas expirarem em 90 dias
```
{
"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"
}
}
}
]
}
```
## Chaves de API rotativas
A rotação regular de suas chaves de API reduz o risco de acesso não autorizado. Recomendamos estabelecer um cronograma de rotação que se alinhe às políticas de segurança da sua organização.
### Processo de rotação
Para alternar uma chave de API sem interromper a entrega do registro, siga este procedimento:
1. Crie uma nova credencial (secundária) para o usuário do IAM:
```
aws iam create-service-specific-credential \
--user-name cloudwatch-logs-hlc-user \
--service-name logs.amazonaws.com \
--credential-age-days 90
```
1. (Opcional) Armazene a nova credencial AWS Secrets Manager para recuperação segura e rotação automatizada.
1. Importe a nova credencial para o portal do seu fornecedor ou atualize a configuração do seu aplicativo para usar a nova chave de API.
1. Defina a credencial original como inativa:
```
aws iam update-service-specific-credential \
--user-name cloudwatch-logs-hlc-user \
--service-specific-credential-id ACCA1234EXAMPLE1234 \
--status Inactive
```
1. Verifique se a entrega de registros não é afetada monitorando a `IncomingBytes` métrica do seu grupo de registros em CloudWatch. Para obter mais informações, consulte [Monitoramento com CloudWatch métricas](https://docs.aws.amazon.com/AmazonCloudWatch/latest/logs/CloudWatch-Logs-Monitoring-CloudWatch-Metrics.html).
1. Depois de confirmar a entrega bem-sucedida com a nova chave, exclua a credencial anterior:
```
aws iam delete-service-specific-credential \
--service-specific-credential-id ACCA1234EXAMPLE1234
```
### Monitorando a expiração da chave
Para verificar a data de criação e o status de suas chaves de API existentes, use o [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
```
A resposta inclui `CreateDate` e `Status` para cada credencial. Use essas informações para identificar chaves que estão prestes a expirar ou que estão ativas há mais tempo do que sua política de rotação permite.
## Respondendo a uma chave de API comprometida
Se você suspeitar que uma chave de API foi comprometida, execute as seguintes etapas imediatamente:
1. **Desative a chave imediatamente** para evitar mais uso não autorizado:
```
aws iam update-service-specific-credential \
--user-name cloudwatch-logs-hlc-user \
--service-specific-credential-id ACCA1234EXAMPLE1234 \
--status Inactive
```
1. **Analise CloudTrail os registros** para determinar o escopo do acesso não autorizado. Veja [Registrando o uso da chave de API com CloudTrail](#CWL_HTTP_Endpoints_CloudTrail_Logging) como habilitar a auditoria do uso da chave de API.
1. **Crie uma chave de substituição** seguindo o processo de rotação descrito em[Processo de rotação](#CWL_HTTP_Endpoints_Rotation_Process).
1. **Exclua a chave comprometida** depois que a substituição estiver em vigor:
```
aws iam delete-service-specific-credential \
--service-specific-credential-id ACCA1234EXAMPLE1234
```
1. **Anexe uma política de negação** se precisar bloquear imediatamente todo o acesso ao token portador do usuário do IAM durante a investigação:
```
{
"Version": "2012-10-17",
"Statement": {
"Effect": "Deny",
"Action": "logs:CallWithBearerToken",
"Resource": "*"
}
}
```
**nota**
Para realizar essas ações por meio da API, você deve se autenticar com AWS credenciais e não com uma chave da API CloudWatch Logs.
Você também pode usar as seguintes operações de API do IAM para gerenciar chaves comprometidas:
+ [ResetServiceSpecificCredential](https://docs.aws.amazon.com/IAM/latest/APIReference/API_ResetServiceSpecificCredential.html)— Redefina a chave para gerar uma nova senha sem excluir a credencial. A chave não deve ter expirado.
## Práticas recomendadas de segurança para chaves de API
Siga estas práticas recomendadas para proteger suas chaves da API CloudWatch Logs:
+ **Nunca incorpore chaves de API no código-fonte.** Não codifique as chaves de API no código do aplicativo nem as comprometa com sistemas de controle de versão. Se uma chave for transferida acidentalmente para um repositório público, o escaneamento AWS automático pode sinalizá-la e você deve girar a chave imediatamente.
+ **Use um gerenciador de segredos.** Armazene as chaves de API em [AWS Secrets Manager](https://docs.aws.amazon.com/secretsmanager/latest/userguide/intro.html)uma solução de gerenciamento de segredos equivalente. Isso permite controle de acesso centralizado, registro de auditoria e rotação automatizada.
+ **Defina uma expiração para todas as chaves.** Sempre especifique um `--credential-age-days` valor ao criar chaves de API. Para impor uma vida útil máxima da chave em sua organização, use a chave de condição `iam:ServiceSpecificCredentialAgeDays` do IAM. Para ver um exemplo, consulte [Permita a criação de chaves de CloudWatch registros somente se elas expirarem em 90 dias](#CWL_HTTP_Endpoints_Allow_Expire_90).
+ **Aplique permissões com privilégios mínimos.** Defina o escopo das permissões do usuário do IAM somente para os grupos de registros e as ações necessárias. Use a política de [CloudWatchLogsAPIKeyacesso](https://docs.aws.amazon.com/aws-managed-policy/latest/reference/CloudWatchLogsAPIKeyAccess.html) gerenciado como ponto de partida e restrinja ainda mais conforme necessário.
+ **Ative o CloudTrail registro.** Audite o uso da chave da API ativando eventos de CloudTrail dados para`AWS::Logs::LogGroupAuthorization`. Consulte [Registrando o uso da chave de API com CloudTrail](#CWL_HTTP_Endpoints_CloudTrail_Logging).
+ **Monitore com o IAM Access Analyzer.** Use o [IAM Access Analyzer](https://docs.aws.amazon.com/IAM/latest/UserGuide/what-is-access-analyzer.html) para identificar credenciais não utilizadas e políticas excessivamente permissivas associadas aos usuários da chave de API do IAM.
+ **Gire as teclas regularmente.** Estabeleça um cronograma de rotação e siga o processo descrito em[Chaves de API rotativas](#CWL_HTTP_Endpoints_Rotating_Keys).
## Registrando o uso da chave de API com CloudTrail
Você pode usar AWS CloudTrail para registrar eventos de dados para o uso da chave da API CloudWatch Logs. CloudWatch O Logs emite eventos de `AWS::Logs::LogGroupAuthorization` dados para `CallWithBearerToken` chamadas, permitindo que você audite quando e como as chaves de API são usadas para enviar registros.
Para ativar o CloudTrail registro para o uso da chave da API CloudWatch Logs:
**nota**
O bucket do S3 que você especifica para a trilha deve ter uma política de bucket que permita CloudTrail gravar arquivos de log nele. Para obter mais informações, consulte a [política de bucket do Amazon S3](https://docs.aws.amazon.com/awscloudtrail/latest/userguide/create-s3-bucket-policy-for-cloudtrail.html) para. CloudTrail
1. Crie uma trilha:
```
aws cloudtrail create-trail \
--name cloudwatch-logs-api-key-audit \
--s3-bucket-name my-cloudtrail-bucket \
--region us-east-1
```
1. Configure seletores de eventos avançados para capturar eventos de autorização de grupos de CloudWatch registros 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 o registro de trilhas:
```
aws cloudtrail start-logging \
--name cloudwatch-logs-api-key-audit \
--region us-east-1
```
# Enviando registros usando o endpoint OTLP (OpenTelemetry Logs)
O endpoint do OpenTelemetry Logs (`/v1/logs`) aceita dados de log do OpenTelemetry Protocolo (OTLP) na codificação JSON ou Protobuf. Para obter informações detalhadas sobre o endpoint OTLP, incluindo configuração e uso, consulte [Enviar métricas e rastreamentos para com CloudWatch ](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/CloudWatch-OTLPEndpoint.html). OpenTelemetry
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.
## Formato de solicitação
+ Método: `POST`
+ Tipo de conteúdo: ou `application/json` `application/x-protobuf`
+ Grupo de registros: somente `x-aws-log-group` cabeçalho (parâmetro de consulta não suportado)
+ Fluxo de log: `x-aws-log-stream` cabeçalho
## Exemplo de solicitação
```
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" }
}
]
}
]
}
]
}
]
}'
```
## Respostas
**Sucesso (todos os eventos são aceitos):**
```
HTTP 200 OK
{}
```
**Sucesso parcial (alguns eventos foram rejeitados):**
```
{
"partialSuccess": {
"rejectedLogRecords": 5,
"errorMessage": "{\"tooOldLogEventCount\": 3, \"tooNewLogEventCount\": 1, \"expiredLogEventCount\": 1}"
}
}
```
Quando a solicitação Content-Type é`application/x-protobuf`, a resposta é retornada como uma mensagem `ExportLogsServiceResponse` protobuf serializada com os mesmos campos.
## Comportamentos específicos do OTLP
Os comportamentos a seguir são específicos do endpoint OTLP e não estão presentes nos outros endpoints de ingestão HTTP:
+ **Cabeçalho Retry-After** — Incluído nas respostas 503 e 429 para indicar quando o cliente deve tentar novamente.
# 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.
# Enviando registros usando o endpoint NDJSON (ND-JSON Logs)
O endpoint ND-JSON Logs (`/ingest/bulk`) aceita registros no formato [NDJSON (Newline Delimited JSON)](https://github.com/ndjson/ndjson-spec). Cada linha contém exatamente um valor JSON, separado por caracteres de nova linha.
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.
## Formato de solicitação
Envie um valor JSON por linha, separado por `\n` (LF) ou `\r\n` (CRLF). As linhas vazias são ignoradas silenciosamente.
```
{"timestamp":1771007942000,"message":"event one","level":"INFO"}
{"timestamp":1771007943000,"message":"event two","level":"ERROR"}
{"timestamp":1771007944000,"message":"event three","level":"DEBUG"}
```
Ambos `application/json` `application/x-ndjson` são aceitos como o tipo de conteúdo.
## Tipos de valores JSON aceitos
De acordo com a especificação NDJSON (RFC 8259), qualquer valor JSON válido é aceito em cada linha.
**Objetos JSON (mais comuns):**
```
{"timestamp":1771007942000,"message":"User logged in","service":"auth"}
{"timestamp":1771007943000,"error":"Connection timeout","service":"api"}
```
**Matrizes JSON (agrupadas em eventos individuais):**
```
[{"timestamp":1000,"message":"a"},{"timestamp":2000,"message":"b"}]
```
Essa única linha produz 2 eventos. Cada elemento da matriz se torna um evento de log separado.
**Valores primitivos:**
```
"a plain string log message"
42
true
null
```
Cada primitivo se torna seu próprio evento com a data e hora atual do servidor.
**Tipos mistos:**
```
{"timestamp":1771007942000,"message":"structured event"}
"unstructured string message"
42
{"timestamp":1771007943000,"error":"something failed"}
```
Todas as 4 linhas são aceitas como eventos válidos.
| Conteúdo da linha | Comportamento |
| --- | --- |
| Objeto JSON | Aceito, carimbo de data/hora extraído, se presente |
| matriz JSON | Achatado — cada elemento se torna um evento separado |
| Matriz vazia [] | Aceito, produz 0 eventos |
| Cadeia de caracteres JSON | Aceito como mensagem do evento |
| Número JSON | Aceito como mensagem do evento |
| Booleano JSON | Aceito como mensagem do evento |
| JSON nulo | Aceito como mensagem do evento |
| JSON inválido | Ignorado (contado, o processamento continua) |
| Linha vazia | Ignorado (não contado como ignorado) |
## Campo de carimbo de data/hora
O `"timestamp"` campo está em milissegundos de época (não segundos).
| Formato | Exemplo | Interpretada como |
| --- | --- | --- |
| Numérico (millis) | "timestamp":1771007942000 | 1771007942000 ms |
| Missing (Ausente) | (sem campo de carimbo de data/hora) | Hora atual do servidor |
| Não numérico | "timestamp":"invalid" | Hora atual do servidor |
| Linha sem objeto | "hello", 42, true | Hora atual do servidor |
## Linhas inválidas
As linhas que não são JSON válidas são ignoradas e contadas silenciosamente. O processamento continua com a próxima linha.
```
{"message":"valid event"}
this is not valid json
{"message":"another valid event"}
```
Resultado: 2 eventos ingeridos, 1 ignorado. Retorna `HTTP 200`.
Se todas as linhas forem inválidas, retorna `HTTP 400` com`"All events were invalid"`.
## Exemplo de solicitação
```
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"}'
```
## Respostas
**Sucesso (todos os eventos são aceitos):**
```
HTTP 200 OK
{}
```
**Sucesso parcial (alguns eventos foram rejeitados):**
```
{
"partialSuccess": {
"rejectedLogRecords": 5,
"errorMessage": "{\"tooOldLogEventCount\": 3, \"tooNewLogEventCount\": 1, \"expiredLogEventCount\": 1}"
}
}
```
O `rejectedLogRecords` campo é o número total de eventos rejeitados. O `errorMessage` campo contém um detalhamento codificado em JSON por motivo de rejeição:
+ `tooOldLogEventCount`— Eventos com carimbos de data/hora anteriores ao período de retenção
+ `tooNewLogEventCount`— Eventos com timestamps muito distantes no futuro
+ `expiredLogEventCount`— Eventos que expiraram durante o processamento
## 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.
# Envio de registros usando o endpoint JSON estruturado (Structured JSON Logs)
O endpoint (`/ingest/json`) do Structured JSON Logs aceita JSON padrão — um único objeto JSON ou uma matriz JSON de objetos. Esse endpoint foi projetado para dados de log estruturados em que cada evento é um objeto JSON.
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.
## Formato de solicitação
Só `application/json` é aceito como o tipo de conteúdo.
**Objeto JSON único:**
```
{"timestamp":1771007942000,"message":"single event","level":"INFO"}
```
**Matriz JSON de objetos:**
```
[
{"timestamp":1771007942000,"message":"event one","level":"INFO"},
{"timestamp":1771007943000,"message":"event two","level":"ERROR"}
]
```
## Tipos de valores JSON aceitos
Esse endpoint é estrito — somente objetos JSON são aceitos como eventos.
| Input | Comportamento |
| --- | --- |
| Objeto JSON único | Aceito como um evento |
| Matriz JSON de objetos | Cada objeto se torna um evento separado |
| Matriz vazia [] | Aceito, produz 0 eventos |
| Não objeto na matriz (string, número, etc.) | Ignorado |
| Primitivo de nível superior ("hello",) 42 | Ignorado |
| Objetos concatenados \$1...\$1\$1...\$1 | Somente o primeiro objeto analisado |
**Exemplo — matriz com tipos mistos:**
```
[
{"timestamp":1771007942000,"message":"valid object"},
"just a string",
42,
{"timestamp":1771007943000,"message":"another valid object"}
]
```
Resultado: 2 eventos ingeridos (os objetos), 2 ignorados (a string e o número).
## Campo de carimbo de data/hora
O `"timestamp"` campo está em milissegundos de época, o mesmo que o endpoint NDJSON.
| Formato | Exemplo | Interpretada como |
| --- | --- | --- |
| Numérico (millis) | "timestamp":1771007942000 | 1771007942000 ms |
| Missing (Ausente) | (sem campo de carimbo de data/hora) | Hora atual do servidor |
| Não numérico | "timestamp":"invalid" | Hora atual do servidor |
## Exemplo de solicitação
```
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"}]'
```
## Respostas
**Sucesso (todos os eventos são aceitos):**
```
HTTP 200 OK
{}
```
**Sucesso parcial (alguns eventos foram rejeitados):**
```
{
"partialSuccess": {
"rejectedLogRecords": 5,
"errorMessage": "{\"tooOldLogEventCount\": 3, \"tooNewLogEventCount\": 1, \"expiredLogEventCount\": 1}"
}
}
```
O `rejectedLogRecords` campo é o número total de eventos rejeitados. O `errorMessage` campo contém um detalhamento codificado em JSON por motivo de rejeição:
+ `tooOldLogEventCount`— Eventos com carimbos de data/hora anteriores ao período de retenção
+ `tooNewLogEventCount`— Eventos com timestamps muito distantes no futuro
+ `expiredLogEventCount`— Eventos que expiraram durante o processamento
## 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.
## Comparação dos endpoints de ingestão de HTTP
| Recurso | Registros do HLC | Registros ND-JSON | Registros JSON estruturados | OpenTelemetry Registros |
| --- | --- | --- | --- | --- |
| Path | /services/collector/event | /ingest/bulk | /ingest/json | /v1/logs |
| Content-Type | application/json | application/json ou application/x-ndjson | application/json | application/json ou application/x-protobuf |
| Campo de carimbo de data/hora | "time" (segundos) | "timestamp"(milissegundos) | "timestamp"(milissegundos) | "timeUnixNano"(nanossegundos) |
| Campos obrigatórios | "event" | Nenhum | Nenhum | Estrutura OTLP () "resourceLogs" |
| Resposta parcial de sucesso | Não | Sim | Sim | Sim |
| Suporte a parâmetros de consulta | Sim | Sim | Sim | Não (somente cabeçalhos) |
| Metadados da entidade | Sim | Sim | Sim | Não |
| Aceita primitivos | Não | Sim | Não | Não |
| Análise baseada em linha | Não | Sim | Não | Não |
| Suporte ao Protobuf | Não | Não | Não | Sim |
| Cabeçalho Retry-After | Não | Não | Não | Sim |
## Escolhendo um endpoint
+ **Usando o formato HLC?** Use os registros do HLC. Suas cargas úteis de HLC existentes funcionam com o mínimo de alterações.
+ ** line-by-lineRegistros de streaming?** Use registros ND-JSON. Ideal para pipelines de log que emitem um evento por linha. Mais flexível — aceita qualquer tipo de valor JSON.
+ **Enviando cargas JSON estruturadas?** Use registros JSON estruturados. Ideal para aplicativos que produzem objetos ou matrizes JSON bem formados.
+ **Já está usando OpenTelemetry?** Use OpenTelemetry registros. Aceita o formato OTLP JSON ou Protobuf e oferece suporte a respostas parciais de sucesso com semântica de repetição.