Pustaka klien Distro Opentelemetry Azure Monitor untuk Python - versi 1.1.1

Artikel
12/06/2023

Distro Azure Monitor dari Opentelemetry Python menyediakan beberapa komponen yang dapat diinstal yang tersedia untuk solusi pemantauan Opentelemetry Azure Monitor. Ini memungkinkan Anda untuk melengkapi aplikasi Python Anda untuk menangkap dan melaporkan telemetri ke Azure Monitor melalui pengekspor monitor Azure.

Distro ini secara otomatis menginstal pustaka berikut:

Pengekspor OpenTelemetry Azure Monitor
Subset instrumentasi OpenTelemetry yang secara resmi didukung seperti yang tercantum di bawah ini.

Instrumentasi yang didukung secara resmi

Instrumentasi OpenTelemetry memungkinkan pengumpulan permintaan otomatis yang dikirim dari pustaka berinstrumentasi yang mendasarinya. Berikut ini adalah daftar instrumentasi OpenTelemetry yang dibundel dengan distro Monitor Azure. Instrumentasi ini diaktifkan secara default. Lihat bagian Penggunaan di bawah ini untuk cara menolak instrumentasi ini.

Instrumentasi	Nama pustaka yang didukung	Versi yang didukung
Azure Core Tracing OpenTelemetry	`azure_sdk`
Instrumentasi Django OpenTelemetry	Django	Tautan
Instrumentasi FastApi OpenTelemetry	fastapi	Tautan
Instrumentasi Flask OpenTelemetry	Labu	Tautan
Instrumentasi OpenTelemetry Psycopg2	psycopg2	Tautan
Instrumentasi Permintaan OpenTelemetry	permintaan	Tautan
Instrumentasi UrlLib OpenTelemetry	urllib	Semua
Instrumentasi OpenTelemetry UrlLib3	urllib3	Tautan

Jika Anda ingin menambahkan dukungan untuk instrumentasi OpenTelemetry lain, kirimkan permintaan fitur. Sementara itu, Anda dapat menggunakan instrumentasi OpenTelemetry secara manual melalui API itu sendiri (yaitu instrument()) dalam kode Anda. Lihat ini sebagai contoh.

Konsep utama

Paket ini menggabungkan serangkaian komponen OpenTelemetry dan Azure Monitor untuk mengaktifkan pengumpulan dan pengiriman telemetri ke Azure Monitor. Untuk instrumentasi MANUAL, gunakan configure_azure_monitor fungsi . Instrumentasi OTOMATIS belum didukung.

Pengekspor OpenTelemetry Azure Monitor adalah komponen utama dalam mencapai hal ini. Anda akan dapat menggunakan eksportir dan API mereka secara langsung melalui paket ini. Silakan buka dokumentasi pengekspor untuk memahami cara kerja komponen OpenTelemetry dan Azure Monitor dalam mengaktifkan pengumpulan dan ekspor telemetri.

Saat ini, semua instrumentasi yang tersedia dalam OpenTelemetry dalam keadaan beta, yang berarti tidak stabil dan mungkin memiliki perubahan yang melanggar di masa depan. Upaya sedang dilakukan dalam mendorong ini ke keadaan yang lebih stabil.

Memulai

Prasyarat

Untuk menggunakan paket ini, Anda harus memiliki:

Langganan Azure - Membuat akun gratis
Azure Monitor - Cara menggunakan wawasan aplikasi
Opentelemetry SDK - SDK Opentelemetry untuk Python
Python 3.7 atau yang lebih baru - Instal Python

Instal paketnya

Instal Distro Opentelemetry Azure Monitor dengan pip:

pip install azure-monitor-opentelemetry

Penggunaan

Anda dapat menggunakan configure_azure_monitor untuk menyiapkan instrumentasi untuk aplikasi Anda ke Azure Monitor. configure_azure_monitor mendukung argumen opsional berikut. Semua parameter pass-in lebih diprioritaskan daripada variabel lingkungan terkait.

