Logtail configuration API parameters - legacy reference - Simple Log Service: Central de Documentação do Alibaba Cloud

Uma configuração do Logtail define políticas de coleta de logs, como fonte de dados e modo de coleta. Este tópico descreve os parâmetros de API legados.

O CRD-AliyunLogConfig legado não recebe mais manutenção. Use AliyunPipelineConfig em seu lugar. CreateLogtailPipelineConfig - Create a Logtail pipeline configuration .

Parâmetros básicos

Parâmetro	Tipo	Obrigatório	Exemplo	Descrição
configName	string	Sim	config-sample	Nome da configuração do Logtail. Deve ser único no projeto e imutável após a criação. Regras de nomenclatura: Aceita apenas letras minúsculas, dígitos, hifens (-) e sublinhados (_). Deve começar e terminar com letra minúscula ou dígito. Deve ter entre 2 e 128 caracteres.
inputType	string	Sim	file	Tipo de fonte de dados. Valores válidos: plugin: Coleta logs por meio de plug-ins do Logtail (por exemplo, MySQL Binlog). file: Coleta logs de arquivos de texto em modo fixo (regex completo, delimitador, entre outros).
inputDetail	Objeto JSON	Sim	Nenhum	Configuração da fonte de dados. inputDetail parameters.
outputType	string	Sim	LogService	Destino de saída. Somente o LogService é compatível.
outputDetail	Objeto JSON	Sim	Nenhum	Configuração de saída de log. outputDetail parameters.
logSample	string	Não	Nenhum	Log de amostra. Nota O log de amostra deve ter menos de 1.500 bytes.

Parâmetros de inputDetail

Parâmetros básicos

Parâmetro	Tipo	Obrigatório	Exemplo	Descrição
filterKey	array	Não	["ip"]	Campos de filtro de log. O sistema coleta apenas logs correspondentes aos padrões de filterRegex. Nota Este parâmetro aplica-se apenas à coleta de logs de texto.
filterRegex	array	Não	["^10.*"]	Padrões regex para filterKey. O tamanho do array filterRegex deve corresponder ao de filterKey. Nota Este parâmetro aplica-se apenas à coleta de logs de texto.
shardHashKey	array	Não	["__source__"]	Modo de gravação de dados. Padrão: balanceamento de carga. Modo de balanceamento de carga (LoadBalance): Grava em qualquer shard gravável. Ideal para cenários sem requisitos de ordenação. Modo de shard (KeyHash): Roteia dados para um shard específico com base no campo Key nos parâmetros de URL. Retorna ao balanceamento de carga se não estiver definido. Garante ordenação estrita dentro de um shard durante mesclagem e divisão. Shards. Quando configurado, os dados são gravados no modo de shard. O campo __source__ é compatível.
enableRawLog	boolean	Não	false	Indica se os logs brutos devem ser enviados. true: Envia logs brutos. false (padrão): Não envia logs brutos.
sensitive_keys	array	Não	Nenhum	Configuração de mascaramento de dados. sensitive_keys parameters.
mergeType	string	Não	topic	Método de agregação. Valores válidos: topic (padrão): Agrega por tópico. logstore: Agrega por Logstore.
delayAlarmBytes	int	Não	209715200	Limiar de alerta para atraso na coleta. Padrão: 209715200 (200 MB).
adjustTimezone	boolean	Não	false	Indica se os fusos horários dos logs devem ser ajustados. Aplica-se apenas quando a análise de tempo está configurada (por exemplo, quando timeFormat está definido).
logTimezone	string	Não	GMT+08:00	Deslocamento de fuso horário. Formato: GMT+HH:MM (leste) ou GMT-HH:MM (oeste). Exemplo: GMT+08:00 para UTC+8.
advanced	Objeto JSON	Não	Nenhum	Configuração de recursos avançados. advanced parameters.

Parâmetros de sensitive_keys

Parâmetros

