• Acquisisci eventi APM in registrazioni JFR
• Configura eventi JFR in Tracer APM
• Creazione di un file ACML
• Domande frequenti

1. Assicurarsi che APM Tracer funzioni correttamente.

   Aprire Trace Explorer e confermare di poter visualizzare tutti i trace. Per informazioni sull'apertura e l'utilizzo di Trace Explorer, vedere Monitorare i trace in Trace Explorer.

2. Aggiungere una dipendenza al progetto Maven che consentirà all'APM Tracer di aggiungere eventi nelle registrazioni JFR effettuate dalla JVM Helidon.

   <dependency>
       <groupId>com.oracle.apm.agent.java</groupId>
       <artifactId>apm-java-agent-jfr11</artifactId>
       <version>[1.0.1389,)</version>
   </dependency>

3. Avvia una registrazione.

   Per verificare che tutto funzioni correttamente, è necessario avviare una registrazione utilizzando il metodo preferito (potrebbe essere l'utilizzo dell'interfaccia utente JDK Mission Control o della utility della riga di comando JCMD). Dopo l'avvio di una registrazione, gli eventi di trace vengono visualizzati nell'interfaccia utente di JDK Mission Control quando la registrazione viene visualizzata.

   Per verificare che gli eventi di trace APM vengano aggiunti correttamente alle registrazioni JFR, connettersi a JDK Mission Control e confermare che i trace APM siano visibili in Event Browser: fare clic su APM OpenTracing e confermare che gli eventi di trace APM siano visibili.

• Caso 1: tag component

  Questo è il modo più semplice per classificare un evento. Questo è il metodo consigliato.

  Nella maggior parte degli scenari, l'intervallo Opentracing conterrà una tag denominata component. Il valore del tag component viene utilizzato per determinare il tipo di evento.

  Ad esempio, vedere il seguente intervallo:

  {  "id":"e926ff3d06013045",
    "trace-id":"49abd92e69786853e926ff3d06013045",
    "parent-id":"6ef54ec2c524c99a",
    "name":"content-write",
    "ts-micros":1614190751360177,
    "td-micros":219348,
    "attributes":{
      "server":"Helidon SE",
      "http.url":"http://localhost:8079/health",
      "http.status_code":200,
      "component":"helidon-webserver",
      "http.method":"GET",
      "organization":"development"
    },
    "events":[
    ]
  },

  In questo caso all'evento generato verrà assegnato un tipo di evento helidon-webserver in quanto è il valore del tag component.

• Caso 2: Altro tag

  Se l'applicazione non utilizza il tag component, ma utilizza un altro tag o esiste una libreria che sta generando i tag automaticamente, APM Tracer può essere configurato per leggere il tipo di evento da tale altro tag.

  Ad esempio, vedere il seguente intervallo in cui è possibile leggere il tipo di evento dalla tag denominata span.type:

  {  "id":"e926ff3d06013045",
    "trace-id":"49abd92e69786853e926ff3d06013045",
    "parent-id":"6ef54ec2c524c99a",
    "name":"content-write",
    "ts-micros":1614190751360177,
    "td-micros":219348,
    "attributes":{
      "server":"Helidon SE",
      "http.url":"http://localhost:8079/health",
      "http.status_code":200,
      "span.type":"helidon-webserver",
      "http.method":"GET",
      "organization":"development"
    },
    "events":[
    ]
  },

  In questo caso, è possibile fare in modo che APM Tracer legga il tipo di evento dalla tag span.type utilizzando la seguente proprietà di sistema all'avvio dell'applicazione java:

  java -Dcom.oracle.apm.agent.jfr.category.tag=span.type ...