Parameter	Deskripsi	Variabel Lingkungan
`connection_string`	string koneksi untuk sumber daya Application Insights Anda. string koneksi akan secara otomatis diisi dari `APPLICATIONINSIGHTS_CONNECTION_STRING` variabel lingkungan jika tidak diteruskan secara eksplisit.	`APPLICATIONINSIGHTS_CONNECTION_STRING`
`logger_name`	Nama pencatat Python tempat telemetri dikumpulkan.	`N/A`
`instrumentation_options`	Kamus berlapis yang menentukan instrumentasi mana yang akan diaktifkan atau dinonaktifkan. Instrumentasi disebut dengan Nama Pustaka mereka. Misalnya, `{"azure_sdk": {"enabled": False}, "flask": {"enabled": False}, "django": {"enabled": True}}` akan menonaktifkan Azure Core Tracing dan instrumentasi Flask tetapi membiarkan Django dan instrumentasi default lainnya diaktifkan. Variabel `OTEL_PYTHON_DISABLED_INSTRUMENTATIONS` lingkungan yang dijelaskan di bawah ini juga dapat digunakan untuk menonaktifkan instrumentasi.	`N/A`

Anda dapat mengonfigurasi lebih lanjut dengan variabel lingkungan OpenTelemetry seperti: | Variabel Lingkungan | Deskripsi | |-------------|----------------------| | OTEL_SERVICE_NAME, OTEL_RESOURCE_ATTRIBUTES | Menentukan sumber daya OpenTelemetry yang terkait dengan aplikasi Anda. | | OTEL_LOGS_EXPORTER | Jika diatur ke None, menonaktifkan pengumpulan dan ekspor telemetri pengelogan. | | OTEL_METRICS_EXPORTER | Jika diatur ke None, menonaktifkan pengumpulan dan ekspor telemetri metrik. | | OTEL_TRACES_EXPORTER | Jika diatur ke None, menonaktifkan pengumpulan dan ekspor telemetri pelacakan terdistribusi. | | OTEL_BLRP_SCHEDULE_DELAY | Menentukan interval ekspor pengelogan dalam milidetik. Default ke 5000. | | OTEL_BSP_SCHEDULE_DELAY | Menentukan interval ekspor pelacakan terdistribusi dalam milidetik. Default ke 5000. | | OTEL_TRACES_SAMPLER_ARG | Menentukan rasio telemetri pelacakan terdistribusi yang akan diambil sampelnya. Nilai yang diterima berada dalam rentang [0,1]. Default ke 1.0, yang berarti tidak ada telemetri yang diambil sampelnya. | | OTEL_PYTHON_DISABLED_INSTRUMENTATIONS | Menentukan instrumentasi mana yang didukung untuk dinonaktifkan. Instrumentasi yang dinonaktifkan tidak akan diinstrumentasikan sebagai bagian configure_azure_monitordari . Namun, mereka masih dapat diinstrumentasikan secara manual dengan instrument() langsung. Menerima daftar Nama Pustaka huruf kecil yang dipisahkan koma. Misalnya, atur ke "psycopg2,fastapi" untuk menonaktifkan instrumentasi Psycopg2 dan FastAPI. Default ke daftar kosong, memungkinkan semua instrumentasi yang didukung. | | OTEL_EXPERIMENTAL_RESOURCE_DETECTORS | Variabel lingkungan OpenTelemetry eksperimental yang digunakan untuk menentukan Detektor Sumber Daya yang akan digunakan untuk menghasilkan Atribut Sumber Daya. Ini adalah fitur eksperimental dan nama variabel ini dan perilakunya dapat berubah dengan cara yang kompatibel non-mundur. Default ke "azure_app_service,azure_vm" untuk mengaktifkan Azure Resource Detectors untuk Azure App Service dan Azure VM. Untuk menambahkan atau menghapus detektor sumber daya tertentu, atur variabel lingkungan yang sesuai. Lihat Dokumentasi Detektor Sumber Daya Python OpenTelemetry untuk informasi selengkapnya. |

Konfigurasi Pengekspor OpenTelemetry monitor Azure

