Ingestão de registros por meio de endpoints HTTP - CloudWatch Registros da Amazon
Comportamento comumComparação dos endpoints de ingestão de HTTPEscolhendo um endpoint

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 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 /v1/logs application/json ou application/x-protobuf OTLP JSON ou Protobuf
HLC Logs /services/collector/event application/json Formato HLC
ND-JSON Logs /ingest/bulk application/json ou application/x-ndjson JSON delimitado por Newline
Structured JSON Logs /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 <ACWL token> cabeçalho.

Grupo de registros e fluxo de registros

  • Fornecido por meio de cabeçalhos: x-aws-log-group e x-aws-log-stream

  • ?logGroup=<name>&logStream=<name>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

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.