Java SDK Trace

Per utilizzare l'SDK di tracciamento " Java " basato sulla configurazione, è necessario abilitare l'SDK di tracciamento " Java " come descritto nella sezione Abilitazione dell'SDK di tracciamento " Java ".

L'applicazione di esempio pubblicata (https://github.com/instana/instana-java-sdk/tree/master/instana-java-sdk-sample) contiene un client e un server CustomTCP , che illustra come l'SDK può essere utilizzato per contrassegnare voci, uscite ed eseguire correlazioni.

L'SDK Trace di Java richiede l'aggiunta di un file JAR alla tua applicazione. Questo file JAR contiene le annotazioni e le classi di supporto utilizzate per contrassegnare le sezioni di codice che Instana dovrebbe gestire. Quando si utilizza Maven, è possibile aggiungere facilmente la dipendenza con:

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

L'artefatto instana-java-sdk è disponibile nel repository centrale predefinito Maven.

Quando nessun agente sta monitorando l' JVM, che include questa libreria e contiene sezioni contrassegnate da annotazioni, queste ultime agiscono come operazioni nulle (No-Op). L'uso delle annotazioni è sicuro: non hanno alcun effetto fintanto che nessun agente sta monitorando l' JVM Affinché un agente di Instana possa effettivamente utilizzare le annotazioni, è necessario indicargli quali nomi di pacchetti Java contengono tali annotazioni. Questo perché la ricerca delle annotazioni è un'operazione complessa e la scansione dell'intero percorso di classe di applicazioni di grandi dimensioni può richiedere molto tempo.

La sezione configuration.yaml richiesta ha questo aspetto:

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

I pacchetti sono scansati in modo ricorsivo. In altre parole, se com.mycompany.backend è configurato per essere sottoposto a scansione per le annotazioni, anche com.mycompany.backend.impl e altri pacchetti secondari verranno sottoposti a scansione.

Per contrassegnare un metodo in un span Intermediat basta aggiungere la seguente annotazione:

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

Intermedio è il tipo predefinito di SDK spans e utilizzato se non indicato diversamente. Questo tipo di spans segna metodi "interessanti" nella tua applicazione su cui vuoi avere una migliore visibilità. Si prega di tenere presente che questo strumento non sostituisce un vero e proprio profiler, come il nostro Instana AutoProfile™.

Per contrassegnare un metodo in un elemento Entry, basta aggiungere la seguente annotazione, come mostrato in questo esempio :

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

Non appena Instana rileva l'ingresso di codice in questo metodo, viene avviata una traccia. Gli spans entry normalmente indicano chiamate in entrata da sistemi esterni o da attività pianificate.

Per contrassegnare un metodo in un blocco Exit, basta aggiungere la seguente annotazione, come mostrato in questo esempio :

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

Ogni volta che si incontra questo metodo, Instana registrerà uno span contrassegnandolo come chiamata di uscita. Esce contrassegnare le chiamate in uscita verso sistemi esterni.

In molti casi in cui Instana non conosce ancora i punti di uscita e di ingresso, le applicazioni li utilizzano per effettuare una qualche forma di comunicazione remota. Quando viene incontrata una Uscita e non viene eseguita alcuna correlazione, la traccia "rompe", si sarebbero osservate due tracce, una finale all'uscita, e una nuova a partire dalla Voce.

È possibile aiutare Instana a eseguire una correlazione trasferendo manualmente le informazioni di correlazione tramite la comunicazione remota. Sul lato di uscita, l'annotazione di uscita farà in modo che gli identificativi di correlazione richiesti esistano. È sufficiente richiamare ( 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);

per riempire la mappa dei param indicati con gli ID richiesti. Qualora il protocollo supportasse altri mezzi di trasporto di altri dati, è possibile ottenere gli ID con:

currentTraceId(type)

currentSpanId(type)

Sul lato di ingresso è importante leggere i parametri e impostarli per la Voce Spano, prima che l'apertura venga creata da annotazioni:

(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));

Così facendo, la Voce Span si unirà automaticamente alla traccia remota e si aggiungerà come span child dell'uscita chiamante.

In determinate situazioni potrebbe essere utile convertire gli span SDK in un tipo diverso, come ad esempio HTTP o RPC, per rappresentare meglio l'origine di tali span. Ciò può essere fatto aggiungendo i tag di conversione agli span, come descritto nella sezione dedicata ai tag di elaborazione delle linee guida sulle migliori pratiche per il tracciamento personalizzato.

Queste tag possono essere impostate utilizzando il metodo SpanSupport.annotate(type, name, key, value) .

Instana tratterà questi tag secondo il funzionamento della strumentazione automatica degli agenti non appena questi campi saranno annidati sotto la tags. chiave. Quindi, ad esempio, per impostare il campo http.url , la chiamata del metodo dovrebbe essere simile alla seguente:

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

Allo stesso modo, è anche possibile modificare il servizio, l'endpoint e il nome della chiamata, come descritto nella pagina dedicata alle migliori pratiche per il tracciamento personalizzato.

Quando non viene fornito alcun campo specifico, il nome del servizio per tutte le aree SDK sarà SDK. L'endpoint e il nome della chiamata saranno il name fornito nell'annotazione @Span o il metodo SpanSupport.annotate() .

La classe ContextSupport consente di salvare e ripristinare il contesto di traccia corrente. Il metodo takeSnapshot() memorizza le informazioni sul contesto di traccia, come l'ID traccia e l'ID estensione, in una associazione interna. Il metodo restoreSnapshot() legge le informazioni salvate dal metodo takeSnapshot() e le utilizza per impostare il contesto di traccia corrente. Questi metodi sono utili nelle situazioni in cui un'applicazione utilizza l'elaborazione asincrona per completare un'attività e la traccia deve essere continuata in un altro thread.

Ad esempio, il contesto di traccia corrente può essere salvato con:

snapShotKey = ContextSupport.takeSnapshot();

Poi, il contesto di traccia può essere ripristinato in un altro thread con:

ContextSupport.restoreSnapshot(snapShotKey);

I seguenti tutorial ti guideranno attraverso alcuni dei casi d'uso più comuni dell'SDK Trace di Java :

• Implementazione di un framework personalizzato per l' Java HTTP
• Implementazione di uno scheduler personalizzato
• Implementazione di una funzione intermedia personalizzata

Qualora le tracce SDK non si presentino nella UI, diversi articoli valgono la verifica:

• Il jar instana-java-sdk viene fornito con l'applicazione? In caso contrario, l'agent non eseguirà alcuna operazione in modalità non presidiata, poiché è in modalità no-op .
• Il file configuration.yaml fa riferimento a tutti i package con annotazioni?
• Il tracciamento è attivo?
• La sintassi di YAML è corretta?
• Gli altri agenti APM sono attivi? È noto che la maggior parte degli altri agenti APM interferisce con Instana; pertanto, l'agente di Instana non eseguirà il tracciamento se rileva la presenza di altri agenti. In tal caso, comparirà nei log quanto segue:

  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.
   

• Attiva la registrazione DEBUG e cerca un messaggio simile a questo:

  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. 
   

• I metodi annotati sono effettivamente colpiti da un driver utente / di caricamento? L'agente " Instana " interagirà con ogni istanza di " JVM " poco dopo il suo avvio. Di conseguenza, le transazioni che si verificano prima che l'agent collegato non vengono catturate. Assicurati di annotare i metodi che normalmente vengono utilizzati durante il ciclo di vita dell'applicazione.
• Segui i passaggi indicati nella sezione "Verifica della configurazione dell'SDK ".