• Caso 3: utilizzare il nome dell'operazione se non sono disponibili tag

  Se l'applicazione non utilizza tag con categorie utili, è possibile utilizzare Operation Name per determinare il tipo di evento, ma questo metodo non è consigliato.

  Il sistema JFR richiede che il nome del tipo di evento sia un identificativo Java valido, ma Operation Name spesso contiene spazi e anche altri caratteri non validi. APM Tracer convertirà Operation Name in un identificativo valido sostituendo tutti i caratteri non validi con un carattere di sottolineatura.

  java -Dcom.oracle.apm.agent.jfr.category.default=ORACLE_APM_USE_SPAN_OPERATION_NAMES

  Nota
  
  Il tag Operation Name verrà utilizzato solo se il tag della categoria è mancante o vuoto.

  Questa non è una soluzione semplice perché Operation Name può contenere token univoci come ID che renderanno ogni evento nel proprio tipo di evento. Inoltre, la conversione del Operation Name in un identificatore valido causerà ulteriori problemi nella configurazione del tipo di evento per impostare i campi necessari nell'evento e, inoltre, la configurazione dovrà essere eseguita in base al Operation Name convertito, altrimenti sarebbe necessario configurare molte varianti diverse del Operation Name nello stesso modo.

• Caso 4: non sono disponibili tag e tutti i nomi operazione sono univoci

  In questo caso non sono disponibili informazioni per classificare i tipi di evento. Questo è lo scenario peggiore in cui tutti gli eventi finiranno come lo stesso tipo di evento oppure tutti finiranno per essere univoci se sono configurati utilizzando lo scenario caso d'uso 3 come mostrato sopra. L'unica cosa che si può fare è consentire di scegliere il nome di questo tipo di evento predefinito e questo può essere configurato come mostrato di seguito.

  java -Dcom.oracle.apm.agent.jfr.category.default=Unknown

  Nota
  
  Il valore predefinito verrà utilizzato solo se il tag della categoria è mancante o vuoto.

  In questo caso, tutti gli eventi vengono inseriti nel tipo di evento Unknown o in qualsiasi valore personalizzato selezionato.

caseSensitiveFieldName: false
recordCallStack: true

eventTypes:
  helidon-webserver:
    name: helidon-webserver
    label: Helidon Webserver Events
    description: All events based on helidon webserver
    recordCallStack: true
    # All fields must be provided here.
    # Fields are NOT incremental since that would make them impossible to remove 
    fields:
      - name: traceID
        type: String
        label: New Trace ID
        description: New Opentracing Trace ID
      - name: spanID
        type: String
        label: New Span ID
        description: New Opentracing Span ID
      - name: http.url
        type: String
        label: New HTTP URL
        description: The New URL for the HTTP endpoint being hit
      - name: organization
        type: String
        label: Organization
        description: The New Organization value of this call
      - name: startThread
        type: Thread
        label: Start Thread
        description: The thread on which this event started
      - name: http.status_code
        type: int
        label: Status Code
        description: The HTTP Response status code
      - name: http.method
        type: String
        label: HTTP Method
        description: The HTTP Method

1. Quando sono disponibili entrambe le impostazioni: proprietà com.oracle.apm.agent.jfr.category.tag e com.oracle.apm.agent.jfr.category.default, quale impostazione ha la priorità?

   Se entrambi ricevono un valore, esamineremo prima l'intervallo per il tag della categoria. Se viene trovato, verrà utilizzato. Se manca, verrà utilizzato il valore predefinito.

2. Per APM Tracer, è obbligatorio un file di configurazione? È possibile specificare solo le proprietà senza file?

   Un file di configurazione non è obbligatorio. Se l'impostazione predefinita funziona correttamente, non è necessario un file di configurazione ed è comunque possibile specificare le proprietà.

