Python uygulamanız için iş parametrelerini ayıklayın - Cloud Monitor

Ön koşullar

Python uygulaması için ARMS Python aracı yüklüdür.
Python aracı sürümü 3.1.0 veya üzeridir.

Desteklenen kapsam

Aşağıdaki tabloda Python sürümü tarafından desteklenen parametre ayıklama türleri ve kaynakları açıklanmaktadır.

Parametre ayıklama türü	Parametre kaynağı	Desteklenen çerçeveler	Açıklama
HTTP sunucu isteği	Başlık, Sorgu Parametresi, Çerez, Gövde	Flask, Django, FastAPI	Gövde JSON formatında olmalıdır. Daha fazla bilgi için bkz. SSS.
HTTP sunucu yanıtı	Başlık, Gövde, Çerez	Flask, Django, FastAPI	Gövde JSON formatında olmalıdır. Çerez kaynağı, istek tarafındaki çerezi okur.
HTTP istemci isteği	Başlık, Sorgu Parametresi	requests, httpx, aiohttp, urllib3	İstemci, Gövde veya Çerez kaynaklarını desteklemez.
HTTP istemci yanıtı	Başlık	requests, httpx, aiohttp, urllib3	-

Gereksinim duyduğunuz parametre kaynağı desteklenen kapsamda yoksa OpenTelemetry SDK'yı kullanarak özel enstrümantasyon ekleyin ve iş parametrelerini bir Span'a Öznitelik olarak yazın.

Yapılandırma sayfasına erişme

ARMS konsoluna giriş yapın.
Sol gezinme bölmesinde Application Monitoring > Application List seçeneğini belirleyin. Üst menü çubuğundan hedef bölgeyi seçin ve ardından hedef Python uygulamasının adını tıklayın.
Sol gezinme bölmesinde Configuration seçeneğini tıklayın. Ardından Parameter Extraction Rule sekmesini tıklayın.

Yapılandırma sayfası iki bölümden oluşur:

Parameter Extraction Rule — İş parametresi ayıklama kuralları oluşturun, görüntüleyin ve değiştirin. ARMS aracı kural değişikliklerini dinamik olarak algılar ve etkinleştirilen tüm kurallara göre iş parametrelerini ayıklar.
Custom Error Settings — Ayıklanan iş parametresi değerleriyle eşleşecek özel hata kuralları yapılandırın. Eşleşme bulunursa ilgili Span hata olarak işaretlenir.

Ayıklama kuralı oluşturma

Parameter Extraction Rule bölümünde aşağıdaki adımları uygulayın:

Create Rule seçeneğini tıklayın.
Bir kural adı ve bir Öznitelik adı girin.
Bir parametre ayıklama türü seçin, aktif arayüzü yapılandırın ve kural için arayüz kapsamını belirtin.
Parametre ayıklama kuralı bölümünde parametre kaynakları ekleyin ve parametre işleme adımlarını yapılandırın. Birden çok parametre kaynağı ve işleme adımı yapılandırabilirsiniz. Birden çok kaynak parametreyi ayıklayabiliyorsa listede ilk sırada yer alan kaynak daha yüksek önceliğe sahiptir.
Kuralı etkinleştirip etkinleştirmeyeceğinizi ayarlayın ve ardından Save seçeneğini tıklayın.

Önemli

İlk ayıklama kuralınızı oluşturduğunuzda özelliğin etkili olması için uygulamayı yeniden başlatmanız gerekir. Sonraki kural ekleme veya değiştirme işlemleri yeniden başlatma gerektirmez. Kurallar, aracının sıcak yapılandırma güncellemesi aracılığıyla dinamik olarak iletilir ve 1 ila 2 dakika içinde etkili olur.

