Configurazione della traccia OpenTelemetry per un server di integrazione

È possibile configurare OpenTelemetry trace per tutti i flussi di messaggi in un server di integrazione ed esportare i dati span in un raccoglitore OpenTelemetry.

Informazioni su questa attività

OpenTelemetry è un progetto di incubazione del CNCF. È un framework e un toolkit di Observability progettato per creare e gestire dati di telemetria come tracce, metriche e log. App Connect Enterprise supporta l'invio di informazioni di tracciamento a un endpoint OpenTelemetry, come ad esempio IBM o Instana. Al momento sono supportate solo le tracce, sotto forma di invio di dati "span" a un collettore"

OpenTelemetry Il tracciamento è supportato per i server di integrazione IBM® App Connect Enterprise su Linux® x86-64, Linux zSeries, Linux su sistemi POWER® - Little Endian, AIX® e piattaforme Windows.

Quando OpenTelemetry è abilitato per un server di integrazione, gli intervalli vengono creati per tutti i nodi di flusso dei messaggi che supportano OpenTelemetry,, compresi i nodi di flusso richiamabili. Per i nodi di input di trasporto supportati, gli spans vengono creati e quindi eseguiti fino a quando la transazione del flusso di messaggi per il flusso non viene completata o sottoposta a rollback. Per i nodi di richiesta di trasporto supportati, gli intervalli vengono creati e poi eseguiti per la durata dell'interazione del nodo con il trasporto (ad esempio, l'invio e la ricezione di un messaggio HTTP ). Per una spiegazione più dettagliata delle funzioni e del funzionamento delle campate, consultare il seguente link: https://opentelemetry.io/docs/concepts/observability-primer/

I seguenti nodi del flusso di messaggi di trasporto supportano la traccia OpenTelemetry :
  • MQ:
    • nodo MQGet
    • nodo MQInput
    • nodo MQOutput
    • nodo MQPublication
    • nodo MQReply
  • HTTP:
    • nodo HTTPAsyncRequest
    • nodo HTTPAsyncResponse
    • nodo HTTPInput
    • nodo HTTPReply
    • nodo HTTPRequest
  • Kafka:
    • KafkaConsumer nodo
    • KafkaProducer nodo
    • KafkaRead nodo
  • RIPOSO:
    • Nodo RESTAsyncRequest
    • nodo RESTAsyncResponse
    • nodo RESTRequest
  • SAPONE:
    • nodo SOAPAsyncRequest
    • Nodo SOAPAsyncResponse
    • nodo SOAPInput
    • nodo SOAPReply
    • nodo SOAPRequest

Quando la traccia di OpenTelemetry è abilitata, viene creato un intervallo di flusso di messaggi per i flussi richiamabili che iniziano con un nodo CallableInput e viene creato un intervallo intorno al nodo CallableFlowInvoke nodo. Per i nodi di flusso richiamabili asincroni, viene creato un intervallo di flusso di messaggi per i flussi che iniziano con a CallableFlowAsyncResponse nodo e viene creata una campata attorno al CallableFlowAsyncInvoke nodo.

I seguenti nodi Flusso richiamabile supportano la traccia OpenTelemetry :
  • CallableInput
  • CallableReply
  • CallableFlowInvoke
  • CallableFlowAsyncInvoke
  • CallableFlowAsyncResponse

È possibile abilitare e configurare la traccia di OpenTelemetry impostando le proprietà nella sezione OpenTelemetry del file server.conf.yaml. Per impostazione predefinita, OpenTelemetry trace non è abilitato.

Se si vuole inviare la traccia OpenTelemetry a un backend di osservabilità protetto, si può configurare il server di integrazione in modo che specifichi una credenziale opentelemetry, impostando le proprietà nella sezione OpenTelemetry del file server.conf.yaml :

#openTelemetryHttpSecurityId: '' # Specify an opentelemetry credential used in the HTTP exporter.
#openTelemetryGrpcSecurityId: '' # Specify an opentelemetry credential used in the GRPC exporter.

