logstash-input-oss plugin - Elasticsearch: Central de Documentação do Alibaba Cloud

O plug-in logstash-input-oss conecta o Alibaba Cloud Logstash ao Object Storage Service (OSS) por meio do Simple Message Queue (antigo MNS) (SMQ). Quando um objeto do OSS é atualizado, o SMQ envia uma notificação ao plug-in, que aciona o Logstash para ler os dados mais recentes do OSS.

O logstash-input-oss é um plug-in de código aberto. Para obter mais informações, consulte o repositório no GitHub .

Como funciona

Um objeto do OSS é criado ou atualizado (por exemplo, via PutObject ou AppendObject).
O OSS envia uma notificação de evento para uma fila do SMQ.
O plug-in recebe a notificação do SMQ e extrai a chave do objeto.
O Logstash lê todos os dados do objeto e os envia para o destino seguinte pelo pipeline.

Observações de uso

Após receber uma notificação do SMQ, o Logstash sincroniza todos os dados do objeto associado, não apenas as alterações incrementais.
Objetos no formato .gz ou .gzip são processados como gzip. Todos os outros formatos são tratados como texto simples.
A leitura de objetos em formatos binários (como .jar ou .bin) pode resultar em caracteres ilegíveis.

Pré-requisitos

Antes de começar, verifique se você:

Instale o plug-in logstash-input-oss. Consulte Instalar ou remover um plug-in do Logstash.
Ative o OSS e o SMQ, com buckets do OSS na mesma região das filas ou tópicos do SMQ. Consulte Ativar o OSS e Ativar o SMQ e autorizar usuários RAM a acessar o SMQ.
Configure regras de notificação de eventos no OSS. Consulte Configurar regras de notificação de eventos.

Crie um pipeline

Crie um pipeline usando arquivos de configuração conforme descrito em Usar arquivos de configuração para gerencie pipelines. Configure os parâmetros na seção Parâmetros, salve e implante o pipeline.

O exemplo a seguir lê dados de um bucket do OSS e os grava no Alibaba Cloud Elasticsearch.

input {
  oss {
    endpoint => "oss-cn-hangzhou-internal.aliyuncs.com"
    bucket => "zl-ossou****"
    access_key_id => "******"
    access_key_secret => "*********"
    prefix => "file-sample-prefix"
    mns_settings => {
      endpoint => "******.mns.cn-hangzhou-internal.aliyuncs.com"
      queue => "aliyun-es-sample-mns"
    }
    codec => json {
      charset => "UTF-8"
    }
  }
}

output {
  elasticsearch {
    hosts => ["http://es-cn-***.elasticsearch.aliyuncs.com:9200"]
    index => "aliyun-es-sample"
    user => "elastic"
    password => "changeme"
  }
}

Importante

O endpoint do SMQ deve ser interno e não deve ter o prefixo http. O uso de um endpoint externo causa erro.

Parâmetros

Parâmetros obrigatórios

Parâmetro	Tipo	Descrição
`endpoint`	string	Endpoint usado para acessar o OSS. Consulte Regiões, endpoints e portas abertas.
`bucket`	string	Nome do bucket do OSS.
`access_key_id`	string	AccessKey ID da sua conta Alibaba Cloud.
`access_key_secret`	string	AccessKey secret da sua conta Alibaba Cloud.
`mns_settings`	hash	Configuração do SMQ. Consulte Subparâmetros de mns_settings.

Parâmetros opcionais

Parâmetro	Tipo	Padrão	Descrição
`prefix`	string	—	Filtra objetos pelo prefixo do nome. O Logstash lê apenas objetos cujos nomes começam com esse valor. Não é uma expressão regular. Use este parâmetro para ler de diretórios específicos no bucket.
`additional_oss_settings`	hash	—	Configurações adicionais do cliente OSS. Subparâmetros suportados: `secure_connection_enabled` (ativa conexões seguras) e `max_connections_to_oss` (número máximo de conexões com o OSS).
`delete`	boolean	`false`	Defina se os objetos processados devem ser exclua do bucket de source do OSS após a leitura.
`backup_to_bucket`	string	—	Nome do bucket do OSS para onde os objetos processados serão copiados como backup.
`backup_to_dir`	string	—	Diretório local para onde os arquivos processados serão copiados como backup.
`backup_add_prefix`	string	—	Prefixo adicionado à chave do objeto após o processamento. A chave é o caminho completo, incluindo o nome do objeto no OSS. Use este parâmetro para armazenar backups em uma pasta específica dentro do mesmo bucket ou de outro diferente.
`include_object_properties`	boolean	—	Indica se as propriedades do objeto OSS (`last_modified`, `content_type` e `metadata`) devem ser incluídas em `[@metadata][oss]`. Se não definido, apenas `[@metadata][oss][key]` estará disponível.
`exclude_pattern`	string	—	Expressão regular Ruby correspondente às chaves de objeto a serem ignoradas. Por exemplo, `"\/logs\/debug\/"` exclui todos os objetos com `/logs/debug/` no caminho.

Subparâmetros de mns_settings

Subparâmetro	Obrigatório	Padrão	Descrição
`endpoint`	Sim	—	Endpoint do SMQ. Deve ser um endpoint interno e não incluir `http`.
`queue`	Sim	—	Nome da fila do SMQ.
`poll_interval_seconds`	Não	`10`	Tempo máximo de espera (em segundos) para uma solicitação ReceiveMessage quando a fila está vazia. Consulte ReceiveMessage.
`wait_seconds`	Não	—	Tempo máximo de espera de sondagem (em segundos) para uma solicitação ReceiveMessage.

Metadados do objeto

Quando include_object_properties está ativado, o plug-in expõe os seguintes campos em [@metadata][oss]. Use esses campos nas etapas de filtro ou saída para enriquecer eventos ou aplicar lógica condicional.

Campo	Tipo	Descrição
`[@metadata][oss][key]`	string	Chave completa do objeto (caminho) no OSS. Sempre disponível, independentemente de `include_object_properties`.
`[@metadata][oss][last_modified]`	string	Carimbo de data/hora da última modificação do objeto. Disponível quando `include_object_properties` é `true`.
`[@metadata][oss][content_type]`	string	Tipo MIME do objeto. Disponível quando `include_object_properties` é `true`.
`[@metadata][oss][metadata]`	hash	Metadados personalizados definidos pelo usuário anexados ao objeto. Disponível quando `include_object_properties` é `true`.

Perguntas frequentes

Por que o plug-in usa o SMQ em vez de consultar o OSS diretamente?

Os eventos de atualização de objetos do OSS integram-se perfeitamente ao SMQ, tornando a notificação baseada em mensagens a escolha natural. A alternativa — usar a API ListObjects — exige rastrear quais objetos foram ou não processados no armazenamento local. À medida que o número de objetos aumenta, o desempenho do ListObjects degrada. O ecossistema mais amplo de armazenamento de objetos (incluindo a comunidade de código aberto do Amazon S3) também abandonou o ListObjects em favor de mecanismos de notificação por mensagens.

O que acontece se o Logstash for acionado enquanto o OSS ainda está gravando dados em um objeto?

O plug-in registra na fila do SMQ quais objetos foram gravados e os transmite pelo pipeline do Logstash. Quaisquer dados ainda não gravados no OSS continuam sendo escritos. Na próxima vez que o Logstash for acionado, o plug-in lerá os dados restantes do OSS.

Elasticsearch:Uso do plug-in logstash-input-oss