azure-storage-logging 0.5.1

TableStorageHandler

TableStorageHandler 类是 logging.Handler 类的子类，它将日志消息发送到Azure表存储，并将它们存储在指定的表中。

处理程序将来自应用程序的格式化日志消息放入表实体的 message 属性中，并附带一些系统定义的属性（如 PartitionKey、RowKey 和 Timestamp）

• class azure_storage_logging.handlers.TableStorageHandler(account_name=None, account_key=None, protocol=’https’, table=’logs’, batch_size=0, extra_properties=None, partition_key_formatter=None, row_key_formatter=None, is_emulated=False)

  返回一个新的 TableStorageHandler 类实例。该实例使用您的 Azure 存储账户的名称和密钥以及一些可选参数进行初始化。

  table 指定了存储日志消息的表名称。如果该表不存在，将会创建一个新表。表名称必须符合 Azure 存储表的命名约定，有关更多详细信息，请参阅表的命名约定。

  protocol 指定了 Azure 存储与您的应用程序之间传输数据所使用的协议，支持 http 和 https。

  如果您想在使用批量事务创建新的日志实体时指定 batch_size，则可以指定一个整数值。如果 batch_size 大于 1，则在新的日志消息数量达到 batch_size 时，所有新的日志实体将一次传输到表中。否则，每次执行日志记录时，都会将新的日志实体传输到表中。batch_size 必须不超过 100（Azure 存储表批量事务中的实体最大数量）。

  extra_properties 接受一系列日志记录的格式。处理器特定的 %(hostname)s 格式也是可接受的。处理器将为 extra_properties 中指定的每个格式分配一个实体属性。以下是一个使用额外属性的示例

  import logging
  from azure_storage_logging.handlers import TableStorageHandler
  
  # configure the handler and add it to the logger
  logger = logging.getLogger('example')
  handler = TableStorageHandler(account_name='mystorageaccountname',
                                account_key='mystorageaccountkey',
                                extra_properties=('%(hostname)s',
                                                  '%(levelname)s'))
  logger.addHandler(handler)
  
  # output log messages
  logger.info('info message')
  logger.warning('warning message')
  logger.error('error message')

  它将创建具有额外属性（除常规属性 message 外）的日志实体，并按如下方式存储到表中

  PartitionKey	RowKey	时间戳	hostname	levelname	消息
  XXXXX	XXXXXXXXX	YYYY-MM-DD …	myhost	INFO	info message
  XXXXX	XXXXXXXXX	YYYY-MM-DD …	myhost	WARNING	warn message
  XXXXX	XXXXXXXXX	YYYY-MM-DD …	myhost	ERROR	error message

  您可以为 partition_key_formatter 或 row_key_formatter 指定您的自定义 logging.Formatters 实例，如果您想为表实现自己的键。如果没有为处理器提供自定义格式器，将使用默认格式器作为分区键和行键。分区键的默认值由格式 %(asctime)s 和日期格式 %Y%m%d%H%M（每分钟提供一个唯一值）提供。行键的默认值由格式 %(asctime)s%(msecs)03d-%(hostname)s-%(process)d-%(rowno)02d 和日期格式 %Y%m%d%H%M%S 提供。

  请注意，格式 %(rowno)d 是仅适用于行键的处理程序特定格式。它将格式化为从 0 开始的批处理中的顺序唯一数字。该格式是为了避免在批处理中生成的行键冲突而引入的，如果您不使用批量事务将日志记录到表中，则它始终会格式化为 0。

• setPartitionKeyFormatter(fmt)

  将处理器的分区键格式设置为 fmt。

• setRowKeyFormatter(fmt)

  将处理器的行键格式设置为 fmt。

QueueStorageHandler

QueueStorageHandler 类是 logging.Handler 类的子类，它将日志消息推送到指定的 Azure 存储队列。

您可以使用 Azure 存储客户端库在其他应用程序中从队列中弹出日志消息。

• class azure_storage_logging.handlers.QueueStorageHandler(account_name=None, account_key=None, protocol=’https’, queue=’logs’, message_ttl=None, visibility_timeout=None, base64_encoding=False, is_emulated=False)

  返回一个新实例的 QueueStorageHandler 类。该实例使用 Azure 存储账户的名称和密钥以及一些可选参数进行初始化。

  queue 指定日志消息添加到的队列名称。如果该队列不存在，将创建一个新队列。队列名称必须符合 Azure 存储队列的命名约定，有关更多详细信息，请参阅 队列的命名约定。

  protocol 指定了 Azure 存储与您的应用程序之间传输数据所使用的协议，支持 http 和 https。

  message_ttl 指定消息的存活时间间隔，以秒为单位。允许的最大存活时间是 7 天。如果省略此参数，默认存活时间是 7 天。

  visibility_timeout 指定相对于服务器时间的可见性超时值，以秒为单位。如果没有指定，默认值是 0（使消息立即可见）。新值必须大于或等于 0，并且不能超过 7 天。《visibility_timeout》不能设置为晚于《message_ttl》的值，并且应设置为小于《message_ttl》的值。

  base64_encoding 指定是否需要对日志文本进行 Base64 编码。如果您将其设置为True，则消息中的 Unicode 日志文本首先以 utf-8 编码，然后进行 Base64 编码。一些 Azure 存储客户端库或工具假定 Azure 存储队列中的文本消息已进行 Base64 编码，因此您可以将其设置为True，以正确接收这些库或工具的日志消息。