Bir kural oluşturulup etkinleştirildiğinde gerçek zamanlı olarak ARMS Python aracısına iletilir. Ayıklanan iş parametreleri ilgili çağrı izi Span'ının Özniteliklerinde kaydedilir. Parametreleri iz analiz sayfasında filtreleyebilir ve sorgulayabilirsiniz. Öznitelik adları varsayılan olarak biz. ön ekiyle başlar. Yinelenen Öznitelik adlarına izin verilmez.

Kural yapılandırması

Parametre	Açıklama
Kural adı	Kural için insan tarafından okunabilir bir ad.
Öznitelik adı	Ayıklanan değer için Span Öznitelik adı. Ad varsayılan olarak `biz.` ile başlar ve ardından birden çok kelime gelir. Her kelime yalnızca harf, rakam, tire (-) ve alt çizgi (_) içerebilir. Kelimeler nokta (.) ile ayrılmalıdır. En fazla 10 kelimeye izin verilir.
Parametre ayıklama türü	Ayıklanacak parametre türü (HTTP sunucu isteği/yanıtı, HTTP istemci isteği/yanıtı).
Aktif arayüz	Kural için arayüz kapsamı. Aracı yalnızca bu kuralla eşleşen arayüzlerden parametreleri ayıklar. Daha fazla bilgi için bkz. Aktif arayüzün nasıl eşleştiği.
Parametre ayıklama kuralı	Parametre için kaynak ve işleme yöntemi. Birden çok parametre kaynağı ve ayıklama adımı yapılandırabilirsiniz. Birden çok kaynak parametreyi ayıklayabiliyorsa listede ilk sırada yer alan kaynak daha yüksek önceliğe sahiptir.
Parametre kaynağı	Parametrenin gerçek kaynağı (Başlık, Sorgu Parametresi, Çerez veya Gövde).
Parametre işleme adımları	Parametre kaynağını ayrıştırmak ve nihai değeri ayıklamak için sıralı işleme adımları. Birden çok adım ekleyebilirsiniz. Önceki adımın çıktısı sonraki adımın girdisi olur. İşleme adımı eklenmezse ayıklanan değer kaynak nesnenin JSON metnidir.
Etkinleştir	Kuralın etkinleştirilip etkinleştirilmeyeceğini belirtir.

Parametre işleme yöntemleri

Aşağıdaki tabloda Python sürümü tarafından desteklenen parametre işleme yöntemleri açıklanmaktadır.

İşleme yöntemi	Giriş	Çıktı	Açıklama
JsonPath	JSON dizesi veya JSON nesnesi	Dize	Nokta gösterimli JsonPath ifadelerini destekler. Birden çok değer eşleşirse ilk değer kullanılır. Örnek: `$.data.code`.
Regex	Dize	Dize	Adlandırılmış gruplara sahip düzenli ifadeleri destekler. Ayıklanacak alt dize `res` adlı bir gruba karşılık gelir. Tam eşleşme semantiği kullanılır (düzenli ifadenin bir alt dize araması yerine tüm girişi eşleştirmesi gerekir). Örnek: `.from:(?<res>[a-z]+).`.

Aktif arayüzün nasıl eşleştiği

Eşleşme hedefi, Request method Route formatındaki Span adıdır; örneğin POST /api/order veya GET /api/user/{id}. Aşağıdaki hususları göz önünde bulundurun:

Equals /api/order eşleşmez. Bunun yerine Equals POST /api/order olarak yapılandırın.
Alternatif olarak Ends with /api/order kullanın.
Veya .*/api/order düzenli ifadesini kullanın (düzenli ifadeler de tam eşleşme semantiği kullanır).

Değer işleme

Kısaltma — Ayıklanan bir değer maksimum uzunluk sınırını (varsayılan olarak 100 karakter) aşarsa sonuna ... eklenerek kısaltılır. Daha uzun Gövde alanlarını ayıklamak için ayıklanan değer uzunluğu sınırını artırın.
Çoklu değer birleştirme — Aynı Başlık veya Sorgu Parametresi adı için birden çok değer varsa bunlar [a,b,c] formatında bir dizede birleştirilir.
Maskeleme — Maskeleme etkinleştirilirse ayıklanan değer *** ile değiştirilir.
Çerez — Aynı ada sahip birden çok çerez varsa son değer kullanılır. Yanıt aşamasındaki Çerez kaynağı istek tarafındaki çerezi okur.

