Java İzleme SDK

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.

Özel İkili İletişim Kuralına İlişkin Çıkışlar ve Girdiler

Yayınlanan örnek uygulama (https://github.com/instana/instana-java-sdk/tree/master/instana-java-sdk-sample), SDK ' nın girdileri işaretlemek, çıkışları ve ilintileri gerçekleştirmek için nasıl kullanılabileceğini gösteren bir CustomTCP sunucusu ve istemcisi içerir.

instana-java-sdk 'nin kullanılması

Java İzleme SDK, uygulamanıza küçük bir jar dosyası eklemenizi gerektirir. Bu jar dosyası, YönOrtamın işlemesi gereken kod kısımlarını biçimlemek için kullanılan ek açıklamaları ve yardımcı sınıfları içerir. Maven kullanılırken, bağımlılık aşağıdaki yöntemlerle kolayca eklenebilir:

<dependency>
  <groupId>com.instana</groupId>
  <artifactId>instana-java-sdk</artifactId>
  <version>1.2.0</version>
</dependency>

instana-java-sdk yapay nesnesi, varsayılan Maven merkezi havuzundan kullanılabilir.

Yukarıdaki kitaplığı içeren ve ek açıklamalarla işaretlenmiş kısımları olan JVM ' yi izleyen bir aracı yoksa, bunlar No-Op olarak işlev görür. Ek açıklamaların kullanılması güvenlidir; hiçbir aracı JVM ' yi izlemediği sürece bunların herhangi bir etkisi olmaz. Bir Yönlendirici aracısının ek açıklamalardan yararlanmasını sağlamak için, bu ek açıklamaları hangi Java paket adlarında olduğunu söylemeniz gerekir. Bunun nedeni, ek açıklama taramasının ağır sıklet işlemi olmasıdır ve büyük uygulamaların tam sınıf yolunun taranması uzun sürebilir.

Gerekli configuration.yaml bölümü şöyle görünür:

# Java Tracing
com.instana.plugin.javatrace:
  instrumentation:
    # By default no packages are scanned for SDK annotations.
    sdk:
      packages:
        - 'com.mycompany.backend'
        - 'com.mycompany.frontend'

Paketler özyinelemeli olarak taranır. Yani, com.mycompany.backend ek açıklamalar için taranmak üzere yapılandırıldıysa, com.mycompany.backend.impl ve diğer alt paketler de taranır.

Ara Düzey İmleme

Bir yöntemi Intermediat aralığında işaretlemek için aşağıdaki ek açıklamayı ekleyin:

@Span(value = "custom-tcp-server")

Ara düzey, SDK yayılarının varsayılan tipidir ve aksi belirtilmemişse kullanılır. Bu tür uygulamalar, daha iyi görünürlük elde etmek istediğiniz uygulamanızda "ilginç" yöntemleri işaretler. Lütfen bunun Instana AutoProfile™gibi gerçek bir profilciye göre bir ikame olmadığını unutmayın.

Girdiyi İmleme

Bir yöntemi Giriş aralığında işaretlemek için, aşağıdaki ek açıklamayı bu örnektegösterildiği gibi ekleyin:

@Span(type = Type.ENTRY, value = "custom-tcp-server")

Instana bu yönteme giren kodu görür görmez bir izleme başlatılır. Giriş yayılır, genellikle dış sistemlerden ya da zamanlanmış görevlerden gelen çağrıları gösterir.

Çıkışı İmleme

Bir yöntemi Çıkış aralığında işaretlemek için, aşağıdaki ek açıklamayı bu örnektegösterildiği gibi ekleyin:

@Span(type = Type.EXIT, value = "custom-tcp-client", capturedStackFrames = 5)

Bu yöntemle karşılaşıldığında, YönOrtamıana bunu Çıkış çağrısı olarak etiketleyen bir aralık kaydeder. Dış sistemlere giden çağrıları işaretlemektedir.

Çıkış ve Girdinin İlintileri

Bir Çıkış ve Giriş 'in henüz YönOrtamı'nında bilinmediği birçok durumda, uygulamalar bunları bir tür uzak iletişim gerçekleştirmek için kullanır. Bir Çıkış ile karşılaşıldığında ve ilinti gerçekleştirilmezken, izleme "kesilir"; bu, biri Çıkış ile biten, diğeri de Girdiden başlayan iki izlemenin gözlemleneceği anlamına gelir.

Instana 'nın uzak iletişim boyunca ilişkilendirme bilgilerini el ile taşıyarak bir ilişkilendirme gerçekleştirmesine yardımcı olabilir. Çıkış tarafında, çıkış ek açıklaması gerekli ilinti tanıtıcılarının var olduğunu doğrulayın. Basitçe çağrılabilir (https://github.com/instana/instana-java-sdk/blob/master/instana-java-sdk/src/main/java/com/instana/sdk/support/SpanSupport.java#L182):

SpanSupport.addTraceHeadersIfTracing(Type.EXIT, params);

Belirtilen değiştirgeler eşlemini gereken tanıtıcılarla doldurmak için. Protokol diğer veri taşıma yöntemlerinin desteklenmesini destekliyorsa, kimlikler aşağıdaki özelliklere sahip olabilir:

currentTraceId(type)

currentSpanId(type)

Giriş tarafında, aralık ek açıklamalarla yaratılmadan önce parametreleri okumak ve Giriş Span için ayarlamak önemlidir:

(https://github.com/instana/instana-java-sdk/blob/master/instana-java-sdk-sample/custom-http-sample/src/main/java/com/instana/sample/GreetingHandler.java#L52):

SpanSupport.inheritNext(SpanSupport.stringAsId(trace), SpanSupport.stringAsId(span));

Bunu yaparak, Entry Span otomatik olarak uzak izlemeye katılır ve kendisini çağıran Exit 'in alt öğesi olarak ekler.

Dönüştürme ve Adlandırma

Bazı durumlarda, SDK ' ların HTTP ya da RPC gibi farklı bir tipe dönüştürülmesi, bu yayılımın kökenini daha iyi temsil etmek için yararlı olabilir. Bu, özel izleme için en iyi uygulamalarbölümünün işleme etiketleri bölümünde açıklandığı gibi, yayıllara dönüştürme etiketleri eklenerek yapılabilir.

Bu etiketler, SpanSupport.annotate(type, name, key, value) yöntemi kullanılarak ayarlanabilir.

Instana bu etiketleri, bu alanlar tags. tuşunun altına yerleştirilir yerleştirilmez otomatik aracı özel işlemiyle aynı şekilde işler. Örneğin, http.url alanını ayarlamak için yöntem çağrısı şöyle görünür:

SpanSupport.annotate(<type>, <name>, "tags.http.url", "service://my-awesome-service/some/path")

Aynı şekilde, özel izleme için en iyi uygulamalar sayfasında açıklandığı gibi hizmet, uç nokta ve çağrı adını da değiştirebilirsiniz.

Belirli bir alan sağlanmadığı zaman, tüm SDK yayılılarına ilişkin hizmetin adı SDKolur. Uç nokta ve çağrı adı, @Span ek açıklamasında ya da SpanSupport.annotate() yönteminde verilen name olur.

İzleme Bağlamının Saklanması ve Geri Yüklenmesi

ContextSupport sınıfı, yürürlükteki izleme bağlamının saklanmasını ve geri yüklenmesini sağlar. takeSnapshot() yöntemi, izleme tanıtıcısı ve kapsam tanıtıcısı gibi izleme bağlamı bilgilerini bir iç eşlemde saklar. restoreSnapshot() yöntemi, takeSnapshot() yöntemiyle saklanan bilgileri okur ve yürürlükteki izleme bağlamını ayarlamak için bu bilgileri kullanır. Bu yöntemler, bir uygulamanın bir görevi tamamlamak için zamanuyumsuz işleme kullandığı ve izlemenin başka bir iş parçacığında sürdürülmesi gereken durumlarda kullanışlıdır.

Örneğin, yürürlükteki izleme bağlamı aşağıdakilerle saklanabilir:

snapShotKey = ContextSupport.takeSnapshot();

Daha sonra, izleme bağlamı aşağıdaki gibi başka bir iş parçacığında geri yüklenebilir:

ContextSupport.restoreSnapshot(snapShotKey);

Eğitim Programları

Aşağıdaki eğitmenler, Java Trace SDK ' ya ilişkin bazı yaygın kullanım senaryoları boyunca size yol gösterir:

• Özel Java HTTP Çerçevesine İzleme Kodu Oluşturma
• Özel Zamanlayıcı İzleme Kodu Oluşturma

Sorun Giderme

SDK izlemeleri kullanıcı arabiriminde gösterilmese, birkaç öğe denetlemeye değer:

• instana-java-sdk jar dosyası uygulamayla birlikte mi gönderildi? Değilse, aracı no-op kipinde olduğu gibi sessiz bir şekilde hiçbir şey yapmaz.
• configuration.yaml kütük ek açıklamalarla tüm paketlere gönderme yapıyor mu?
• İzleme etkin mi?
• YAML sözdizimi doğru mu?
• Diğer APM aracıları etkin mi? Diğer APM ajanlarının çoğunun Instana 'ya müdahale edeceği bilinmektedir, bu nedenle, Instana 'nın ajanı diğer ajanları tespit ederse izleme gerçekleştirmeyecektir. Böyle bir durumda, günlüklerde aşağıdaki öğeler görüntülenir:

  JVM <PID> is running the <3rdParty> agent, which is known to be causing problems for the Instana Agent. Tracing will not be enabled for this JVM.
  

• DEBUG günlüğe kaydetmeyi açın ve aşağıdaki gibi bir ileti arayın:

  2016-09-05T08:26:14.094+0200 | DEBUG | na-http-thread-1 | LoggerEndpoint                   | 48 - com.instana.agent - 1.1.194 | JVM (11403). Successfully instrumented class com.acme.resources.HelloWorldResource [sun.misc.Launcher$AppClassLoader@3d4eac69]`
  2016-09-05T08:26:14.145+0200 | DEBUG | na-http-thread-1 | LoggerEndpoint                   | 48 - com.instana.agent - 1.1.194 | JVM (11403) - Spent 188ms and 124kb transforming SDK classes. 
  

• Ek açıklamalı yöntemlere gerçekten bir kullanıcı/yükleme sürücüsü tarafından mı rastlandı? Instana aracısı, başlatıldıktan kısa bir süre sonra her JVM ile etkileşimde bulunur. Sonuç olarak, aracı eklenmeden önce gerçekleşen işlemler yakalanmaz. Uygulamanın kullanım ömrü boyunca olağan olarak vurulmuş yöntemlere ek açıklama eklerken emin olun.

SSS