BlobStorageRotatingFileHandler

BlobStorageRotatingFileHandler 类是 logging.handlers.RotatingFileHandler 类的子类。它执行日志文件轮换，并在当前文件达到一定大小时，将过时的文件存储在 Azure 块存储容器中。

• class azure_storage_logging.handlers.BlobStorageRotatingFileHandler(filename, mode=’a’, maxBytes=0, encoding=None, delay=False, account_name=None, account_key=None, protocol=’https’, container=’logs’, zip_compression=False, max_connections=1, max_retries=5, retry_wait=1.0, is_emulated=False)

  返回一个新实例的 BlobStorageRotatingFileHandler 类。该实例使用您的 Azure 存储账户的名称和密钥以及一些可选参数进行初始化。

  有关其基本用法，请参阅 RotatingFileHandler。该处理器将最新日志文件保留在本地文件系统中。同时，该处理器会立即将过时日志文件发送到块容器，然后从本地文件系统中删除它。

  container 指定存储过时日志文件的块容器名称。如果该容器不存在，将创建一个新容器。容器名称必须符合 Azure 存储块容器的命名约定，有关更多详细信息，请参阅 块容器的命名约定。

  protocol 指定了 Azure 存储与您的应用程序之间传输数据所使用的协议，支持 http 和 https。

  zip_compression 指定是否需要在将过时日志文件放入容器之前对其进行 zip 格式压缩。

  max_connections 指定在块大小超过 64MB 时要使用的最大并行连接数。将值设置为 1 以顺序上传块。将值设置为 2 或更多以并行上传块，这将使用更多系统资源，但会更快地上传。

  max_retries 指定如果发生错误时重试上传块次数。

  retry_wait 指定重试之间的睡眠时间（以秒为单位）。

  仅接受两个格式化程序 %(hostname)s 和 %(process)d 作为 filename 或 container 的一部分。您可以通过使用这些格式化程序来命名容器，将日志文件保存到每个主机或进程的专用块容器中，也可以通过使用它们来命名日志文件，在块容器中存储来自多个主机或进程的日志文件。

  在使用 filename 中的 %(process)d 格式化程序时请小心，因为每次应用程序启动时分配给您的应用程序的不一致的 PIDs 都包含在用于搜索轮转的日志文件名称中。您仅应在长时间运行的应用程序进程生成日志文件时使用 filename 中的格式化程序。

  请注意，与 RotatingFileHandler 不同，处理器类不接收 backupCount 参数。处理器类在容器中存储过时的日志文件的数量是无限的，并且文件以表示用 UTC 替换新文件时的时间的扩展名保存。如果您想将容器中过时日志文件的数量保持在一定数量，您将需要使用 Azure 管理门户或其他工具来完成此操作。

BlobStorageTimedRotatingFileHandler

BlobStorageTimedRotatingFileHandler 类是 logging.handlers.TimedRotatingFileHandler 类的子类。它执行日志文件轮转，并在特定时间间隔将过时文件存储到 Azure 块存储容器中。

• class azure_storage_logging.handlers.BlobStorageTimedRotatingFileHandler(filename, when=’h’, interval=1, encoding=None, delay=False, utc=False, account_name=None, account_key=None, protocol=’https’, container=’logs’, zip_compression=False, max_connections=1, max_retries=5, retry_wait=1.0, is_emulated=False)

  返回 BlobStorageTimedRotatingFileHandler 类的新实例。实例使用您的 Azure 存储帐户的名称和密钥以及一些可选参数进行初始化。

  有关基本用法，请参阅 TimedRotatingFileHandler。处理器将最新日志文件保留在本地文件系统中。同时，处理器会立即将过时日志文件发送到块容器，然后从本地文件系统中删除它。

  container 指定存储过时日志文件的块容器名称。如果该容器不存在，将创建一个新容器。容器名称必须符合 Azure 存储块容器的命名约定，有关更多详细信息，请参阅 块容器的命名约定。

  protocol 指定了 Azure 存储与您的应用程序之间传输数据所使用的协议，支持 http 和 https。

  zip_compression 指定是否需要在将过时日志文件放入容器之前对其进行 zip 格式压缩。

  max_connections 指定在块大小超过 64MB 时要使用的最大并行连接数。将值设置为 1 以顺序上传块。将值设置为 2 或更多以并行上传块，这将使用更多系统资源，但会更快地上传。

  max_retries 指定如果发生错误时重试上传块次数。

  retry_wait 指定重试之间的睡眠时间（以秒为单位）。

  仅接受两个格式化程序 %(hostname)s 和 %(process)d 作为 filename 或 container 的一部分。您可以通过使用这些格式化程序来命名容器，将日志文件保存到每个主机或进程的专用块容器中，也可以通过使用它们来命名日志文件，在块容器中存储来自多个主机或进程的日志文件。

  在使用 filename 中的 %(process)d 格式化程序时请小心，因为每次应用程序启动时分配给您的应用程序的不一致的 PIDs 都包含在用于搜索轮转的日志文件名称中。您仅应在长时间运行的应用程序进程生成日志文件时使用 filename 中的格式化程序。

  请注意，处理器类不接收 backupCount 参数，这与 TimedRotatingFileHandler 不同。处理器类在容器中存储的过时日志文件数量是无限的。如果您想将容器中过时日志文件的数量保持在一定数量，您将需要使用 Azure 管理门户或其他工具来完成此操作。