# `logging.handlers` — Manipuladores de logging

Código-fonte: Lib/logging/handlers.py

Os seguintes tratadores úteis são fornecidos neste pacote. Observe que três dos tratadores (`StreamHandler`, `FileHandler` e `NullHandler`) são, na verdade, definidos no próprio módulo `logging`, mas foram documentados aqui junto com os outros tratadores.

## StreamHandler

A classe `StreamHandler` localizada no pacote principal `logging`, envia a saída de log para fluxos como sys.stdout, sys.stderr ou qualquer objeto arquivo ou similar (ou, mais precisamente, qualquer objeto que provê os métodos `write()` e `flush()`).

class logging.StreamHandler(stream=None)

  Retorna uma nova instância da classe `StreamHandler` Se stream for especificado, a instância irá utilizá-lo para a saída de log; caso contrário, sys.stderr será usado.

  emit(record)

    Se um formatador for especificado, ele será usado para formatar o registro. Em seguida, o registro é escrito no fluxo, seguido por `terminator` Se houver informações de exceção, elas são formatadas usando `traceback.print_exception()` e anexadas ao fluxo.

  flush()

    Esvazia o fluxo chamando seu método `flush()`. Observe que o método `close()` é herdado de `Handler` e, portanto, não produz nenhuma saída, de modo que uma chamada explícita a `flush()` pode ser necessária em alguns casos.

  setStream(stream)

    Define o fluxo da instância para o valor especificado, caso seja diferente. O fluxo antigo é esvaziado antes que o novo fluxo seja definido.

    Parâmetros:

      stream – O fluxo que o manipulador deve usar.

    Retorna:

      o fluxo antigo, se o fluxo tiver sido alterado, ou `None`, se não tiver sido.

    Adicionado na versão 3.7.

  terminator

    String usada como terminador ao gravar um registro formatado em um fluxo. O valor padrão é `'\n'`.

    Se você não quiser uma terminação com nova linha, pode definir o atributo `terminator` da instância do manipulador como uma string vazia.

    Nas versões anteriores, o terminador era codificado diretamente como `'\n'`.

    Adicionado na versão 3.2.

## FileHandler

A classe `FileHandler`, localizada no pacote principal `logging`, envia a saída de logging para um arquivo em disco. Ela herda a funcionalidade de saída da classe `StreamHandler`.

class logging.FileHandler(filename, mode='a', encoding=None, delay=False, errors=None)

  Retorna uma nova instância da classe `FileHandler`. O arquivo especificado é aberto e usado como o fluxo para logging. Se mode não for especificado, `'a'` é usado. Se encoding não for `None`, ele é usado para abrir o arquivo com essa codificação. Se delay for verdadeiro, então a abertura do arquivo é adiada até a primeira chamada de `emit()` Por padrão, o arquivo cresce indefinidamente. Se errors for especificado, ele é usado para determinar como os erros de codificação serão tratados.

  Alterado na versão 3.6: Além de valores do tipo string, objetos `Path` também são aceitos para o argumento filename.

  Alterado na versão 3.9: O parâmetro errors foi adicionado.

  close()

    Fecha o arquivo.

  emit(record)

    Envia o registro para o arquivo.

    Observe que, se o arquivo tiver sido fechado devido ao encerramento do sistema de logging na saída e o modo do arquivo for ‘w’, o registro não será emitido (veja bpo-42378).

## NullHandler

Adicionado na versão 3.1.

A classe `NullHandler`, localizada no pacote principal `logging`, não realiza qualquer formatação ou saída. Ela é essencialmente um manipulador ‘no-op’, destinado ao uso por desenvolvedores de bibliotecas.

class logging.NullHandler

  Retorna uma nova instância da classe `NullHandler`.

  emit(record)

    Esse método não faz nada.

  handle(record)

    Esse método não faz nada.

  createLock()

    Este método retorna `None` para a trava, pois não há E/S subjacente cujo acesso precise ser serializado.

Consulte Configurando logging para uma biblioteca para obter mais informações sobre como usar `NullHandler`.

## WatchedFileHandler

A classe `WatchedFileHandler`, localizada no módulo `logging.handlers`, é um `FileHandler` que monitora o arquivo no qual está registrando logs. Se o arquivo for alterado, ele é fechado e reaberto usando o nome do arquivo.

Uma alteração no arquivo pode ocorrer devido ao modo de usar de programas como newsyslog e logrotate, que realizam a rotação de arquivos de log. Este manipulador, destinado ao uso em Unix/Linux, monitora o arquivo para verificar se ele foi alterado desde a última chamada a emit. (Considera-se que um arquivo foi alterado se o seu dispositivo ou nó-i tiverem mudado.) Se o arquivo tiver sido alterado, o fluxo do arquivo antigo é fechado, e o arquivo é aberto novamente para obter um novo fluxo.

Este manipulador não é apropriado para uso no Windows, porque, nesse sistema, arquivos de log abertos não podem ser movidos ou renomeados — o logging abre os arquivos com travas exclusivas — e, portanto, não há necessidade desse tipo de manipulador. Além disso, ST_INO não é suportado no Windows; `stat()` sempre retorna zero para esse valor.

