Mengonfigurasi pengelogan di pustaka Azure untuk Python

  • Artikel

Pustaka Azure untuk Python yang didasarkan pada azure.core menyediakan output pengelogan menggunakan pustaka pengelogan Python standar.

Proses umum yang berfungsi dengan pengelogan adalah sebagai berikut:

  1. Mendapatkan objek pengelogan untuk pustaka yang diinginkan dan mengatur tingkat pengelogan.
  2. Mendaftarkan pengatur untuk aliran pengelogan.
  3. Untuk menyertakan informasi HTTP, berikan parameter logging_enable=True ke konstruktor objek klien, konstruktor objek kredensial, atau ke metode tertentu.

Detail disediakan di bagian yang tersisa dari artikel ini.

Sebagai aturan umum, sumber daya terbaik untuk memahami penggunaan pengelogan dalam pustaka adalah menelusuri kode sumber SDK di github.com/Azure/azure-sdk-for-python. Anda disarankan untuk mengklon repositori ini secara lokal agar Anda dapat dengan mudah mencari detail saat diperlukan, seperti yang disarankan oleh bagian berikut.

Mengatur tingkat pengelogan

import logging

# ...

# Acquire the logger for a library (azure.mgmt.resource in this example)
logger = logging.getLogger('azure.mgmt.resource')

# Set the desired logging level
logger.setLevel(logging.DEBUG)
  • Contoh ini memperoleh pencatat untuk pustaka azure.mgmt.resource, lalu mengatur tingkat pengelogan menjadi logging.DEBUG.
  • Anda dapat memanggil logger.setLevel kapan saja untuk mengubah tingkat pengelogan untuk segmen kode yang berbeda.

Untuk mengatur tingkat pustaka yang berbeda, gunakan nama pustaka tersebut dalam panggilan logging.getLogger. Misalnya, pustaka azure-eventhubs menyediakan pencatat bernama azure.eventhubs, pustaka azure-storage-queue menyediakan pencatat bernama azure.storage.queue, dan sebagainya. (Kode sumber SDK sering menggunakan pernyataan logging.getLogger(__name__), yang memperoleh pencatat menggunakan nama modul yang terkandung.)

Anda juga dapat menggunakan namespace yang lebih umum. Contohnya,

import logging

# Set the logging level for all azure-storage-* libraries
logger = logging.getLogger('azure.storage')
logger.setLevel(logging.INFO)

# Set the logging level for all azure-* libraries
logger = logging.getLogger('azure')
logger.setLevel(logging.ERROR)

Pencatat azure digunakan oleh beberapa pustaka alih-alih pencatat tertentu. Misalnya, pustaka azure-storage-blob menggunakan pencatat azure.

Anda dapat menggunakan metode logger.isEnabledFor untuk memeriksa apakah tingkat pengelogan yang diberikan diaktifkan:

print(
    f"Logger enabled for ERROR={logger.isEnabledFor(logging.ERROR)}, "
    f"WARNING={logger.isEnabledFor(logging.WARNING)}, "
    f"INFO={logger.isEnabledFor(logging.INFO)}, "
    f"DEBUG={logger.isEnabledFor(logging.DEBUG)}"
)

Tingkat pengelogan sama dengan tingkat pustaka pengelogan standar. Tabel berikut menjelaskan penggunaan umum tingkat pengelogan ini di pustaka Azure untuk Python:

Tingkat pengelogan Kegunaan umum
logging.ERROR Kegagalan ketika aplikasi tidak mungkin pulih (misalnya, kehabisan memori).
logging.WARNING (default) Fungsi gagal melakukan tugas yang dimaksudkan (tetapi tidak ketika fungsi dapat pulih, seperti mencoba kembali panggilan REST API). Fungsi biasanya mencatat peringatan saat menaikkan pengecualian. Tingkat peringatan secara otomatis mengaktifkan tingkat kesalahan.
logging.INFO Fungsi beroperasi secara normal atau panggilan layanan dibatalkan. Peristiwa info biasanya mencakup permintaan, tanggapan, dan header. Tingkat info secara otomatis mengaktifkan tingkat kesalahan dan peringatan.
logging.DEBUG Informasi mendetail yang biasa digunakan untuk pemecahan masalah dan menyertakan jejak tumpukan untuk pengecualian. Tingkat debug secara otomatis mengaktifkan tingkat info, peringatan, dan kesalahan. PERHATIAN: Jika Anda juga mengatur logging_enable=True, tingkat debug akan mencakup informasi sensitif seperti kunci akun di header dan kredensial lainnya. Pastikan untuk melindungi log ini guna menghindari pembobolan keamanan.
logging.NOTSET Menonaktifkan semua pengelogan.

