Yapılanış Tabanlı Java İzleme SDK

Yapılandırma tabanlı Java Trace SDK, yayılmaların taşıması gereken yayılma ve etiketlerin bildirimsel bir belirtimini etkinleştirir ve uygulamanızın belirli yöntemlerini yürüterek yayılır.
İfade edilebilirlik, programlı Java Trace SDK' nın @Span ek açıklaması ve SpanSupport.annotate() olanaklarıyla karşılaştırılabilir.

Özel izlemeyi uygulamadan önce izleme en iyi uygulamalarıbaşlıklı konuyu okuyun.

Giriş

Yapılandırma tabanlı SDK, uygulamanızdaki değişikliklere karşı kırılgan. Bir sınıfı ya da yöntemi yeniden adlandırabilirsiniz ve birden yapılandırma eşleşmez ve izleme verilerinizi kaybedersiniz. Mümkün olduğunda, kod değişikliklerine karşı çok daha esnek olan ve hedeflerinize ulaşmanıza yardımcı olacak daha fazla özelliğe sahip Java Trace SDK' yı kullanmanız önerilir.

Yapılandırma

Yapılanış tabanlı Java İzleme SDK 'yı kullanmak için, Java İzleme SDK' yı Java İzlemenin Etkinleştirilmesi ve Geçersiz Kılınmasıkonusunda açıklandığı gibi etkinleştirmeniz gerekir.

Notlar:

  • Yapılanış tabanlı Java İzleme SDK ' nın yapılanışında yapılan değişiklikler, YönOrtamıAna aracısı tarafından otomatik olarak alınır. Değiştirilen yapılandırmayı kullanmak için önceden izleme kodu eklenmiş uygulamaların yeniden başlatılması gerekir.

  • Yapılanış tabanlı Java Trace SDK, 1.2.351 Java Trace Sensor sürümünde ya da daha sonraki bir sürümde bulunur.

Biçim

Aşağıdaki listede yapılandırmanın genel biçimi açıklanmaktadır:

# Java Tracing
com.instana.plugin.javatrace:
  instrumentation:
    sdk:
      targets:
        - match:
            type: 'interface'|'class'|'baseclass'
            name: '<type-name>'
            method: '<method-name>'
            [argumentTypes:
      	      - '<argument-type-index0>'
    	      - '<argument-type-indexn>']
            [returnType: '<return-type-name>']
          span:
            name: '<span-name>'
            [type: '<span-type>']
            [stackDepth: <depth>]
            [tags:
              - kind: 'argument'
                name: 'name'
                index: 0
              - kind: 'return'
                name: 'name'
              - kind: 'constant'
                name: 'name'
                value: 'constant-value']