class logging.handlers.WatchedFileHandler(filename, mode='a', encoding=None, delay=False, errors=None)

  Retorna uma nova instância da classe `WatchedFileHandler`. O arquivo especificado é aberto e usado como o fluxo para registro de logs. Se mode não for especificado, `'a'` será usado. Se encoding não for `None`, ele será usado para abrir o arquivo com essa codificação. Se delay for verdadeiro, a abertura do arquivo é adiada até a primeira chamada a `emit()`. Por padrão, o arquivo cresce indefinidamente. Se errors for fornecido, ele determina como erros de codificação são tratados.

  Alterado na versão 3.6: Além de valores do tipo string, objetos `Path` também são aceitos para o argumento filename.

  Alterado na versão 3.9: O parâmetro errors foi adicionado.

  reopenIfNeeded()

    Verifica se o arquivo foi alterado. Se tiver sido, o fluxo existente é descarregado e fechado, e o arquivo é aberto novamente, normalmente como um passo preliminar antes de enviar o registro para o arquivo.

    Adicionado na versão 3.6.

  emit(record)

    Emite o registro para o arquivo, mas antes chama `reopenIfNeeded()` para reabrir o arquivo caso ele tenha sido alterado.

## BaseRotatingHandler

A classe `BaseRotatingHandler`, localizada no módulo `logging.handlers`, é a classe base para os tratadores de arquivos com rotação, `RotatingFileHandler` e `TimedRotatingFileHandler` Em geral, não é necessário instanciar essa classe, mas ela possui atributos e métodos que podem precisar ser substituídos.

class logging.handlers.BaseRotatingHandler(filename, mode, encoding=None, delay=False, errors=None)

  Os parâmetros são os mesmos de `FileHandler`. Os atributos são:

  namer

    Se esse atributo for definido como um chamável, o método `rotation_filename()` delega a ele. Os parâmetros passados ao chamável são os mesmos passados para `rotation_filename()`.

    Nota

    A função namer é chamada muitas vezes durante a rotação, portanto deve ser a mais simples e rápida possível. Ela também deve retornar sempre o mesmo resultado para uma dada entrada; caso contrário, o comportamento da rotação pode não funcionar como esperado.

    Também vale observar que é preciso ter cuidado ao usar um namer para preservar certos atributo no nome do arquivo que são usados durante a rotação. Por exemplo, `RotatingFileHandler` espera ter um conjunto de arquivos de log cujos nomes contenham inteiros sucessivos, para que a rotação funcione como esperado, e `TimedRotatingFileHandler` remova arquivos de log antigos (com base no parâmetro `backupCount` passado ao inicializador do manipulador) determinando quais são os arquivos mais antigos a serem excluídos. Para que isso funcione, os nomes dos arquivos devem ser ordenáveis usando a porção de data/hora do nome, e um namer precisa respeitar isso. (Se for desejado um namer que não respeite esse esquema, ele deverá ser usado em uma subclasse de `TimedRotatingFileHandler` que substitua o método `getFilesToDelete()` para se adequar ao esquema de nomeação personalizado.)

    Adicionado na versão 3.3.

  rotator

    Se este atributo estiver definido como um chamável, o método `rotate()` delega a esse chamável. Os parâmetros passados ao chamável são os mesmos passados para `rotate()`.

    Adicionado na versão 3.3.

  rotation_filename(default_name)

    Modifica o nome do arquivo de log durante a rotação.

    Isso é fornecido para que um nome de arquivo personalizado possa ser providenciado.

    A implementação padrão chama o atributo namer do manipulador, se ele for chamável, passando o nome padrão para ele. Se o atributo não for chamável (o padrão é `None`), o nome é devolvido sem alterações.

    Parâmetros:

      default_name – O nome padrão para o arquivo de log.

    Adicionado na versão 3.3.

  rotate(source, dest)

    Quando ocorre a rotação, rotaciona o log atual.

    A implementação padrão chama o atributo rotator do manipulador, se ele for chamável, passando os argumentos source e dest para ele. Se o atributo não for chamável (o padrão é `None`), o arquivo de origem é simplesmente renomeado para o destino.

    Parâmetros:

      - source – O nome do arquivo de origem. Normalmente, este é o nome base do arquivo, por exemplo, ‘test.log’.

      - dest – O nome do arquivo de destino. Normalmente, é para onde o arquivo de origem é rotacionado, por exemplo, ‘test.log.1’.

    Adicionado na versão 3.3.

O motivo da existência desses atributos é evitar que você precise criar subclasses — é possível usar os mesmos chamáveis para instâncias de `RotatingFileHandler` e `TimedRotatingFileHandler`. Se o chamável namer ou rotator levantar uma exceção, ela será tratada da mesma forma que qualquer outra exceção durante uma chamada a `emit()`, isto é, por meio do método `handleError()` do manipulador.

Se precisar fazer alterações mais significativas no processamento de rotação, você pode substituir os métodos.

Para um exemplo, consulte Using a rotator and namer to customize log rotation processing.

## RotatingFileHandler

A classe `RotatingFileHandler`, localizada no módulo `logging.handlers`, oferece suporte à rotação de arquivos de log em disco.