Perilaku tingkat pengelogan khusus pustaka

Perilaku pengelogan yang tepat di setiap tingkat bergantung pada pustaka yang dimaksud. Beberapa pustaka, seperti azure.eventhub, melakukan pengelogan ekstensif sedangkan pustaka lain melakukan sedikit.

Cara terbaik untuk memeriksa pengelogan yang tepat untuk pustaka adalah dengan mencari tingkat pengelogan di Azure SDK untuk kode sumber Python:

  1. Di folder repositori, arahkan ke folder sdk, lalu arahkan ke folder untuk layanan kepentingan tertentu.

  2. Dalam folder tersebut, cari salah satu string berikut:

    • _LOGGER.error
    • _LOGGER.warning
    • _LOGGER.info
    • _LOGGER.debug

Mendaftarkan pengatur aliran log

Untuk menangkap output pengelogan, Anda harus mendaftarkan minimal satu pengatur aliran log dalam kode Anda:

import logging
# Direct logging output to stdout. Without adding a handler,
# no logging output is visible.
handler = logging.StreamHandler(stream=sys.stdout)
logger.addHandler(handler)

Contoh ini mendaftarkan pengatur yang mengarahkan output log ke stdout. Anda dapat menggunakan jenis pengatur lain seperti yang dijelaskan pada logging.handlers dalam dokumentasi Python atau menggunakan metode logging.basicConfig standar.

Mengaktifkan pengelogan HTTP untuk objek atau operasi klien

Secara default, pengelogan dalam pustaka Azure tidak menyertakan informasi HTTP apa pun. Untuk menyertakan informasi HTTP dalam output log (sebagai tingkat DEBUG), Anda harus secara eksplisit meneruskan logging_enable=True ke klien atau konstruktor objek kredensial atau ke metode tertentu.

Perhatian

Pengelogan HTTP dapat menyertakan informasi sensitif seperti kunci akun di header dan kredensial lainnya. Pastikan untuk melindungi log ini guna menghindari pembobolan keamanan.

Mengaktifkan pengelogan HTTP untuk objek klien (tingkat DEBUG)

from azure.storage.blob import BlobClient
from azure.identity import DefaultAzureCredential

# Enable HTTP logging on the client object when using DEBUG level
# endpoint is the Blob storage URL.
client = BlobClient(endpoint, DefaultAzureCredential(), logging_enable=True)

Mengaktifkan pengelogan HTTP untuk objek klien memungkinkan pengelogan untuk semua operasi yang dipanggil melalui objek tersebut.

Mengaktifkan pengelogan HTTP untuk objek kredensial (tingkat DEBUG)

from azure.storage.blob import BlobClient
from azure.identity import DefaultAzureCredential

# Enable HTTP logging on the credential object when using DEBUG level
credential = DefaultAzureCredential(logging_enable=True)

# endpoint is the Blob storage URL.
client = BlobClient(endpoint, credential)

Mengaktifkan pengelogan HTTP untuk objek kredensial memungkinkan pengelogan untuk semua operasi yang dipanggil melalui objek tersebut, tetapi tidak untuk operasi di objek klien yang tidak melibatkan autentikasi.

Mengaktifkan pengelogan untuk metode individual (tingkat DEBUG)

from azure.storage.blob import BlobClient
from azure.identity import DefaultAzureCredential

# endpoint is the Blob storage URL.
client = BlobClient(endpoint, DefaultAzureCredential())