targets anahtarı içinde her biri bir aralık yaratılacağını belirten birden çok hedef tanımlanabilir.
Bir target nesnesinin match nesnesi, özel işlemden geçirmenin uygulanacağı yöntemi belirtir.
span nesnesi, adını (örneğin call.name süzgeci için Unbounded Analytics 'te kullanılan) ve hangi etiketlerin ayarlanması gerektiğini de içeren kapsamanın nasıl oluşturulacağını belirtir.

İzleme kodu eklemek için yöntemleri eşleştirme

NOT: Arabirimler ya da temel sınıflar, özellikle çok sayıda sınıf kullanan uygulamalarda çok kaynak yoğun olabilir ve mümkünse önlenmelidir.

Bu nesne, özel işlemden geçirilecek kod noktasını tanımlar:

  • type: Özel işlemden kullanılacak kodun tipi; desteklenen değerler:
    • class, somut bir sınıfla eşleştir
    • interface, arabirimi gerçekleştiren tüm sınıfları eşleştir
    • baseclass, temel sınıfı genişleten tüm sınıfları eşleştir
  • name:
    İçiçe sınıflar için a.b.c.OutsideClass$NestedClass ile eşleşecek sınıfın, arabirimin ya da temel sınıfın tam olarak nitelenmiş adı
  • method: Bir çağırmanın kaydedilmesi gereken, verili sınıfın, arabirimin ya da temel sınıfın yönteminin adı
  • argumentTypes: Eşleştirilecek yöntemin tam olarak nitelenmiş bağımsız değişken tiplerinin listesi (isteğe bağlı)
    • Eksikse, bağımsız değişkenler eşleşmez ve fazla yükleme durumunda tüm yönteme özel işlemden geçirme uygulanır
    • Varsa, tüm bağımsız değişkenlerin verilen tiplerle sırayla eşleşmesi gerekir; tersi durumda, yöntem eşleşmez.
  • returnType: Eşleştirilecek yöntemin tam olarak nitelenmiş dönüş tipi (isteğe bağlı)
    • Eksikse, dönüş tipi dikkate alınmaz
    • Varsa, dönüş tipinin verili tiple eşleşmesi gerekir; tersi durumda, yöntem eşleşmez

Spans 'ın nasıl görüneceğini belirleme

Bu nesne, match içinde açıklanan yöntem çağrılırsa yaratılacak aralık özelliklerini tanımlar:

  • name: Span name (Span adı)
  • type: Span tipi (isteğe bağlı); desteklenen değerler:
    • ENTRY, dış sistemlerden gelen çağrıları belirtmek için kullanılır
    • INTERMEDIATE, "ilginç" yöntemlere iç çağrıları yakalamak için kullanılır (varsayılan)
    • EXIT, dış sistemlere yönelik "giden" çağrıları belirtmek için kullanılır
  • stackDepth: Yöntem çağrısının yakalanacak yığın çerçevesi sayısı (isteğe bağlı); varsayılan değer 0
  • tags: Yakaladığınız etiketlerin/ek açıklamaların listesi ve bunların değerlerinin nasıl elde edileceği (isteğe bağlı); desteklenen değerler:
    • constant, sabit bir değer yakalayın
      • kind: constant
      • name: Yaratılacak etiketin adı
      • value: Yaratılacak etiketin değişmez değeri
    • return, yöntem çağrısının dönüş değerini yakalayın
      • kind: return
      • name: Yaratılacak etiketin adı; değer, döndürülen nesnenin değeri olacaktır
    • argument, yöntem çağrısının belirli bir bağımsız değişken değerini yakalayın
      • kind: argument
      • name: Yaratılacak etiketin adı
      • index: etiketin değeri olarak yakalanacak bağımsız değişkenin 0 tabanlı dizini

NOT: Yakalanan değer null ya da Optional.empty ise, tanımlı etiket eklenmez. Etiketleri eksik olan boyutlar, call.tag süzgeciyle birlikte is not present işleci kullanılarak Unbounded Analytics (sınırsız Analitik) içinde aranabilir.

Hatalı Harcamalar

Bir Throwable özel işlemden geçirilmiş bir yöntemin dışına yayılırsa, aralık otomatik olarak hatalı olarak işaretlenir ve Throwable#getMessage() değeri, call.error.message etiketi aracılığıyla Unbounded Analytics içinde arama yapabileceğiniz hata iletisi olarak ayarlanır.

Örnek

Aşağıdaki kod parçacığı, bir uygulamanın toplu işleri işlemesinin nasıl izlenebileceğine ilişkin örnek bir yapılandırmayı göstermektedir:

com.instana.plugin.javatrace:
  instrumentation:
    sdk:
      targets:
        - match:
            type: class
            name: com.instana.java.sdk.BatchApplication
            method: processBatch
          span:
            name: Job
            type: ENTRY
            stackDepth: 2
            tags:
              - kind: constant
                name: endpoint
                value: BatchJob
              - kind: argument
                name: batch.job
                index: 0
        - match:
            type: class
            name: com.instana.java.sdk.BatchApplication
            method: updateDatabase
          span:
            name: DatabaseCall
            type: EXIT
            stackDepth: 2
            tags:
              - kind: constant
                name: db.connection_string
                value: jdbc:mysql://127.0.0.1:3306/jobs
              - kind: argument
                name: db.statement
                index: 0

İlk olarak, com.instana.java.sdk.BatchApplication sınıfındaki processBatch yöntemine Jobadlı giriş yayımevleri, endpoint değişmez değeri BatchJobolan ek açıklama ve değeri birinci bağımsız değişkeni olan batch.job ek açıklaması yaratma izleme kodu eklendi.

Furthermore, outgoing DB calls during the batch processing, that is invocations of method updateDatabase in the same class, will create exit spans with name DatabaseCall and the annotation db.connection_string with the constant value jdbc:mysql://127.0.0.1:3306/jobs and annotation db.statement with the first argument of the method invocation.

processBatch ile yeni bir toplu işin işlenmesi yeni bir izleme başlatır ve sonraki veritabanı güncellemeleri updateDatabase ile birlikte alt öğe yayımı olarak listelenir. Unbounded Analytics gibi tüm Instana özellikleri, AutoTraceYönOrtamıyla yaratılan izlerle aynı şekilde kullanılabilir.

Sınırlamaları

Yapılanış tabanlı Java Trace SDK için aşağıdaki kısıtlamalar geçerlidir:

  • Oluşturuculara izleme kodu ekleme desteklenmiyor.
  • Bir yöntemde bir kapsama başlatılıp başka bir yöntemde kapatılması desteklenmez; başka bir deyişle, yapılandırma tabanlı SDK ' nın @Span.Start ve @Span.End ek açıklamalarının eşdeğeri yoktur.
  • Belirtik olarak tag yaratmadan tüm bağımsız değişkenlerin ya da dönüş değerinin yakalanması desteklenmez.
  • Önemsiz bağımsız değişkenler için bağımsız değişken listesinde yer tutucuların belirtilmesi ya da "all the rest" desteklenmez; bağımsız değişkenlere dayalı eşleşme sıkı bir şekilde yürütülür.
  • Sınıflar ya da yöntemler için ad örüntülerinin belirtilmesi desteklenmez.
  • Bir aralık oluşturmadan önce bir izleme bağlamının geri yüklenmesi desteklenmez; yani, yapılandırma tabanlı SDK ' nın SpanSupport.inheritNext()ile eşdeğer bir yeteneği yoktur.