適用于 Python 的 Azure 監視器 Opentelemetry Distro 用戶端程式庫 - 1.1.1 版

發行項
12/06/2023

Opentelemetry Python的 Azure 監視器散發版本提供多個可安裝元件，可供 Opentelemetry Azure 監視器監視解決方案使用。它可讓您檢測 Python 應用程式，以透過 Azure 監視器匯出工具將遙測擷取和報告至 Azure 監視器。

此散發版本會自動安裝下列程式庫：

Azure 監視器 OpenTelemetry 匯出工具
正式支援的 OpenTelemetry 檢測子集，如下所示。

正式支援的檢測

OpenTelemetry 檢測允許自動收集從基礎檢測程式庫傳送的要求。以下是隨附于 Azure 監視器散發版本的 OpenTelemetry 檢測清單。預設會啟用這些檢測。如需如何退出這些檢測，請參閱下面的使用方式一節。

測試設備	支援的程式庫名稱	支援的版本
Azure Core Tracing OpenTelemetry	`azure_sdk`
OpenTelemetry Django Instrumentation	Django	link
OpenTelemetry FastApi Instrumentation	fastapi	link
OpenTelemetry Flask Instrumentation	瓶	link
OpenTelemetry Psycopg2 Instrumentation	psycopg2	link
OpenTelemetry 要求檢測	requests	link
OpenTelemetry UrlLib Instrumentation	urllib	全部
OpenTelemetry UrlLib3 Instrumentation	urllib3	link

如果您想要新增另一個 OpenTelemetry 檢測的支援，請提交功能要求。同時，您可以透過自己的 API 手動使用 OpenTelemetry 檢測 (，也就是 instrument() 在您的程式碼中) 。如需範例，請參閱此範例。

重要概念

此套件會組合一系列的 OpenTelemetry 和 Azure 監視器元件，以啟用遙測的收集和傳送至 Azure 監視器。針對 MANUAL 檢測，請使用函 configure_azure_monitor 式。尚未支援 AUTOMATIC 檢測。

Azure 監視器 OpenTelemetry 匯出工具是完成這項作業的主要元件。您將能夠直接透過此套件使用匯出工具及其 API。請前往匯出工具檔，以瞭解 OpenTelemetry 和 Azure 監視器元件在啟用遙測收集和匯出時的運作方式。

目前，OpenTelemetry 中可用的所有檢測都處於 Beta 狀態，這表示它們不穩定，未來可能會有重大變更。努力將這些工作推送至更穩定的狀態。

開始使用

Prerequisites

若要使用此套件，您必須具有：

Azure 訂用帳戶 - 建立免費帳戶
Azure 監視器 - 如何使用 Application Insights
Opentelemetry SDK - 適用于 Python 的 Opentelemetry SDK
Python 3.7 或更新版本 - 安裝 Python

安裝套件

使用 pip安裝 Azure 監視器 Opentelemetry Distro：

pip install azure-monitor-opentelemetry

使用方式

您可以使用 configure_azure_monitor 將應用程式的檢測設定為 Azure 監視器。 configure_azure_monitor 支援下列選擇性引數。所有傳入參數都會優先于任何相關的環境變數。

參數	Description	環境變數
`connection_string`	Application Insights 資源的連接字串。如果未明確傳入，則會自動從 `APPLICATIONINSIGHTS_CONNECTION_STRING` 環境變數填入連接字串。	`APPLICATIONINSIGHTS_CONNECTION_STRING`
`logger_name`	用來收集遙測的 Python 記錄器名稱。	`N/A`
`instrumentation_options`	巢狀字典，決定要啟用或停用的檢測。檢測是由其程式庫名稱所參考。例如， `{"azure_sdk": {"enabled": False}, "flask": {"enabled": False}, "django": {"enabled": True}}` 會停用 Azure 核心追蹤和 Flask 檢測，但讓 Django 和其他預設檢測保持啟用狀態。 `OTEL_PYTHON_DISABLED_INSTRUMENTATIONS`以下所述的環境變數也可用來停用檢測。	`N/A`