class logging.handlers.RotatingFileHandler(filename, mode='a', maxBytes=0, backupCount=0, encoding=None, delay=False, errors=None)

  Retorna uma nova instância da classe `RotatingFileHandler`. O arquivo especificado é aberto e usado como o stream para logging. Se mode não for especificado, `'a'` é usado. Se encoding não for `None`, ele é usado para abrir o arquivo com essa codificação. Se delay for verdadeiro, a abertura do arquivo é adiada até a primeira chamada a `emit()`. Por padrão, o arquivo cresce indefinidamente. Se errors for fornecido, ele é usado para determinar como erros de codificação são tratados.

  Você pode usar os valores maxBytes e backupCount para permitir que o arquivo faça rollover em um tamanho predeterminado. Quando o tamanho está prestes a ser excedido, o arquivo é fechado e um novo arquivo é aberto silenciosamente para saída. A rotação ocorre sempre que o arquivo de log atual está próximo de maxBytes em comprimento; mas, se maxBytes ou backupCount for zero, a rotação nunca ocorre, portanto, em geral, você deve definir backupCount como pelo menos 1 e usar um maxBytes diferente de zero. Quando backupCount é diferente de zero, o sistema salva arquivos de log antigos acrescentando as extensões ‘.1’, ‘.2’ etc. ao nome do arquivo. Por exemplo, com um backupCount de 5 e um nome de arquivo base `app.log`, você terá `app.log`, `app.log.1`, `app.log.2`, até `app.log.5`. O arquivo no qual se escreve é sempre `app.log`. Quando esse arquivo é preenchido, ele é fechado e renomeado para `app.log.1` e, se existirem os arquivos `app.log.1`, `app.log.2` etc., eles são renomeados para `app.log.2`, `app.log.3` etc., respectivamente.

  Alterado na versão 3.6: Além de valores do tipo string, objetos `Path` também são aceitos para o argumento filename.

  Alterado na versão 3.9: O parâmetro errors foi adicionado.

  doRollover()

    Realiza uma rotação, conforme descrito acima.

  emit(record)

    Grava o registro no arquivo, tratando a rotação conforme descrito anteriormente.

  shouldRollover(record)

    Verifica se o registro fornecido faria o arquivo exceder o limite de tamanho configurado.

## TimedRotatingFileHandler

A classe `TimedRotatingFileHandler`, localizada no módulo `logging.handlers`, oferece suporte à rotação de arquivos de log em disco em intervalos de tempo determinados.

class logging.handlers.TimedRotatingFileHandler(filename, when='h', interval=1, backupCount=0, encoding=None, delay=False, utc=False, atTime=None, errors=None)

  Retorna uma nova instância da classe `TimedRotatingFileHandler`. O arquivo especificado é aberto e usado como fluxo para o logging. Durante a rotação, o sufixo do nome do arquivo também é definido. A rotação ocorre com base no produto de when e interval.

  Você pode usar o when para especificar o tipo de intervalo. A lista de possíveis valores está abaixo. Observe que eles não diferenciam maiúsculas de minúsculas.

  Valor | Tipo de intervalo | Se/como atTime é usado
  --- | --- | ---
  `'S'` | Segundos | Ignorado
  `'M'` | Minutos | Ignorado
  `'H'` | Horas | Ignorado
  `'D'` | Dias | Ignorado
  `'W0'-'W6'` | Dia da semana (0=Segunda) | Usado para calcular o tempo inicial de rotação
  `'midnight'` | Faz a rotação à meia-noite, se atTime não for especificado; caso contrário, no horário atTime. | Usado para calcular o tempo inicial de rotação

  Ao usar rotação baseada em dia da semana, especifique ‘W0’ para segunda-feira, ‘W1’ para terça-feira, e assim por diante até ‘W6’ para domingo. Nesse caso, o valor passado para interval não é utilizado.

  O sistema salvará arquivos de log antigos acrescentando extensões ao nome do arquivo. As extensões são baseadas em data e hora, usando o formato strftime `%Y-%m-%d_%H-%M-%S` ou uma porção inicial dele, dependendo do intervalo de rollover.

  Quando a próximo rotação é calculada pela primeira vez (no momento em que o manipulador é criado), o tempo da última modificação de um arquivo de log existente — ou, caso contrário, o tempo atual — é usado para determinar quando a próxima rotação ocorrerá.

  Se o argumento utc for verdadeiro, serão usados horários em Horário Universal Coordenado (UTC); caso contrário, será usado o horário local.

  Se backupCount for diferente de zero, no máximo backupCount arquivos serão mantidos, e, se mais arquivos fossem criados quando ocorrer a rotação, o mais antigo será excluído. A lógica de exclusão usa o interval para determinar quais arquivos devem ser removidos; assim, alterar o intervalo pode deixar arquivos antigos remanescentes.

  Se delay for verdadeiro, a abertura do arquivo será adiada até a primeira chamada para `emit()`.

  Se atTime não for `None`, ele deve ser uma instância de `datetime.time` que especifica a hora do dia em que ocorre a rotação, nos casos em que a rotação está configurada para acontecer “à meia-noite” ou “em um determinado dia da semana”. Observe que, nesses casos, o valor de atTime é efetivamente usado para calcular a rotação inicial, e as rotações subsequentes são calculadas por meio do cálculo normal do intervalo.

  Se erros for especificado, ele será usado para determinar como erros de codificação são tratados.

  Nota

  O cálculo do tempo da rotação inicial é feito quando o manipulador é inicializado. O cálculo dos tempos de rotações subsequentes é feito apenas quando ocorre uma rotação, e a rotação ocorre somente quando há emissão de saída. Se isso não for levado em consideração, pode causar alguma confusão. Por exemplo, se for definido um intervalo de “a cada minuto”, isso não significa que você sempre verá arquivos de log com horários (no nome do arquivo) separados por um minuto; se, durante a execução da aplicação, a saída de log for gerada com maior frequência do que uma vez por minuto, então você pode esperar observar arquivos de log com horários separados por um minuto. Se, por outro lado, as mensagens de log forem emitidas apenas uma vez a cada cinco minutos (por exemplo), então haverá lacunas nos horários dos arquivos correspondentes aos minutos em que não houve saída (e, portanto, nenhuma rotação).

  Alterado na versão 3.4: parâmetro atTime foi adicionado.

  Alterado na versão 3.6: Além de valores do tipo string, objetos `Path` também são aceitos para o argumento filename.

  Alterado na versão 3.9: O parâmetro errors foi adicionado.

  doRollover()

    Realiza uma rotação, conforme descrito acima.

  emit(record)

    Emite o registro para o arquivo, com a preparação para a rotação, conforme descrito acima.

  getFilesToDelete()

    Retorna uma lista de nomes de arquivos que devem ser excluídos como parte da rotação. Esses são os caminhos absolutos dos arquivos de log de backup mais antigos gravados pelo manipulador.

  shouldRollover(record)

    Verifica se passou tempo suficiente para que a rotação ocorra e, se for o caso, calcula o próximo horário da rotação.