Yapılandırmayı doğrulama

Bir parametre ayıklama kuralı yapılandırıldıktan sonra hemen etkili olur (ilk kural hariç; ilk kural uygulama yeniden başlatması gerektirir). Ayıklamanın çalıştığını doğrulamak için:

Yeni kural için Öznitelik adını bulun. Örneğin, Öznitelik adını orderCode olarak ayarlarsanız tam Öznitelik adı biz.orderCode olur.
İz analiz sayfasında attributes.<Attribute name> formatında (örneğin attributes.biz.orderCode) Öznitelik adını bir sorgu koşulu olarak ekleyerek ilgili Span'ları filtreleyin.
Bir izi tıklayın ve ardından Span Öznitelikleri panelini kontrol edin. Beklenen ayıklanan değerle biz.orderCode özniteliği görünüyorsa ayıklama kuralı etkili olmuştur.

Kuralları yönetme

Bir kuralı etkinleştirme veya devre dışı bırakma — Hedef kuralın sağ tarafındaki Enable anahtarını değiştirin.
Bir kuralı düzenleme veya silme — Hedef kuralın sağ tarafındaki Edit veya Delete seçeneğini tıklayın.
Toplu silme — Silinecek ayıklama kurallarını seçin ve ardından Batch Delete seçeneğini tıklayın.
Toplu kopyalama — Kopyalanacak ayıklama kurallarını seçin ve ardından Batch Copy to Other Applications seçeneğini tıklayın. İletişim kutusunda kuralların diğer tüm uygulamalara mı yoksa belirtilen uygulamalara mı kopyalanacağını seçin.
- Toplu kopyalamanın etkili olması 1 ila 2 dakika sürer.
- Yalnızca parametre ayıklama kuralları kopyalanır. İlişkili özel hata kuralları hedef uygulamaya kopyalanmaz.
- Hedef uygulamada zaten aynı Öznitelik adına sahip bir kural varsa kural kopyalanmaz.

SSS

Parametre ayıklamanın başarısız olmasına ne sebep olur?

Parametre ayıklama türü veya kaynağı desteklenen kapsamda değildir (örneğin istemci için Gövde veya Çerez kaynağı). Geçerli çerçevenin ve kaynağın desteklenip desteklenmediğini doğrulamak için bkz. Desteklenen kapsam.
Aktif arayüz eşleştirme kuralı yanlış yapılandırılmıştır. Eşleşme hedefi, Request method Route formatındaki Span adıdır. Equals /api/order gibi bir kural eşleşmez. Bkz. Aktif arayüzün nasıl eşleştiği.
Parametre işleme adımının sözdizimi hatalıdır veya giriş türü işleme yöntemi gereksinimleriyle eşleşmez:
- Regex, res adlı bir adlandırılmış grup içermeli ve tam eşleşme semantiği kullanmalıdır. Bir alt dizeyi eşleştirmek için her iki tarafa da .* ekleyin.
- JsonPath için giriş bir JSON nesnesi veya JSON metni olmalıdır. Düz bir dize üzerinde (örneğin Başlık değeri abc) JsonPath çalıştırmak sonuç üretmez.
Python aracı sürümü 3.1.0'dan öncektir ve iş parametresi ayıklamayı desteklemez.
İlk kural oluşturulduktan sonra uygulama yeniden başlatılmadı.

Gövde ayıklamanın başarısız olmasına ne sebep olur?