您可以使用OpenTelemetry 環境變數進一步設定，例如： |環境變數 |描述 | |-------------|----------------------| |OTEL_SERVICE_NAME，OTEL_RESOURCE_ATTRIBUTES | 指定與應用程式相關聯的 OpenTelemetry資源。 | | OTEL_LOGS_EXPORTER |如果設定為 None ，則會停用記錄遙測的收集和匯出。 | | OTEL_METRICS_EXPORTER |如果設定為 None ，則會停用計量遙測的收集和匯出。 | | OTEL_TRACES_EXPORTER |如果設定為 None ，則會停用分散式追蹤遙測的收集和匯出。 | | OTEL_BLRP_SCHEDULE_DELAY |以毫秒為單位指定記錄匯出間隔。預設值為 5000。 | | OTEL_BSP_SCHEDULE_DELAY |以毫秒為單位指定分散式追蹤匯出間隔。預設值為 5000。 | | OTEL_TRACES_SAMPLER_ARG |指定要取樣之分散式追蹤遙測的比例。接受的值位於 [0,1] 範圍內。預設為 1.0，這表示不會取樣任何遙測。| | OTEL_PYTHON_DISABLED_INSTRUMENTATIONS |指定要停用哪些支援的檢測。停用的檢測不會檢測為的 configure_azure_monitor 一部分。不過，他們仍然可以直接手動檢測 instrument() 。接受以逗號分隔的小寫程式庫名稱清單。例如，設定為 "psycopg2,fastapi" 以停用 Psycopg2 和 FastAPI 檢測。預設為空白清單，啟用所有支援的檢測。 | | OTEL_EXPERIMENTAL_RESOURCE_DETECTORS |實驗性 OpenTelemetry 環境變數，用來指定要用來產生資源屬性的資源偵測器。這是實驗性功能，而且此變數的名稱及其行為可能會以非回溯相容的方式變更。預設為「azure_app_service，azure_vm」，以啟用適用于 Azure App 服務和 Azure VM的 Azure Resource Detectors。若要新增或移除特定資源偵測器，請據以設定環境變數。如需詳細資訊，請參閱 OpenTelemetry Python 資源偵測器檔。 |

Azure 監視器 OpenTelemetry 匯出工具設定

您可以將 Azure 監視器 OpenTelemetry 匯出工具組態參數直接傳遞至 configure_azure_monitor 。請參閱這裡匯出的相關其他組態。

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

範例

您可以在這裡取得範例來示範如何使用上述組態選項。

在 Azure Functions 中監視

追蹤相互關聯

傳入您裝載于 Azure Functions Python 應用程式的追蹤傳入要求，將不會自動與其內追蹤的遙測相互關聯。您可以直接擷取 TraceContext 來手動達成追蹤相互關聯，如下所示：


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),
   ):
      ...

記錄問題

Azure Functions背景工作角色本身會傳送記錄遙測本身，而不需要使用 azure 監視器 sdk， (呼叫 configure_azure_monitor()) 。這會導致您在傳送記錄遙測時可能會遇到重複的遙測專案。我們建議客戶只使用 SDK，因為它會允許比使用Azure Functions背景工作角色所提供的內建遙測和功能更豐富的遙測和功能。您可以清除記錄器的處理常式清單，以關閉Azure Functions遙測記錄器。

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

請務必在設定任何記錄器或呼叫之前呼叫 configure_azure_monitor() 上述。

您也可以透過Azure Functions組態停用記錄。

v2.x+

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

v1.x

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

疑難排解

匯出工具會引發 Azure Core中定義的例外狀況。

下一步

如需詳細資訊，請參閱檔。

參與

此專案歡迎參與和提供建議。大部分的參與都要求您同意「參與者授權合約 (CLA)」，宣告您有權且確實授與我們使用投稿的權利。如需詳細資料，請前往 https://cla.microsoft.com 。

當您提交提取要求時，CLA Bot 會自動判斷您是否需要提供 CLA，並適當地裝飾 PR (例如標籤、註解)。請遵循 bot 提供的指示。您只需要使用我們的 CLA 在所有存放庫上執行此動作一次。

此專案採用 Microsoft Open Source Code of Conduct (Microsoft 開放原始碼管理辦法)。如需詳細資訊，請參閱管理辦法常見問題集，如有任何其他問題或意見請連絡 opencode@microsoft.com。

共用方式為