# Enable HTTP logging for only this operation when using DEBUG level
client.create_container("container01", logging_enable=True)

Contoh output pengelogan

Kode berikut ditampilkan dalam Contoh: Gunakan akun penyimpanan dengan tambahan pengaktifan pengelogan DEBUG dan HTTP:

import logging
import os
import sys
import uuid

from azure.core import exceptions
from azure.identity import DefaultAzureCredential
from azure.storage.blob import BlobClient

logger = logging.getLogger("azure")
logger.setLevel(logging.DEBUG)

# Set the logging level for the azure.storage.blob library
logger = logging.getLogger("azure.storage.blob")
logger.setLevel(logging.DEBUG)

# Direct logging output to stdout. Without adding a handler,
# no logging output is visible.
handler = logging.StreamHandler(stream=sys.stdout)
logger.addHandler(handler)

print(
    f"Logger enabled for ERROR={logger.isEnabledFor(logging.ERROR)}, "
    f"WARNING={logger.isEnabledFor(logging.WARNING)}, "
    f"INFO={logger.isEnabledFor(logging.INFO)}, "
    f"DEBUG={logger.isEnabledFor(logging.DEBUG)}"
)

try:
    credential = DefaultAzureCredential()
    storage_url = os.environ["AZURE_STORAGE_BLOB_URL"]
    unique_str = str(uuid.uuid4())[0:5]

    # Enable logging on the client object
    blob_client = BlobClient(
        storage_url,
        container_name="blob-container-01",
        blob_name=f"sample-blob-{unique_str}.txt",
        credential=credential,
    )

    with open("./sample-source.txt", "rb") as data:
        blob_client.upload_blob(data, logging_body=True, logging_enable=True)

except (
    exceptions.ClientAuthenticationError,
    exceptions.HttpResponseError
) as e:
    print(e.message)

Outputnya sebagai berikut:

Logger enabled for ERROR=True, WARNING=True, INFO=True, DEBUG=True
Request URL: 'https://pythonazurestorage12345.blob.core.windows.net/blob-container-01/sample-blob-5588e.txt'
Request method: 'PUT'
Request headers:
    'Content-Length': '77'
    'x-ms-blob-type': 'BlockBlob'
    'If-None-Match': '*'
    'x-ms-version': '2023-11-03'
    'Content-Type': 'application/octet-stream'
    'Accept': 'application/xml'
    'User-Agent': 'azsdk-python-storage-blob/12.19.0 Python/3.10.11 (Windows-10-10.0.22631-SP0)'
    'x-ms-date': 'Fri, 19 Jan 2024 19:25:53 GMT'
    'x-ms-client-request-id': '8f7b1b0b-b700-11ee-b391-782b46f5c56b'
    'Authorization': '*****'
Request body:
b"Hello there, Azure Storage. I'm a friendly file ready to be stored in a blob."
Response status: 201
Response headers:
    'Content-Length': '0'
    'Content-MD5': 'SUytm0872jZh+KYqtgjbTA=='
    'Last-Modified': 'Fri, 19 Jan 2024 19:25:54 GMT'
    'ETag': '"0x8DC1924749AE3C3"'
    'Server': 'Windows-Azure-Blob/1.0 Microsoft-HTTPAPI/2.0'
    'x-ms-request-id': '7ac499fa-601e-006d-3f0d-4bdf28000000'
    'x-ms-client-request-id': '8f7b1b0b-b700-11ee-b391-782b46f5c56b'
    'x-ms-version': '2023-11-03'
    'x-ms-content-crc64': 'rtHLUlztgxc='
    'x-ms-request-server-encrypted': 'true'
    'Date': 'Fri, 19 Jan 2024 19:25:53 GMT'
Response content:
b''

Catatan

Jika Anda mendapatkan kesalahan otorisasi, pastikan identitas yang Anda jalankan di bawah diberi peran "Kontributor Data Blob Penyimpanan" pada kontainer blob Anda. Untuk mempelajari selengkapnya, lihat Menggunakan penyimpanan blob dengan autentikasi.