Uygulamanın istek veya yanıt gövdesini kendi okuma işlemini etkilememek için aracı Gövdeyi okumadan önce bir kabul kontrolü gerçekleştirir. Aşağıdaki koşullardan herhangi biri karşılanmazsa Gövde kaynağı tamamen atlanır (ayrıştırmadan önce kısaltılmaz):

Content-Type JSON değildir — Yalnızca application/json veya +json ile biten medya türleri desteklenir. text/plain, application/x-www-form-urlencoded, multipart/form-data ve ikili türler gibi türler ayıklanmaz.
Content-Length eksik veya sınırı aşıyor — İstek üstbilgisi Content-Length içermiyorsa (örneğin parçalı aktarım kodlaması) veya Gövde uzunluğu üst sınırı (varsayılan olarak 64 KB) aşarsa tüm Gövde atlanır.
Gövde geçerli UTF-8 kodlu JSON değildir — Kod çözme veya JSON ayrıştırma başarısız olursa Gövde atlanır.
Akış yanıtı — Flask akışı veya direct_passthrough yanıtları, Django StreamingHttpResponse ve FastAPI/Starlette StreamingResponse (SSE dahil) yanıt Gövdesini ayıklamaz.

Aşağıdakiler çerçeveye özgü senaryolardır:

FastAPI — İstek Gövdesi yalnızca uygulama onu gerçekten okuduğunda görünür; yani uç nokta bir Gövde parametresi (örneğin bir Pydantic modeli veya Body()) bildirir veya kod await request.body() ya da await request.json() çağrısını yapar. Uç nokta istek gövdesini okumazsa aracı istek akışını aktif olarak tüketmez ve Gövde ayıklanamaz.
Django — Uygulama önce istek akışını request.read() kullanarak tüketirse (RawPostDataException tetiklenir) veya Gövde Django'nun DATA_UPLOAD_MAX_MEMORY_SIZE sınırını aşarsa (RequestDataTooBig tetiklenir) Gövde ayıklanamaz. request.body üzerinden normal okuma işlemi etkilenmez (Django gövdeyi önbelleğe alır, böylece uygulama onu normal şekilde okuyabilir).
Flask — Aracı istek gövdesini request.get_data(cache=True) kullanarak okur ve önbelleğe alır. Uygulama daha sonra gövdeyi normal şekilde okumaya devam edebilir; ek sınırlama yoktur.

Ayıklanan değer beklentilerle eşleşmezse ne yapılır?

Değerin sonunda ... var: Değer ayıklanan değer uzunluğu sınırını (varsayılan olarak 100 karakter) aştı ve kısaltıldı. Uzunluk sınırını artırın.
Değer *** şeklindedir: Bu kural için veya genel olarak maskeleme etkinleştirilmiştir.
Değer [a,b] formatındadır: Aynı Başlık veya Sorgu Parametresi için birden çok değer vardır ve birleştirilmiştir.
JsonPath birden çok düğümle eşleştiğinde yalnızca ilk sonuç döndürülür.
Birden çok kural aynı Öznitelik adına yazdığında daha sonra uygulanan kural öncekinin üzerine yazar.

Form kodlu istek Gövdesinden form alanlarını ayıklamak için Sorgu Parametresi kaynağını kullanabilir miyim?

Hayır. İstek Content-Type değeri application/x-www-form-urlencoded olduğunda aracının çerçevenin form ayrıştırmasını tetiklemesini ve uygulamanın istek gövdesini kendi okumasını etkilemesini önlemek için Sorgu Parametresi kaynağı tamamen atlanır. Bu tür parametreler için bunları URL sorgu dizeleri veya Başlıklar aracılığıyla iletin ya da sonraki soruda açıklandığı gibi özel enstrümantasyon ekleyin.

Python sürümü tarafından desteklenmeyen iş parametresi kaynaklarını nasıl ayıklarım?

Python uygulamaları için OpenTelemetry SDK'yı kullanarak özel enstrümantasyon ekleyin ve iş parametrelerini bir Span'a Öznitelik olarak yazın.