3. In alcuni casi, perché le voci vengono duplicate? Ad esempio, il seguente snippet del file di configurazione ACML contiene due volte la voce helidon-webserver:

   eventTypes:
     helidon-webserver:
       name: helidon-webserver

   La prima voce helidon-webserver è quella che viene letta/dedotta dalle tag o dal nome dell'operazione. Se il tipo di evento è pulito, facile da preparare e intuitivo, come l'esempio precedente, è possibile utilizzare lo stesso tipo di evento per l'invio alla registrazione JFR e il modo in cui verrà visualizzato in JMC.

   Tuttavia, a volte quando si utilizza operation name è possibile ottenere un tipo di evento simile al seguente: q_AxPsCbac9Ykp0HjpU+ENCiYHKl5HzMCmR02AfGzow3A= che rappresenta una query JDBC da un client DB. In questo caso si desidera modificare il nome inviato alla registrazione JFR in qualcosa di intuitivo quindi l'esempio seguente può essere utilizzato in questi casi:

   eventTypes:
     q_AxPsCbac9Ykp0HjpU+ENCiYHKl5HzMCmR02AfGzow3A=:
       name: jdbc-select-query

4. Se è possibile specificare recordCallStack per ogni tipo di evento, perché è necessario disporre anche del livello superiore recordCallStack?

   Supportiamo due casi d'uso per la massima flessibilità nella registrazione dello stack di chiamate. La registrazione dello stack di chiamata può essere disattivata a livello globale e quindi può essere attivata in modo selettivo per tipi di evento specifici. Un'altra opzione è quella di attivarla globalmente e quindi può essere disattivata selettivamente per tipi di evento specifici. Entrambi i casi d'uso sono supportati, pertanto l'impostazione si trova sia al livello superiore che a livello di evento.

5. Sono presenti intervalli non configurati e ignorati. È comunque possibile acquisire tali eventi senza configurarli?

   Sì. Se si imposta allowUnconfiguredEvents: true nella configurazione principale di livello superiore, gli eventi verranno acquisiti. Quando ciò accade, non sappiamo quali campi raccogliere. Vengono raccolti solo i seguenti set di campi predefiniti: traceID, spanID, parentSpanID, startThread e operationName.

6. Se si utilizza com.oracle.apm.agent.jfr.category.default=ORACLE_APM_USE_SPAN_OPERATION_NAMES per utilizzare le categorie definite dal nome dell'operazione, il nome dell'operazione deve corrispondere esattamente al nome del tipo di evento nel file di configurazione? In caso affermativo e se si dispone di nomi operazione univoci, è necessario specificare un tipo di evento per ogni operazione?

   Sì, deve corrispondere al nome del tipo di evento nel file di configurazione. Anche se si dispone di molti nomi di operazione univoci, sarà necessario specificare un tipo di evento per ciascuna operazione poiché è probabile che ognuno di questi tipi di evento abbia un set di campi diverso da configurare.

7. Il nome operazione personale viene convertito in identificativo Java, pertanto non è possibile configurarne il tipo di evento. Come è possibile determinare in quale nome operazione è stato convertito?

   Tutti i caratteri non validi sono stati sostituiti con un carattere di sottolineatura. Se è necessario un codice Java di esempio per convertire le stringhe in identificativi, è possibile utilizzare il codice riportato di seguito, che è la stessa routine utilizzata da APM per convertire le stringhe.

   // Convert an arbitrary string into a valid java identifier by replacing non-identifier chars with an underscore
   public static String getJavaIdentifier(String inString)
   {
       if (inString == null || inString.length() == 0)
          return inString;
       StringBuilder stringBuilder = new StringBuilder();
       char[] allChars = inString.toCharArray();
   
       if(Character.isJavaIdentifierStart(allChars[0]))
           stringBuilder.append(allChars[0]);
       else
           stringBuilder.append("_");
   
       for (int i = 1; i < allChars.length; i++)
       {
           if (Character.isJavaIdentifierPart(allChars[i]))
               stringBuilder.append(allChars[i]);
           else
               stringBuilder.append("_");
       }
       return stringBuilder.toString();
   }

8. Il nome corrispondente può essere RegEx?

   N. RegEx non è supportato.