Java Trace SDK baseado em configuração

O SDK baseado em configuração é sensível às mudanças em seu aplicativo. Você pode renomear uma classe ou um método e, de repente, a configuração não corresponde mais e você perde seus dados de rastreio Sempre que possível, recomendamos que você utilize o SDK de rastreamento do Java, que é muito mais resistente a alterações no código e oferece mais recursos para ajudá-lo a atingir seus objetivos.

Para usar o SDK de rastreamento do ` Java ` baseado em configuração, é necessário habilitar o SDK de rastreamento do ` Java `, conforme descrito em “Habilitando o SDK de rastreamento do ` Java ` ”.

Notas:

• As alterações na configuração do SDK de rastreamento do Java baseado em configuração são detectadas automaticamente pelo agente do Instana. Os aplicativos já instrumentados precisam ser reiniciados para usar a configuração mudada.

• O SDK de rastreamento do Java, baseado em configuração, está disponível na versão 1.2.351Java do Trace Sensor ou em versões posteriores.

A listagem a seguir descreve o formato geral da configuração:

# 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']
 

Diversos destinos podem ser definidos dentro da chave targets, cada um deles especifica um período a ser criado. O objeto match de um target especifica o método ao qual aplicar a instrumentação. O objeto span especifica como construir o período, incluindo o seu nome (que é usado, por exemplo, no Unbounded Analytics para o filtro call.name ) e quais tags devem ser configuradas.

Se um valor Throwable for propagado para fora de um método instrumentado, o intervalo será automaticamente marcado como errado, e o valor de Throwable#getMessage() será definido como a mensagem de erro, que você poderá pesquisar no Unbounded Analytics por meio da call.error.message tag.

1. Verifique se a configuração foi analisada com sucesso. Nos registros do agente, procure uma mensagem semelhante a:

   Parsed configuration file /instana-agent/etc/instana/configuration.yaml 

2. Verifique se a instrumentação foi aplicada. Após a análise, o agente registrará uma mensagem indicando que realizou a instrumentação do SDK:

   ... Spent XX ms and XXX KiB of Metaspace for instrumentation [sdk] ... 

3. Ative e verifique os registros de rastreamento de intervalos do SDK. Para verificar se os spans estão realmente sendo criados, habilite o registro de rastreamento adicionando o seguinte ` YAML `:

   com.instana.plugin.javatrace: instrumentation: log: type: trace file: /tmp/trace.log 

Assim que a instrumentação estiver ativa e o código instrumentado for executado, você deverá ver os spans do SDK sendo emitidos. Exemplo de formato de log de rastreamento:

 -|EN|052d6bf37f16034c7:0:52d6bf37f16034c7|sdk:sdk.quarkus-hello|*com.instana.agent.instrumentation.sdk.SdkPlugin:start:789:SdkPlugin.java
    

O fragmento a seguir mostra uma configuração de exemplo de como as tarefas em lote de manipulação de aplicativo poderiam ser rastreadas:

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
 

Primeiramente, o método processBatch na classe com.instana.java.sdk.BatchApplication é instrumentado para criar períodos de entrada com o nome Job, a anotação endpoint com o valor constante BatchJob e a anotação batch.job com o primeiro argumento como o valor dela.

Além disso, as chamadas de saída do banco de dados durante o processamento em lote, ou seja, as chamadas de método updateDatabase na mesma classe, criarão períodos de saída com o nome DatabaseCall, a anotação db.connection_string com o valor constante jdbc:mysql://127.0.0.1:3306/jobs e a anotação db.statement com o primeiro argumento da chamada de método.

O processamento de um novo lote com processBatch iniciará um novo rastreio e as subsequentes atualizações do banco de dados com updateDatabase serão listadas como períodos filhos dentro dele. Todos os recursos da Instana, como o Unbounded Analytics, podem ser usados identicamente para rastreios criados com a Instana AutoTrace.

As restrições a seguir aplicam-se ao Java Trace SDK baseado em configuração:

• A instrumentação de construtores não é suportada.
• Não há suporte para iniciar um período em um método e fechá-lo em outro, ou seja, o SDK baseado em configuração não tem nenhum equivalente para as anotações @Span.Start e @Span.End.
• A captura de todos os argumentos ou o valor de retorno sem criar explicitamente uma tag não é suportada.
• Não é permitido especificar placeholders na lista de argumentos para argumentos não essenciais ou para todos os demais; a correspondência baseada em argumentos é executada de forma estrita.
• A especificação de padrões de nome para classes ou métodos não é suportada.
• A restauração de um contexto de rastreio não é suportada antes da criação de um período, ou seja, o SDK baseado em configuração não tem um recurso equivalente a SpanSupport.inheritNext().
• O SDK baseado em configuração não oferece suporte à instrumentação de classes do JDK.