## SocketHandler

A classe `SocketHandler`, localizada no módulo `logging.handlers`, envia a saída de logging para um soquete de rede. A classe base utiliza um soquete TCP.

class logging.handlers.SocketHandler(host, port)

  Retorna uma nova instância da classe `SocketHandler`, destinada a se comunicar com uma máquina remota cujo endereço é fornecido por host e port.

  Alterado na versão 3.4: Se `port` for especificado como `None`, um Soquete de domínio Unix será criado usando o valor em `host` - caso contrário, um soquete TCP será criado.

  close()

    Fecha o soquete.

  emit()

    Serializa com pickle o dicionário de atributos do registro e o grava no soquete em formato binário. Se houver um erro com o soquete, o pacote é descartado silenciosamente. Se a conexão tiver sido perdida anteriormente, ela é restabelecida. Para desserializar com pickle o registro no lado receptor em um `LogRecord`, use a função `makeLogRecord()`.

  handleError()

    Trata um erro ocorrido durante `emit()`. A causa mais provável é a perda da conexão. Fecha o soquete para que seja possível tentar novamente no próximo evento.

  makeSocket()

    Este é um método de fábrica que permite que subclasses definam o tipo exato de soquete que desejam. A implementação padrão cria um soquete TCP (`socket.SOCK_STREAM`).

  makePickle(record)

    Serializa com pickle o dicionário de atributos do registro em formato binário com um prefixo de comprimento e o retorna pronto para transmissão através do socket. Os detalhes dessa operação são equivalentes a:

        data = pickle.dumps(record_attr_dict, 1)
        datalen = struct.pack('>L', len(data))
        return datalen + data

    Observe que os pickles não são completamente seguros. Se você estiver preocupado com a segurança, pode ser necessário substituir este método para implementar um mecanismo mais seguro. Por exemplo, você pode assinar os pickles usando HMAC e depois verificá-los no lado receptor, ou alternativamente pode desativar a desserialização com pickle de objetos globais no lado receptor.

  send(packet)

    Envia para o soquete uma string de bytes serializada com pickle denominada packet. O formato da string de bytes enviada é o descrito na documentação de `makePickle()`.

    Este função permite envios parciais, que podem ocorrer quando a rede está ocupada.

  createSocket()

    Tenta criar um soquete; em caso de falha, utiliza um algoritmo de back-off exponencial. Na falha inicial, o manipulador descarta a mensagem que estava tentando enviar. Quando mensagens subsequentes são tratadas pela mesma instância, ela não tentará se reconectar até que algum tempo tenha passado. Os parâmetros padrão são tais que o atraso inicial é de um segundo e, se após esse atraso a conexão ainda não puder ser estabelecida, o manipulador dobrará o atraso a cada tentativa, até um máximo de 30 segundos.

    Este comportamento é controlado pelo seguintes atributos do manipulador:

    - `retryStart` (atraso inicial, padrão de 1,0 segundo).

    - `retryFactor` (multiplicador, com padrão de 2,0).

    - `retryMax` (atraso máximo, padrão de 30,0 segundos).

    Isso significa que, se o ouvinte remoto iniciar após o manipulador já ter sido utilizado, mensagens podem ser perdidas (pois o manipulador nem sequer tentará estabelecer uma conexão até que o atraso tenha decorrido, apenas descartando silenciosamente as mensagens durante esse período de atraso).

## DatagramHandler

A classe `DatagramHandler`, localizada no módulo `logging.handlers`, herda de `SocketHandler` para oferecer suporte ao envio de mensagens de log por meio de soquetes UDP.