Parâmetro	Tipo	Obrigatório	Exemplo	Descrição
key	string	Sim	content	Nome do campo de log.
type	string	Sim	const	Método de mascaramento de dados. Valores válidos: const: Substitui o conteúdo sensível pelo valor do campo const. md5: Substitui o conteúdo sensível pelo hash MD5 correspondente.
regex_begin	string	Sim	'password':'	Prefixo regex para localizar conteúdo sensível. Usa sintaxe RE2.
regex_content	string	Sim	[^']*	Regex para o conteúdo sensível. Usa sintaxe RE2.
all	boolean	Sim	true	Indica se todo o conteúdo sensível no campo deve ser substituído. true (recomendado): Substitui todo o conteúdo sensível. false: Substitui apenas a primeira ocorrência.
const	string	Não	"****"	Este parâmetro é obrigatório se você definir type como const.

Exemplo de configuração
Por exemplo, se o valor do campo content em um log for [{'account':'1812213231432969','password':'04a23f38'}, {'account':'1812213685634','password':'123a'}], substitua o valor do campo password por **** definindo sensitive_keys da seguinte forma.
```
sensitive_keys = [{"all": true,
"const": "********",
"regex_content": "[^']*",
"regex_begin": "'password':'",
"type": "const",
"key": "content"}]                    
```

Log de amostra

[{'account':'1812213231432969','password':'********'}, {'account':'1812213685634','password':'********'}]

Parâmetros avançados

Parâmetro	Tipo	Obrigatório	Exemplo	Descrição
enable_root_path_collection	boolean	Não	false	Indica se a coleta a partir de diretórios raiz do Windows é permitida (por exemplo, D:\log). true: Permitido. false (padrão): Não permitido. Importante* Parâmetro global. Ative isso em qualquer configuração do Logtail permite que todas as configurações no servidor coletem de diretórios raiz até que o Logtail seja reiniciado. Este recurso é compatível apenas com o Logtail 1.0.0.22 para Windows e versões posteriores.
exactly_once_concurrency	int	Não	1	Ativa a gravação ExactlyOnce e defina o número de envios simultâneos por arquivo (0-512). Appendix: ExactlyOnce write feature. 0: Desativa o recurso de gravação ExactlyOnce. Outros valores: Ativa a gravação ExactlyOnce com a simultaneidade especificada por arquivo. Importante Valores maiores aumentam a sobrecarga de memória e disco. Defina com base no seu tráfego de gravação local. O Logtail realiza randomização local. Mesmo que este valor seja menor que a contagem de shards, o balanceamento de gravação ainda é garantido. Entra em vigor apenas para novos arquivos após a configuração. Este recurso é compatível apenas com o Logtail 1.0.21 e versões posteriores.
enable_log_position_meta	boolean	Não	true	Indica se metadados do arquivo de log devem ser adicionados (campos __tag__:__inode__ e __file_offset__). true: Adiciona os metadados. false: Não adiciona os metadados. Nota Este recurso é compatível apenas com o Logtail 1.0.21 e versões posteriores.
specified_year	uint	Não	0	Completa carimbos de data/hora de log sem o ano. Valores válidos: 0: Usa o ano atual. Um ano específico (por exemplo, 2020): Usa o ano especificado. Nota Este recurso é compatível apenas com o Logtail 1.0.21 e versões posteriores.
force_multiconfig	boolean	Não	false	Indica se esta configuração pode coletar arquivos já correspondidos por outras configurações. Padrão: false. Use para cenários de gravação múltipla em que duas configurações coletam um mesmo arquivo para Logstores diferentes.
raw_log_tag	string	Não	__raw__	Nome do campo para armazenar logs brutos. Padrão: __raw__.
blacklist	object	Não	Nenhum	Configuração de lista de bloqueios de coleta. blacklist parameters.
tail_size_kb	int	Não	1024	Tamanho inicial de coleta para novos arquivos, determinando a posição inicial de leitura. Padrão: 1024 KB. Arquivos menores que 1024 KB: a coleta começa do início. Arquivos maiores que 1024 KB: a coleta começa 1024 KB antes do final. Intervalo: 0-10485760 KB.
batch_send_interval	int	Não	3	Intervalo de envio de agregação em segundos. Padrão: 3.
max_rotate_queue_size	int	Não	20	Comprimento da fila de rotação de arquivo único. Padrão: 20.
enable_precise_timestamp	boolean	Não	false	Indica se o tempo de alta precisão deve ser extraído. Padrão: false. Quando ativado, o Logtail analisa o campo de tempo em um carimbo de data/hora no nível de milissegundos e o armazena no campo precise_timestamp_key. Nota O tempo do sistema deve estar desativado na configuração de coleta do Logtail. Este recurso é compatível apenas com o Logtail 1.0.32 e versões posteriores.
precise_timestamp_key	string	Não	"precise_timestamp"	Campo para armazenar o carimbo de data/hora de alta precisão. Padrão: precise_timestamp.
precise_timestamp_unit	string	Não	"ms"	Unidade do carimbo de data/hora de alta precisão. Padrão: ms. Valores válidos: ms (milissegundo), us (microssegundo), ns (nanossegundo).

A tabela a seguir descreve os parâmetros de blacklist.

Parâmetro	Tipo	Obrigatório	Exemplo	Descrição
dir_blacklist	array	Não	["/home/admin/dir1", "/home/admin/dir2*"]	Lista de bloqueios de diretórios (caminhos absolutos). Suporta curingas de asterisco (*). Por exemplo, se você configure o caminho como /home/admin/dir1, todo o conteúdo no diretório /home/admin/dir1 será ignorado durante a coleta.
filename_blacklist	array	Não	["app*.log", "password"]	Lista de bloqueios de nomes de arquivo. Os arquivos correspondentes são excluídos de todos os diretórios. Suporta curingas de asterisco (*).
filepath_blacklist	array	Não	["/home/admin/private*.log"]	Lista de bloqueios de caminhos de arquivo (caminhos absolutos). Suporta curingas de asterisco (). Se você configure o caminho como /home/admin/private.log, todos os arquivos no diretório /home/admin/ que começam com "private" e terminam com ".log" serão ignorados durante a coleta.

Configurações específicas para logs de texto

Parâmetros básicos

Parâmetro	Tipo	Obrigatório	Exemplo	Descrição
logType	string	Sim	common_reg_log	Modo de coleta de logs. Valores válidos: json_log: Modo JSON. common_reg_log: Modo regex completo. plugin: Modo plug-in. delimiter_log: Modo delimitador.
logPath	string	Sim	/var/log/http/	Caminho do diretório do arquivo de log.
filePattern	string	Sim	access*.log	Padrão de nome do arquivo de log.
topicFormat	string	Sim	none	Método de geração de tópico. Valores válidos: none: Não gera tópicos de log. default: Usa o caminho do arquivo de log como tópico do log. group_topic: Usa o tópico do grupo de máquinas como tópico do log. Regex de caminho de arquivo: Usa parte do caminho do arquivo de log como tópico. Exemplo: /var/log/(.*).log. Log topics.
timeFormat	string	Não	%Y/%m/%d %H:%M:%S	Formato de tempo do log. Time formats.
preserve	boolean	Não	true	Comportamento de tempo limite do arquivo de log. Valores válidos: true (padrão): Nunca expira. false: Expira após 30 minutos de inatividade. O arquivo deixa de ser monitorado.
preserveDepth	integer	Não	1	Profundidade máxima de diretório para tempo limite quando preserve é false. Intervalo: 1-3.
fileEncoding	string	Não	utf8	Codificação do arquivo de log. Valores válidos: utf8, gbk.
discardUnmatch	boolean	Não	true	Indica se logs sem correspondência devem ser descartados. Valores válidos: true: Descarta logs sem correspondência. false: Não descarta logs sem correspondência.
maxDepth	int	Não	100	Profundidade máxima do diretório de log monitorado (0-1.000). Um valor de 0 monitora apenas o diretório atual.
delaySkipBytes	int	Não	0	Limiar para descarte de dados atrasados. Valores válidos: 0 (padrão): Não descarta dados. Outros valores: Se o atraso na coleta exceder este valor (por exemplo, 1024 KB), os dados atrasados serão descartados.
dockerFile	boolean	Não	false	Indica se o arquivo alvo está dentro de um contêiner. Padrão: false.
dockerIncludeLabel	Objeto JSON	Não	Nenhum	Lista de permissões de rótulos de contêiner. Vazia por padrão (coleta de todos os contêineres). LabelKey é obrigatório; LabelValue é opcional. Se LabelValue estiver vazio, todos os contêineres com um rótulo que inclua o LabelKey serão correspondidos. Se LabelValue não estiver vazio, apenas contêineres com um rótulo LabelKey=LabelValue serão correspondidos. Por padrão, LabelValue é correspondido como uma string. Uma correspondência ocorre apenas se o LabelValue for idêntico ao valor do rótulo do contêiner. Se o valor começar com `^` e terminar com `$`, será tratado como uma expressão regular. Por exemplo, defina LabelKey como `io.kubernetes.container.name` e LabelValue como `^(nginx\|cube)$` para corresponder a contêineres chamados nginx ou cube. Nota Não defina o mesmo LabelKey várias vezes. Se houver duplicatas, apenas uma entrará em vigor. Várias entradas na lista de permissões têm uma relação OU. Um contêiner é correspondido se seu rótulo satisfizer qualquer uma das entradas da lista de permissões.
dockerExcludeLabel	Objeto JSON	Não	Nenhum	Lista de bloqueios de rótulos de contêiner. Vazia por padrão (nenhum contêiner excluído). LabelKey é obrigatório; LabelValue é opcional. Se LabelValue estiver vazio, todos os contêineres com um rótulo que inclua o LabelKey serão excluídos. Se LabelValue não estiver vazio, apenas contêineres com um rótulo LabelKey=LabelValue serão excluídos. Por padrão, LabelValue é correspondido como uma string. Uma correspondência ocorre apenas se o LabelValue for idêntico ao valor do rótulo do contêiner. Se o valor começar com `^` e terminar com `$`, será tratado como uma expressão regular. Por exemplo, defina LabelKey como `io.kubernetes.container.name` e LabelValue como `^(nginx\|cube)$` para corresponder a contêineres chamados nginx ou cube. Nota Não defina o mesmo LabelKey várias vezes. Se houver duplicatas, apenas uma entrará em vigor. Várias entradas na lista de bloqueios têm uma relação OU. Um contêiner é excluído se seu rótulo satisfizer qualquer um dos pares chave-valor da lista de bloqueios.
dockerIncludeEnv	Objeto JSON	Não	Nenhum	Lista de permissões de variáveis de ambiente. Vazia por padrão (coleta de todos os contêineres). EnvKey é obrigatório; EnvValue é opcional. Se EnvValue estiver vazio, todos os contêineres com uma variável de ambiente que inclua o EnvKey serão correspondidos. Se EnvValue não estiver vazio, apenas contêineres com uma variável de ambiente EnvKey=EnvValue serão correspondidos. Por padrão, EnvValue é correspondido como uma string. Uma correspondência ocorre apenas se o EnvValue for idêntico ao valor da variável de ambiente. Se o valor começar com `^` e terminar com `$`, será tratado como uma expressão regular. Por exemplo, defina EnvKey como `NGINX_SERVICE_PORT` e EnvValue como `^(80\|6379)$` para corresponder a contêineres com uma porta de service 80 ou 6379. Nota Várias entradas na lista de permissões têm uma relação OU. Um contêiner é correspondido se suas variáveis de ambiente satisfizerem qualquer uma das entradas da lista de permissões.
dockerExcludeEnv	Objeto JSON	Não	Nenhum	Lista de bloqueios de variáveis de ambiente. Vazia por padrão (nenhum contêiner excluído). EnvKey é obrigatório; EnvValue é opcional. Se EnvValue estiver vazio, todos os contêineres com uma variável de ambiente que inclua o EnvKey serão excluídos. Se EnvValue não estiver vazio, apenas contêineres com uma variável de ambiente EnvKey=EnvValue serão excluídos. Por padrão, EnvValue é correspondido como uma string. Uma correspondência ocorre apenas se o EnvValue for idêntico ao valor da variável de ambiente. Se o valor começar com `^` e terminar com `$`, será tratado como uma expressão regular. Por exemplo, defina EnvKey como `NGINX_SERVICE_PORT` e EnvValue como `^(80\|6379)$` para corresponder a contêineres com uma porta de service 80 ou 6379. Nota Várias entradas na lista de bloqueios têm uma relação OU. Um contêiner é excluído se suas variáveis de ambiente satisfizerem qualquer um dos pares chave-valor.

Parâmetros de modo regex completo e simples

Parâmetros

Parâmetro	Tipo	Obrigatório	Exemplo	Descrição
key	array	Sim	["content"]	Nomes de campos para o conteúdo bruto do log.
logBeginRegex	string	Não	.*	Regex para o início de uma entrada de log. Apenas uma única expressão regular é compatível. Para corresponder a vários formatos de início de linha, combine os padrões em uma única expressão regular usando o operador barra vertical (	).
regex	string	Não	(.*)	Regex para extração de campos.

Exemplo de configuração

{
    "configName": "logConfigName", 
    "outputType": "LogService", 
    "inputType": "file", 
    "inputDetail": {
        "logPath": "/logPath", 
        "filePattern": "*", 
        "logType": "common_reg_log", 
        "topicFormat": "default", 
        "discardUnmatch": false, 
        "enableRawLog": true, 
        "fileEncoding": "utf8", 
        "maxDepth": 10, 
        "key": [
            "content"
        ], 
        "logBeginRegex": ".*", 
        "regex": "(.*)"
    }, 
    "outputDetail": {
        "projectName": "test-project", 
        "logstoreName": "test-logstore"
    }
}

Parâmetros do modo JSON

Parâmetro	Tipo	Obrigatório	Exemplo	Descrição
timeKey	string	Não	time	Nome da chave do campo de tempo.

Parâmetros do modo delimitador

Parâmetros

Parâmetro	Tipo	Obrigatório	Exemplo	Descrição
separator	string	Não	,	Escolha o separador correspondente ao formato do seu log. Collect logs in delimiter mode.
quote	string	Sim	\	Caractere de aspas para envolver campos que contenham o separador. O conteúdo entre aspas é analisado como um único campo. Collect logs in delimiter mode.
key	array	Sim	[ "ip", "time"]	Nomes de campos para o conteúdo bruto do log.
timeKey	string	Sim	time	Campo da lista key a ser usado como campo de tempo.
autoExtend	boolean	Não	true	Indica se o envio deve ocorrer quando os campos divididos forem menores que as chaves configuradas. Por exemplo, um log é 11\|22\|33\|44\|55, o separador é uma barra vertical (\|) e o conteúdo do log é analisado em 11, 22, 33, 44 e 55. As chaves são definidas como A, B, C, D e E, respectivamente. true: Ao coletar o log 11\|22\|33\|55, 55 é enviado ao Simple Log Service como o valor para a chave D. false: Ao coletar o log 11\|22\|33\|55, esta entrada de log é descartada porque o número de campos não corresponde ao número de chaves.

Exemplo de configuração

{
    "configName": "logConfigName", 
    "logSample": "testlog", 
    "inputType": "file", 
    "outputType": "LogService", 
    "inputDetail": {
        "logPath": "/logPath", 
        "filePattern": "*", 
        "logType": "delimiter_log", 
        "topicFormat": "default", 
        "discardUnmatch": true, 
        "enableRawLog": true, 
        "fileEncoding": "utf8", 
        "maxDepth": 999, 
        "separator": ",", 
        "quote": "\"", 
        "key": [
            "ip", 
            "time"
        ], 
        "autoExtend": true
    }, 
    "outputDetail": {
        "projectName": "test-project", 
        "logstoreName": "test-logstore"
    }
}

Parâmetros do modo plug-in

Parâmetros

Parâmetros para coleta de logs via plug-in do Logtail.

Parâmetro	Tipo	Obrigatório	Exemplo	Descrição
plugin	Objeto JSON	Sim	Nenhum	Obrigatório para coleta de logs baseada em plug-ins. Use Logtail plug-ins to collect data.

Exemplo de configuração

{
    "configName": "logConfigName", 
    "outputType": "LogService", 
    "inputType": "plugin",
    "inputDetail": {
        "plugin": {
            "inputs": [
                {
                    "detail": {
                        "ExcludeEnv": null, 
                        "ExcludeLabel": null, 
                        "IncludeEnv": null, 
                        "IncludeLabel": null, 
                        "Stderr": true, 
                        "Stdout": true
                    }, 
                    "type": "service_docker_stdout"
                }
            ]
        }
    }, 
    "outputDetail": {
        "projectName": "test-project", 
        "logstoreName": "test-logstore"
    }
}

Parâmetros de outputDetail

Parâmetros de projeto e Logstore de destino.

Parâmetro	Tipo	Obrigatório	Exemplo	Descrição
projectName	string	Sim	my-project	Nome do projeto. Deve corresponder ao projeto na solicitação.
logstoreName	string	Sim	my-logstore	Nome do Logstore.

Apêndice: Recurso de gravação ExactlyOnce

Quando ativado, o Logtail registra checkpoints no nível do arquivo em disco e usa números de sequência incrementais do SLS para evitar gravações duplicadas. Após erros de processo ou reinicializações, os checkpoints determinam o escopo de reprocessamento por arquivo. Isso aumenta a sobrecarga de gravação em disco. Limitações:

Os checkpoints são armazenados no disco local. Se o disco estiver cheio ou corrompido, a recuperação poderá falhar.
Os checkpoints registram apenas metadados do arquivo. Se o arquivo for excluído ou modificado, a recuperação poderá não ser possível.
O ExactlyOnce depende de números de sequência de gravação no SLS. Cada shard suporta no máximo 10.000 registros. Se esse limite for excedido, os registros mais antigos serão substituídos. Para garantir confiabilidade, mantenha Número de arquivos ativos × Número de instâncias do Logtail por Logstore abaixo de 9.500.
- Arquivos ativos: Arquivos sendo lidos e enviados. Arquivos rotacionados com o mesmo nome lógico contam como um único arquivo ativo.
- Instâncias do Logtail: Número de processos do Logtail. Normalmente um por servidor.

O Logtail não chama sync para gravações de checkpoint por padrão. Se o servidor reiniciar antes que os dados em buffer cheguem ao disco, os checkpoints poderão ser perdidos. Para ativar gravações síncronas, adicione "enable_checkpoint_sync_write": true, ao arquivo de configuração de inicialização do Logtail (/usr/local/ilogtail/ilogtail_config.json). Set Logtail startup parameters.