Si impostano le proprietà openTelemetryHttpSecurityId e openTelemetryGrpcSecurityId sul nome di una credenziale nel vault, con un tipo di credenziale opentelemetry. I dettagli recuperati dalla credenziale di riferimento vengono quindi inseriti nell'intestazione HTTP Authorization. Il valore della proprietà openTelemetryGrpcSecurityId determina la credenziale utilizzata per configurare l'esportatore GRPC, mentre il valore della proprietà openTelemetryHttpSecurityId determina la credenziale utilizzata per configurare l'esportatore HTTP.

La credenziale opentelemetry può avere uno dei seguenti tipi di autenticazione: basic, accessToken, o apiKey. Il tipo di autenticazione imposta lo schema nell'intestazione HTTP Authorization nelle richieste inviate al backend OpenTelemetry, nella forma Authorization: <schema> credentials. I tipi di autenticazione impostano lo schema su Basic, Bearer, o ApiKey, come mostrato nella tabella seguente:
Tabella 1. Tipi di autenticazione delle credenziali e intestazioni HTTP
Credenziale auth-type intestazione HTTP
base Authorization: Basic <username>:<password>
accessToken Authorization: Bearer <access-token>
apiKey Authorization: ApiKey <api-key>

Per gli schemi Basic e ApiKey, le credenziali sono codificate in Base64.

Per ulteriori informazioni sull'uso di OpenTelemetry,, vedere Considerazioni e limitazioni su OpenTelemetry e Disattivazione di OpenTelemetry per un flusso di messaggi.

Per una dimostrazione di come inviare i dati di Open Telemetry, guardate questo video: Invio di dati OpenTelemetry quando si usa il trasporto Kafka.

Procedura

Configura la traccia OpenTelemetry per tutti i flussi su un server di integrazione completando la seguente procedura:

  1. Apri il server.conf.yaml file di configurazione per il server di integrazione.

    È possibile modificare il file utilizzando l'editor YAML integrato fornito nel Toolkit " IBM App Connect Enterprise ", sia facendo doppio clic sul file nella vista "Sviluppo applicazioni", sia facendo clic con il pulsante destro del mouse sul file e selezionando "Apri con " > "Editor YAML ". Se si sceglie di modificare il file utilizzando un editor di testo semplice, assicurarsi di non includere alcun carattere di tabulazione (che non è valido in YAML) e utilizzare uno strumento di convalida YAML per convalidare il contenuto del file.

  2. Nel ResourceManagers sezione delserver.conf.yaml file , imposta le proprietà richieste nel file OpenTelemetryManager sottosezione:
    • Impostare la proprietà openTelemetryEnabled su true per abilitare OpenTelemetry per tutti i flussi di messaggi sul server di integrazione. Per impostazione predefinita, questa proprietà è impostata su false. Per informazioni sulla disabilitazione di OpenTelemetry per un singolo flusso di messaggi dopo che è stato abilitato sul server di integrazione, vedere Disattivazione di OpenTelemetry per un flusso di messaggi.
    • Utilizzare la proprietà openTelemetryServiceName per sovrascrivere l'attributo Nome servizio per le applicazioni di telemetria. Per impostazione predefinita, questa proprietà è impostata su App Connect Enterprise-<integration server name>.
    • Utilizzare la proprietà openTelemetryHostName per sovrascrivere l'attributo Nome host per gli spans di telemetria.
    • Utilizzare la proprietà exporterOtlpGrpcEndpoint per specificare l'endpoint GRPC in cui esportare i dati di estensione OpenTelemetry . Ad esempio: 'telemetryagent.host.com:4317'.
    • Utilizzare la proprietà exporterOtlpHttpUrl per specificare il file HTTP /JSON URL in cui esportare i dati dell'intervallo OpenTelemetry. Ad esempio, 'http://<hostname>:<port>/v1/traces'.
    • Utilizzare la proprietà openTelemetryHttpSecurityId per specificare la credenziale utilizzata per configurare l'esportatore HTTP.
    • Utilizzare la proprietà openTelemetryGrpcSecurityId per specificare la credenziale utilizzata per configurare l'esportatore GRPC.
    • Utilizzare la proprietà openTelemetryTruststoreType per specificare il tipo di truststore OpenTelemetry . I valori validi sono PKCS12, PEMe JKS. Questa proprietà viene utilizzata solo per il programma di esportazione GRPC.
    • Utilizzare la proprietà openTelemetryTruststoreFile per specificare l'ubicazione del truststore OpenTelemetry . Questa proprietà viene utilizzata solo per il programma di esportazione GRPC.
    • Utilizzare la proprietà openTelemetryTruststorePass per specificare la credenziale o l'alias della risorsa contenente la password del truststore. Questa proprietà viene utilizzata solo per il programma di esportazione GRPC.
    • Utilizzare la proprietà openTelemetryTrustAlias per specificare l'alias del certificato sicuro nel truststore PKCS12 o JKS.
    • Utilizzare la proprietà openTelemetrySpanProcessor per specificare il tipo di processore span OpenTelemetry da utilizzare. È possibile specificare batch o simple. Per impostazione predefinita, questa proprietà è impostata su batch.
    • Utilizzare la proprietà openTelemetryBatchSpanOptions per specificare le opzioni del processore di estensione batch OpenTelemetry che si desidera utilizzare. È possibile specificare più opzioni, separate da due punti (:). Ad esempio: 'max_queue_size=4096:schedule_delay_millis=5000:max_export_batch_size=4096' .

      Per ulteriori informazioni sulle opzioni del processore batch span OpenTelemetry, consultare la documentazione OpenTelemetry.

    Ad esempio:
    