class logging.handlers.DatagramHandler(host, port)

  Retorna uma nova instância da classe `DatagramHandler`, destinada a se comunicar com uma máquina remota cujo endereço é fornecido por host e port.

  Nota

  Como o UDP não é um protocolo de fluxo contínuo, não há uma conexão persistente entre uma instância deste manipulador e host. Por esse motivo, ao usar um soquete de rede, pode ser necessário realizar uma consulta DNS a cada vez que um evento é registrado, o que pode introduzir alguma latência no sistema. Se isso for um problema para você, pode realizar a consulta manualmente e inicializar este manipulador usando o endereço IP obtido, em vez do nome do host.

  Alterado na versão 3.4: Se `port` for especificado como `None`, um soquete de domínio Unix é criado usando o valor de `host`; caso contrário, é criado um soquete UDP.

  emit()

    Serializa com pickle o dicionário de atributos do registro e o grava no soquete em formato binário. Se houver um erro com o soquete, o pacote é descartado silenciosamente. Para desserializar com pickle o registro no lado receptor em um `LogRecord`, use a função `makeLogRecord()`.

  makeSocket()

    A método de fábrica de `SocketHandler` aqui é substituído para criar um soquete UDP (`socket.SOCK_DGRAM`).

  send(s)

    Envia uma sequência de bytes serializada com pickle para um soquete. O formato da sequência de bytes enviada é conforme descrito na documentação de `SocketHandler.makePickle()`.

## SysLogHandler

A classe `SysLogHandler`, localizada no módulo `logging.handlers`, oferece suporte ao envio de mensagens de log para um syslog Unix remoto ou local.

class logging.handlers.SysLogHandler(address=('localhost', SYSLOG_UDP_PORT), facility=LOG_USER, socktype=socket.SOCK_DGRAM, timeout=None)

  Returns a new instance of the `SysLogHandler` class intended to communicate with a remote Unix machine whose address is given by address in the form of a `(host, port)` tuple. If address is not specified, `('localhost', 514)` is used. The address is used to open a socket. An alternative to providing a `(host, port)` tuple is providing an address as a string, for example ‘/dev/log’. In this case, a Unix domain socket is used to send the message to the syslog. If facility is not specified, `LOG_USER` is used. The type of socket opened depends on the socktype argument, which defaults to `socket.SOCK_DGRAM` and thus opens a UDP socket. To open a TCP socket (for use with the newer syslog daemons such as rsyslog), specify a value of `socket.SOCK_STREAM`. If timeout is specified, it sets a timeout (in seconds) for the socket operations. This can help prevent the program from hanging indefinitely if the syslog server is unreachable. By default, timeout is `None`, meaning no timeout is applied.

  Observe que, se o seu servidor não estiver escutando na porta UDP 514, o `SysLogHandler` pode parecer não funcionar. Nesse caso, verifique qual endereço deve ser usado para um soquete de domínio — isso depende do sistema. Por exemplo, no Linux geralmente é ‘/dev/log’, enquanto no OS/X é ‘/var/run/syslog’. Será necessário verificar a sua plataforma e usar o endereço apropriado (talvez seja preciso fazer essa verificação em tempo de execução se a aplicação precisar rodar em várias plataformas). No Windows, praticamente é necessário usar a opção UDP.

  Nota

  No macOS 12.x (Monterey), a Apple alterou o comportamento do daemon syslog — ele não escuta mais em um soquete de domínio. Portanto, não é possível esperar que `SysLogHandler` funcione nesse sistema.

  Consulte gh-91070 para obter mais informações.

  Alterado na versão 3.2: socktype foi adicionado.

  Alterado na versão 3.14: timeout foi adicionado.

  close()

    Fecha o soquete para o host remoto.

  createSocket()

    Tenta criar um soquete e, se ele não for um soquete de datagrama, conectá-lo à outra extremidade. Este método é chamado durante a inicialização do manipulador, mas não é considerado um erro se a outra extremidade não estiver escutando nesse momento — o método será chamado novamente ao emitir um evento, caso não haja um soquete nesse ponto.

    Adicionado na versão 3.11.

  emit(record)

    O registro é formatado e, em seguida, enviado ao servidor syslog. Se houver informações de exceção, elas não são enviadas ao servidor.

    Alterado na versão 3.2.1: (Veja: bpo-12168.) Em versões anteriores, a mensagem enviada aos daemons syslog era sempre terminada com um byte NUL, porque versões antigas desses daemons esperavam uma mensagem terminada em NUL — embora isso não conste na especificação relevante (RFC 5424). Versões mais recentes desses daemons não esperam o byte NUL, mas o removem caso esteja presente, e daemons ainda mais recentes (que aderem mais de perto à RFC 5424) repassam o byte NUL como parte da mensagem.

    Para facilitar o tratamento de mensagens do syslog diante de todos esses comportamentos distintos dos daemons, a adição do byte NUL tornou-se configurável por meio de um atributo em nível de classe, `append_nul` O valor padrão é `True` (preservando o comportamento existente), mas pode ser definido como `False` em uma instância de `SysLogHandler` para que essa instância não acrescente o terminador NUL.

    Alterado na versão 3.3: (Consulte: bpo-12419) Em versões anteriores, não havia uma instalação para um prefixo “ident” ou “tag” para identificar a origem da mensagem. Isso agora pode ser especificado usando um atributo de nível de classe, que por padrão é `""` para preservar o comportamento existente, mas pode ser substituído em uma instância de `SysLogHandler` para que essa instância adicione o ident a cada mensagem manipulada. Observe que o ident fornecido deve ser texto, não bytes, e é adicionado à mensagem exatamente como está.

  encodePriority(facility, priority)

    Codifica a instalação e a prioridade em um inteiro. Você pode passar strings ou inteiros — se strings forem passadas, dicionários de mapeamento internos são usados para convertê-las em inteiros.

    Os valores simbólicos `LOG_` são definidos em `SysLogHandler` e espelham os valores definidos no arquivo de cabeçalho `sys/syslog.h`.

    Prioridades

    Nome (string) | Valor simbólico
    --- | ---
    `alert` | LOG_ALERT
    `crit` ou `critical` | LOG_CRIT
    `debug` | LOG_DEBUG
    `emerg` or `panic` | LOG_EMERG
    `err` ou `error` | LOG_ERR
    `info` | LOG_INFO
    `notice` | LOG_NOTICE
    `warn` or `warning` | LOG_WARNING

    Facilities

    Nome (string) | Valor simbólico
    --- | ---
    `auth` | LOG_AUTH
    `authpriv` | LOG_AUTHPRIV
    `cron` | LOG_CRON
    `daemon` | LOG_DAEMON
    `ftp` | LOG_FTP
    `kern` | LOG_KERN
    `lpr` | LOG_LPR
    `mail` | LOG_MAIL
    `news` | LOG_NEWS
    `syslog` | LOG_SYSLOG
    `user` | LOG_USER
    `uucp` | LOG_UUCP
    `local0` | LOG_LOCAL0
    `local1` | LOG_LOCAL1
    `local2` | LOG_LOCAL2
    `local3` | LOG_LOCAL3
    `local4` | LOG_LOCAL4
    `local5` | LOG_LOCAL5
    `local6` | LOG_LOCAL6
    `local7` | LOG_LOCAL7

  mapPriority(levelname)

    Maps a logging level name to a syslog priority name. You may need to override this if you are using custom levels, or if the default algorithm is not suitable for your needs. The default algorithm maps `DEBUG`, `INFO`, `WARNING`, `ERROR` and `CRITICAL` to the equivalent syslog names, and all other level names to ‘warning’.