Anda dapat meneruskan parameter konfigurasi pengekspor OpenTelemetry monitor Azure langsung ke configure_azure_monitor. Lihat konfigurasi tambahan yang terkait dengan ekspor di sini.

...
configure_azure_monitor(
   connection_string="<your-connection-string>",
   disable_offline_storage=True,
)
...

Contoh

Sampel tersedia di sini untuk menunjukkan cara menggunakan opsi konfigurasi di atas.

Pemantauan di Azure Functions

Korelasi jejak

Permintaan masuk yang dilacak yang masuk ke aplikasi Python Anda yang dihosting di Azure Functions tidak akan secara otomatis berkorelasi dengan telemetri yang dilacak di dalamnya. Anda dapat mencapai korelasi pelacakan secara manual dengan mengekstrak secara langsung seperti yang TraceContext ditunjukkan di bawah ini:


import azure.functions as func

from azure.monitor.opentelemetry import configure_azure_monitor
from opentelemetry import trace
from opentelemetry.propagate import extract

# Configure Azure monitor collection telemetry pipeline
configure_azure_monitor()

def main(req: func.HttpRequest, context) -> func.HttpResponse:
   ...
   # Store current TraceContext in dictionary format
   carrier = {
      "traceparent": context.trace_context.Traceparent,
      "tracestate": context.trace_context.Tracestate,
   }
   tracer = trace.get_tracer(__name__)
   # Start a span using the current context
   with tracer.start_as_current_span(
      "http_trigger_span",
      context=extract(carrier),
   ):
      ...

Masalah pengelogan

Pekerja Azure Functions itu sendiri mengirim telemetri pengelogan itu sendiri tanpa menggunakan sdk azure monitor (panggilan ke configure_azure_monitor()). Ini akan menyebabkan Anda mungkin mengalami entri telemetri duplikat saat mengirim telemetri pengelogan. Rekomendasi kami kepada pelanggan adalah hanya menggunakan SDK karena akan memungkinkan telemetri dan fitur yang jauh lebih kaya daripada menggunakan yang bawaan yang disediakan oleh pekerja Azure Functions. Anda dapat menonaktifkan Azure Functions pencatat telemetri dengan menghapus daftar penangan pencatat Anda.

...
root_logger = logging.getLogger()
for handler in root_logger.handlers[:]:
    root_logger.removeHandler(handler)
...

Pastikan untuk memanggil di atas SEBELUM setiap pencatat atau panggilan ke disiapkan configure_azure_monitor() .

Anda juga dapat menonaktifkan pengelogan melalui konfigurasi Azure Functions.

v2.x+

...
{
  "logging": {
    ...
    "logLevel": {
      "default": "None",
      ...
    }
  }
}
...

v1.x

...
{
  "logger": {
    "categoryFilter": {
      "defaultLevel": "None",
      ...
    }
  }
}
...

Pemecahan Masalah

Pengekspor memunculkan pengecualian yang ditentukan dalam Azure Core.

Langkah berikutnya

Lihat dokumentasi untuk informasi selengkapnya.

Berkontribusi

Proyek ini menyambut baik kontribusi dan saran. Sebagian besar kontribusi mengharuskan Anda menyetujui Perjanjian Lisensi Kontributor (CLA) yang menyatakan bahwa Anda memiliki hak untuk, dan benar-benar melakukannya, memberi kami hak untuk menggunakan kontribusi Anda. Untuk detailnya, kunjungi https://cla.microsoft.com.

Ketika Anda mengirimkan permintaan tarik, CLA-bot akan secara otomatis menentukan apakah Anda perlu memberikan CLA dan menghias PR dengan tepat (misalnya, label, komentar). Cukup ikuti instruksi yang diberikan oleh bot. Anda hanya perlu melakukan ini sekali di semua repos menggunakan CLA kami.

Proyek ini telah mengadopsi Kode Etik Sumber Terbuka Microsoft. Untuk informasi selengkapnya, lihat Tanya Jawab Umum Tata Tertib atau hubungi opencode@microsoft.com untuk pertanyaan atau komentar lainnya.

Bagikan melalui