Python용 Azure Monitor Opentelemetry Distro 클라이언트 라이브러리 - 버전 1.1.1

아티클
12/06/2023

Opentelemetry Python의 Azure Monitor 배포판은 Opentelemetry Azure Monitor 모니터링 솔루션에 사용할 수 있는 여러 설치 가능한 구성 요소를 제공합니다. 이를 통해 Azure 모니터 내보내기를 통해 원격 분석을 캡처하고 Azure Monitor에 보고하도록 Python 애플리케이션을 계측할 수 있습니다.

이 배포판은 다음 라이브러리를 자동으로 설치합니다.

Azure Monitor OpenTelemetry 내보내기
아래에 나열된 대로 공식적으로 지원되는 OpenTelemetry 계측 의 하위 집합입니다.

공식적으로 지원되는 계측

OpenTelemetry 계측을 사용하면 기본 계측된 라이브러리에서 보낸 요청을 자동으로 수집할 수 있습니다. 다음은 Azure 모니터 배포판과 함께 제공되는 OpenTelemetry 계측 목록입니다. 이러한 계측은 기본적으로 사용하도록 설정됩니다. 이러한 계측을 옵트아웃하는 방법은 아래 사용 량 섹션을 참조하세요.

계측	지원되는 라이브러리 이름	지원되는 버전
Azure Core 추적 OpenTelemetry	`azure_sdk`
OpenTelemetry Django 계측	장	링크
OpenTelemetry FastApi 계측	fastapi	링크
OpenTelemetry Flask 계측	flask	링크
OpenTelemetry Psycopg2 계측	psycopg2	링크
OpenTelemetry 요청 계측	requests	링크
OpenTelemetry UrlLib 계측	urllib	모두
OpenTelemetry UrlLib3 계측	urllib3	링크

다른 OpenTelemetry 계측에 대한 지원을 추가하려면 기능 요청을 제출하세요. 그동안 코드의 자체 API(예 instrument(): )를 통해 OpenTelemetry 계측을 수동으로 사용할 수 있습니다. 예제는 이 항목을 참조하세요.

주요 개념

이 패키지는 일련의 OpenTelemetry 및 Azure Monitor 구성 요소를 번들로 묶어 수집 및 원격 분석을 Azure Monitor로 보낼 수 있도록 합니다. MANUAL 계측의 경우 함수를 configure_azure_monitor 사용합니다. AUTOMATIC 계측은 아직 지원되지 않습니다.

Azure Monitor OpenTelemetry 내보내기는 이 작업을 수행하는 데 기본 구성 요소입니다. 이 패키지를 통해 내보내기 및 해당 API를 직접 사용할 수 있습니다. 원격 분석 수집을 사용하도록 설정하고 내보내기에서 OpenTelemetry 및 Azure Monitor 구성 요소가 작동하는 방식을 이해하려면 내보내기 설명서로 이동하세요.

현재 OpenTelemetry에서 사용할 수 있는 모든 계측은 베타 상태이므로 안정적이지 않으며 향후 호환성이 손상될 수 있습니다. 이러한 작업을 보다 안정적인 상태로 푸시하기 위한 노력이 이루어지고 있습니다.

시작

필수 구성 요소

이 패키지를 사용하려면 다음이 있어야 합니다.

Azure 구독 -체험 계정 만들기
Azure Monitor - 애플리케이션 인사이트를 사용하는 방법
Opentelemetry SDK - Python용 Opentelemetry SDK
Python 3.7 이상 - Python 설치

패키지 설치

pip를 사용하여 Azure Monitor Opentelemetry Distro를 설치합니다.

pip install azure-monitor-opentelemetry

사용량

를 사용하여 configure_azure_monitor 앱에 대한 계측을 Azure Monitor로 설정할 수 있습니다. 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 Core 추적 및 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 | 리소스 특성을 생성하는 데 사용할 Resource Detector를 지정하는 데 사용되는 실험적 OpenTelemetry 환경 변수입니다. 이는 실험적 기능이며 이 변수의 이름이며 해당 동작은 이전 버전과 호환되지 않는 방식으로 변경됩니다. 기본적으로 Azure App Service 및 Azure VM에 대해 Azure Resource Detectors를 사용하도록 설정하려면 "azure_app_service,azure_vm"로 설정됩니다. 특정 리소스 탐지기를 추가하거나 제거하려면 그에 따라 환경 변수를 설정합니다. 자세한 내용은 OpenTelemetry Python Resource Detector 설명서를 참조하세요 . |

Azure Monitor OpenTelemetry Exporter 구성

Azure Monitor 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 Monitor 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을 적절하게 데코레이팅해야 하는지 여부를 자동으로 결정합니다(예: 레이블, 설명). 봇에서 제공하는 지침을 따르기만 하면 됩니다. 이 작업은 CLA를 사용하여 모든 리포지토리에서 한 번만 수행하면 됩니다.

이 프로젝트에는 Microsoft Open Source Code of Conduct(Microsoft 오픈 소스 준수 사항)가 적용됩니다. 자세한 내용은 Code of Conduct FAQ(규정 FAQ)를 참조하세요. 또는 추가 질문이나 의견은 opencode@microsoft.com으로 문의하세요.

다음을 통해 공유