## NTEventLogHandler

The `NTEventLogHandler` class, located in the `logging.handlers` module, supports sending logging messages to a local Windows NT, Windows 2000 or Windows XP event log. Before you can use it, you need Mark Hammond’s Win32 extensions for Python installed.

class logging.handlers.NTEventLogHandler(appname, dllname=None, logtype='Application')

  Returns a new instance of the `NTEventLogHandler` class. The appname is used to define the application name as it appears in the event log. An appropriate registry entry is created using this name. The dllname should give the fully qualified pathname of a .dll or .exe which contains message definitions to hold in the log (if not specified, `'win32service.pyd'` is used - this is installed with the Win32 extensions and contains some basic placeholder message definitions. Note that use of these placeholders will make your event logs big, as the entire message source is held in the log. If you want slimmer logs, you have to pass in the name of your own .dll or .exe which contains the message definitions you want to use in the event log). The logtype is one of `'Application'`, `'System'` or `'Security'`, and defaults to `'Application'`.

  close()

    At this point, you can remove the application name from the registry as a source of event log entries. However, if you do this, you will not be able to see the events as you intended in the Event Log Viewer - it needs to be able to access the registry to get the .dll name. The current version does not do this.

  emit(record)

    Determines the message ID, event category and event type, and then logs the message in the NT event log.

  getEventCategory(record)

    Returns the event category for the record. Override this if you want to specify your own categories. This version returns 0.

  getEventType(record)

    Returns the event type for the record. Override this if you want to specify your own types. This version does a mapping using the handler’s typemap attribute, which is set up in `__init__()` to a dictionary which contains mappings for `DEBUG`, `INFO`, `WARNING`, `ERROR` and `CRITICAL`. If you are using your own levels, you will either need to override this method or place a suitable dictionary in the handler’s typemap attribute.

  getMessageID(record)

    Returns the message ID for the record. If you are using your own messages, you could do this by having the msg passed to the logger being an ID rather than a format string. Then, in here, you could use a dictionary lookup to get the message ID. This version returns 1, which is the base message ID in `win32service.pyd`.

## SMTPHandler

The `SMTPHandler` class, located in the `logging.handlers` module, supports sending logging messages to an email address via SMTP.