ResourceManagers:
    OpenTelemetryManager:
       openTelemetryEnabled: true                           # Enable or disable OpenTelemetry tracing. Available on Linux/x86-64. 
       openTelemetryServiceName:                            # Override the Service Name attribute for telemetry spans. 
                                                            # Defaults to integration server name.
       openTelemetryHostName:                               # Override the value of the Hostname attribute for telemetry spans.
       exporterOtlpGrpcEndpoint: 'localhost:4317'           # The GRPC endpoint to which the OpenTelemetry span data is sent. 
                                                            # For example, 'telemetryagent.host.com:4317'.
       exporterOtlpHttpUrl: ''                              # The HTTP/JSON URL to which the OpenTelemetry span data is sent. 
                                                            # For example, 'http://<hostname>:<port>/v1/traces'.
       #openTelemetryHttpSecurityId: ''                     # Specify an opentelemetry credential used in the HTTP exporter.
       #openTelemetryGrpcSecurityId: ''                     # Specify an opentelemetry credential used in the GRPC exporter.
       openTelemetryTruststoreType: ''                      # Type of OpenTelemetry truststore. Valid values are PKCS12, PEM, or JKS.
                                                            # Used only for the GRPC exporter. 
       openTelemetryTruststoreFile: ''                      # Location of the OpenTelemetry truststore. Used only for GRPC exporter.
       openTelemetryTruststorePass: 'truststore::password'  # Credential or resource alias containing the truststore password.
       openTelemetryTrustAlias: ''                          # Alias of the trust certificate in the PKCS12 or JKS truststore.
       openTelemetrySpanProcessor: 'batch'                  # OpenTelemetry span processor. Set to either 'batch' or 'simple'. 
                                                            # Default is 'batch'.
       openTelemetryBatchSpanOptions: 'max_queue_size=4096' # OpenTelemetry batch span processor options, separated by colons (:). 
                                                            # For example, 'max_queue_size=4096:max_export_batch_size=4096'
  3. Salvare le modifiche e riavviare il server di integrazione per rendere effettive le modifiche.
  4. È possibile controllare le impostazioni OpenTelemetry attive per il server di integrazione utilizzando uno dei seguenti metodi:
    • Utilizzare l'API REST di amministrazione per immettere un GET su /apiv2/resource-managers/opentelemetry-manager per i server di integrazione indipendenti
    • Eseguire il comando mqsireportproperties utilizzando il nome oggetto opentelemetry-manager su un server di integrazione gestito.