class logging.handlers.SMTPHandler(mailhost, fromaddr, toaddrs, subject, credentials=None, secure=None, timeout=1.0)

  Returns a new instance of the `SMTPHandler` class. The instance is initialized with the from and to addresses and subject line of the email. The toaddrs should be a list of strings. To specify a non-standard SMTP port, use the (host, port) tuple format for the mailhost argument. If you use a string, the standard SMTP port is used. If your SMTP server requires authentication, you can specify a (username, password) tuple for the credentials argument.

  To specify the use of a secure protocol (TLS), pass in a tuple to the secure argument. This will only be used when authentication credentials are supplied. The tuple should be either an empty tuple, or a single-value tuple with the name of a keyfile, or a 2-value tuple with the names of the keyfile and certificate file. (This tuple is passed to the `smtplib.SMTP.starttls()` method.)

  A timeout can be specified for communication with the SMTP server using the timeout argument.

  Alterado na versão 3.3: Added the timeout parameter.

  emit(record)

    Formats the record and sends it to the specified addressees.

  getSubject(record)

    If you want to specify a subject line which is record-dependent, override this method.

## MemoryHandler

The `MemoryHandler` class, located in the `logging.handlers` module, supports buffering of logging records in memory, periodically flushing them to a target handler. Flushing occurs whenever the buffer is full, or when an event of a certain severity or greater is seen.

`MemoryHandler` is a subclass of the more general `BufferingHandler`, which is an abstract class. This buffers logging records in memory. Whenever each record is added to the buffer, a check is made by calling `shouldFlush()` to see if the buffer should be flushed. If it should, then `flush()` is expected to do the flushing.

class logging.handlers.BufferingHandler(capacity)

  Initializes the handler with a buffer of the specified capacity. Here, capacity means the number of logging records buffered.

  emit(record)

    Append the record to the buffer. If `shouldFlush()` returns true, call `flush()` to process the buffer.

  flush()

    For a `BufferingHandler` instance, flushing means that it sets the buffer to an empty list. This method can be overwritten to implement more useful flushing behavior.

  shouldFlush(record)

    Return `True` if the buffer is up to capacity. This method can be overridden to implement custom flushing strategies.

class logging.handlers.MemoryHandler(capacity, flushLevel=ERROR, target=None, flushOnClose=True)

  Returns a new instance of the `MemoryHandler` class. The instance is initialized with a buffer size of capacity (number of records buffered). If flushLevel is not specified, `ERROR` is used. If no target is specified, the target will need to be set using `setTarget()` before this handler does anything useful. If flushOnClose is specified as `False`, then the buffer is not flushed when the handler is closed. If not specified or specified as `True`, the previous behaviour of flushing the buffer will occur when the handler is closed.

  Alterado na versão 3.6: The flushOnClose parameter was added.

  close()

    Calls `flush()`, sets the target to `None` and clears the buffer.

  flush()

    For a `MemoryHandler` instance, flushing means just sending the buffered records to the target, if there is one. The buffer is also cleared when buffered records are sent to the target. Override if you want different behavior.

  setTarget(target)

    Sets the target handler for this handler.

  shouldFlush(record)

    Checks for buffer full or a record at the flushLevel or higher.

## HTTPHandler

The `HTTPHandler` class, located in the `logging.handlers` module, supports sending logging messages to a web server, using either `GET` or `POST` semantics.

class logging.handlers.HTTPHandler(host, url, method='GET', secure=False, credentials=None, context=None)

  Returns a new instance of the `HTTPHandler` class. The host can be of the form `host:port`, should you need to use a specific port number. If no method is specified, `GET` is used. If secure is true, a HTTPS connection will be used. The context parameter may be set to a `ssl.SSLContext` instance to configure the SSL settings used for the HTTPS connection. If credentials is specified, it should be a 2-tuple consisting of userid and password, which will be placed in a HTTP ‘Authorization’ header using Basic authentication. If you specify credentials, you should also specify secure=True so that your userid and password are not passed in cleartext across the wire.

  Alterado na versão 3.5: The context parameter was added.

  mapLogRecord(record)

    Provides a dictionary, based on `record`, which is to be URL-encoded and sent to the web server. The default implementation just returns `record.__dict__`. This method can be overridden if e.g. only a subset of `LogRecord` is to be sent to the web server, or if more specific customization of what’s sent to the server is required.

  emit(record)

    Sends the record to the web server as a URL-encoded dictionary. The `mapLogRecord()` method is used to convert the record to the dictionary to be sent.

  Nota

  Since preparing a record for sending it to a web server is not the same as a generic formatting operation, using `setFormatter()` to specify a `Formatter` for a `HTTPHandler` has no effect. Instead of calling `format()`, this handler calls `mapLogRecord()` and then `urllib.parse.urlencode()` to encode the dictionary in a form suitable for sending to a web server.

## QueueHandler

Adicionado na versão 3.2.

The `QueueHandler` class, located in the `logging.handlers` module, supports sending logging messages to a queue, such as those implemented in the `queue` or `multiprocessing` modules.

Along with the `QueueListener` class, `QueueHandler` can be used to let handlers do their work on a separate thread from the one which does the logging. This is important in web applications and also other service applications where threads servicing clients need to respond as quickly as possible, while any potentially slow operations (such as sending an email via `SMTPHandler`) are done on a separate thread.

class logging.handlers.QueueHandler(queue)

  Returns a new instance of the `QueueHandler` class. The instance is initialized with the queue to send messages to. The queue can be any queue-like object; it’s used as-is by the `enqueue()` method, which needs to know how to send messages to it. The queue is not required to have the task tracking API, which means that you can use `SimpleQueue` instances for queue.

  Nota

  If you are using `multiprocessing`, you should avoid using `SimpleQueue` and instead use `multiprocessing.Queue`.

  Aviso

  The `multiprocessing` module uses an internal logger created and accessed via `get_logger()`. `multiprocessing.Queue` will log `DEBUG` level messages upon items being queued. If those log messages are processed by a `QueueHandler` using the same `multiprocessing.Queue` instance, it will cause a deadlock or infinite recursion.

  emit(record)

    Enqueues the result of preparing the LogRecord. Should an exception occur (e.g. because a bounded queue has filled up), the `handleError()` method is called to handle the error. This can result in the record silently being dropped (if `logging.raiseExceptions` is `False`) or a message printed to `sys.stderr` (if `logging.raiseExceptions` is `True`).

  prepare(record)

    Prepares a record for queuing. The object returned by this method is enqueued.

    The base implementation formats the record to merge the message, arguments, exception and stack information, if present. It also removes unpickleable items from the record in-place. Specifically, it overwrites the record’s `msg` and `message` attributes with the merged message (obtained by calling the handler’s `format()` method), and sets the `args`, `exc_info` and `exc_text` attributes to `None`.

    You might want to override this method if you want to convert the record to a dict or JSON string, or send a modified copy of the record while leaving the original intact.

    Nota

    The base implementation formats the message with arguments, sets the `message` and `msg` attributes to the formatted message and sets the `args` and `exc_text` attributes to `None` to allow pickling and to prevent further attempts at formatting. This means that a handler on the `QueueListener` side won’t have the information to do custom formatting, e.g. of exceptions. You may wish to subclass `QueueHandler` and override this method to e.g. avoid setting `exc_text` to `None`. Note that the `message` / `msg` / `args` changes are related to ensuring the record is pickleable, and you might or might not be able to avoid doing that depending on whether your `args` are pickleable. (Note that you may have to consider not only your own code but also code in any libraries that you use.)

  enqueue(record)

    Enqueues the record on the queue using `put_nowait()`; you may want to override this if you want to use blocking behaviour, or a timeout, or a customized queue implementation.

  listener

    When created via configuration using `dictConfig()`, this attribute will contain a `QueueListener` instance for use with this handler. Otherwise, it will be `None`.

    Adicionado na versão 3.12.

## QueueListener

Adicionado na versão 3.2.

The `QueueListener` class, located in the `logging.handlers` module, supports receiving logging messages from a queue, such as those implemented in the `queue` or `multiprocessing` modules. The messages are received from a queue in an internal thread and passed, on the same thread, to one or more handlers for processing. While `QueueListener` is not itself a handler, it is documented here because it works hand-in-hand with `QueueHandler`.

Along with the `QueueHandler` class, `QueueListener` can be used to let handlers do their work on a separate thread from the one which does the logging. This is important in web applications and also other service applications where threads servicing clients need to respond as quickly as possible, while any potentially slow operations (such as sending an email via `SMTPHandler`) are done on a separate thread.

class logging.handlers.QueueListener(queue, *handlers, respect_handler_level=False)

  Returns a new instance of the `QueueListener` class. The instance is initialized with the queue to send messages to and a list of handlers which will handle entries placed on the queue. The queue can be any queue-like object; it’s passed as-is to the `dequeue()` method, which needs to know how to get messages from it. The queue is not required to have the task tracking API (though it’s used if available), which means that you can use `SimpleQueue` instances for queue.

  Nota

  If you are using `multiprocessing`, you should avoid using `SimpleQueue` and instead use `multiprocessing.Queue`.

  If `respect_handler_level` is `True`, a handler’s level is respected (compared with the level for the message) when deciding whether to pass messages to that handler; otherwise, the behaviour is as in previous Python versions - to always pass each message to each handler.

  Alterado na versão 3.5: The `respect_handler_level` argument was added.

  Alterado na versão 3.14: `QueueListener` can now be used as a context manager via `with`. When entering the context, the listener is started. When exiting the context, the listener is stopped. `__enter__()` returns the `QueueListener` object.

  dequeue(block)

    Dequeues a record and return it, optionally blocking.

    The base implementation uses `get()`. You may want to override this method if you want to use timeouts or work with custom queue implementations.

  prepare(record)

    Prepare a record for handling.

    This implementation just returns the passed-in record. You may want to override this method if you need to do any custom marshalling or manipulation of the record before passing it to the handlers.

  handle(record)

    Handle a record.

    This just loops through the handlers offering them the record to handle. The actual object passed to the handlers is that which is returned from `prepare()`.

  start()

    Starts the listener.

    This starts up a background thread to monitor the queue for LogRecords to process.

    Alterado na versão 3.14: Raises `RuntimeError` if called and the listener is already running.

  stop()

    Stops the listener.

    This asks the thread to terminate, and then waits for it to do so. Note that if you don’t call this before your application exits, there may be some records still left on the queue, which won’t be processed.

  enqueue_sentinel()

    Writes a sentinel to the queue to tell the listener to quit. This implementation uses `put_nowait()`. You may want to override this method if you want to use timeouts or work with custom queue implementations.

    Adicionado na versão 3.3.

Ver também

Módulo `logging`

  Referência da API para o módulo de logging.

Módulo `logging.config`

  API de configuração para o módulo logging.