JavaScript agente API

La tabella seguente elenca i parametri:

I tasti di monitoraggio possono essere impostati tramite il comando key . La chiave di monitoraggio è visibile quando si configurano i siti web nell'interfaccia utente di Instana.

ineum('key', trackingKey);
 

I beacon vengono trasmessi al sito URL attraverso HTTP GET e POST per fornire i dati di monitoraggio a Instana.

ineum('reportingUrl', reportingUrl);
 

In alcuni casi, potrebbe essere auspicabile che un agente JavaScript faccia rapporto a più backend. In questo caso, utilizzare il comando reportingBackends per fare in modo che l'agente JavaScript invii segnalazioni a più backend.

ineum('reportingBackends', reportingBackends);
 

Instana può segmentare le metriche del sito web per pagine logiche. Per farlo, ha bisogno di un indizio sulla pagina che l'utente sta guardando. Il nome della pagina può essere impostato tramite il comando page . Impostate il sito page il prima possibile. È possibile modificare il sito page per presentare le modifiche al documento (ad esempio, per le applicazioni a pagina singola). Ciò consente a Instana di tracciare le transizioni di pagina oltre al caricamento della pagina.

ineum('page', pageName);
 

Gli eventi di transizione della pagina vengono registrati ogni volta che il nome della pagina viene modificato tramite l'API, ad eccezione della prima invocazione dell'API durante la fase di caricamento della pagina.

Per definire le pagine, usare nomi logici come product detail page o payment selection invece di window.title o window.href. Utilizzando product detail page o payment selection si ottiene un minor numero di pagine che hanno una relazione diretta con il codice esistente. Mentre utilizzando window.title o window.href si ottengono numerose pagine tracciate che forniscono valore nella maggior parte dei casi perché window.title contiene nomi di prodotti.

Instana fornisce progetti di esempio che mostrano come raccogliere nomi di pagina significativi per vari framework e librerie. Presentare una richiesta di supporto o di pull per il framework o la libreria mancante.

Le informazioni specifiche dell'utente possono essere inviate facoltativamente con i dati trasmessi a Instana. Queste informazioni possono essere utilizzate per sbloccare ulteriori funzionalità, quali:

• Calcolare il numero di utenti interessati dagli errori
• Per filtrare i dati per utenti specifici
• Per vedere quale utente ha avviato il caricamento di una pagina o una chiamata Ajax.

Per impostazione predefinita, Instana non associa alcuna informazione identificabile dall'utente ai beacon. Quando decidete di farlo, fate attenzione alle rispettive leggi sulla protezione dei dati. In Instana, l'ID utente è un string trasparente che viene utilizzato solo per calcolare alcune metriche. Pertanto, l'identificazione degli utenti avviene tramite un ID utente. userName e userEmail possono essere utilizzati per avere accesso a più filtri e a una presentazione efficace delle informazioni dell'utente.

Richiamare questa API in modo sincrono nel processo di caricamento della pagina, ad esempio renderizzando le informazioni nel documento HTML sul lato server, aiuta a garantire che tutti i beacon contengano informazioni sull'utente, che le statistiche sugli utenti unici o interessati siano corrette e che i beacon siano filtrati e raggruppati correttamente quando vengono analizzati.

ineum('user', userId, userName, userEmail);
 

Il tracciamento delle sessioni può essere utilizzato per ottenere informazioni sull'attività degli utenti finali attraverso il caricamento delle pagine. Il monitoraggio delle sessioni consente specificamente a Instana di determinare l'impatto sull'utente finale in assenza di informazioni utente definite.

Per tracciare le sessioni, l'agente JavaScript utilizza l'API del browser dopo aver effettuato la chiamata a localStorage aPI del browser dopo aver effettuato la chiamata a trackSessions . Tecnicamente una sessione è un ID casuale che viene memorizzato insieme a due timestamp all'interno di localStorage dei browser sotto la chiave in-session.

La responsabilità del rispetto delle norme sulla privacy è del chiamante di questa API.

I metadati possono essere utilizzati per annotare il caricamento delle pagine e le chiamate Ajax. Utilizzare i metadati per tenere traccia dei valori di configurazione dell'interfaccia utente, delle impostazioni, dei flag delle funzioni o di qualsiasi altro contesto che possa essere utile per l'analisi.

ineum('meta', key, value);
 

Durante il caricamento della pagina, è possibile definire un ID di traccia backend per consentire la correlazione tra front-end e back-end. Per ulteriori informazioni, vedere Correlazione backend. La definizione dell'ID di traccia del backend è necessaria per ottenere una correlazione tra l'elaborazione del backend e del front-end dei carichi di pagina. Non è necessario per la correlazione tra le richieste di XMLHttpRequest o fetch . L'ID traccia deve essere una stringa esadecimale di 16 o 32 caratteri.

ineum('traceId', traceId);
 

È possibile definire diverse espressioni regolari utilizzando questa API. Con almeno una corrispondenza non risulta la trasmissione di dati a Instana. Le espressioni regolari vengono valutate nei seguenti scenari:

• Valutazione rispetto agli URL dei documenti (gli URL visibili nella barra degli indirizzi, cioè window.location.href). La trasmissione dei dati a Instana viene disattivata quando una delle espressioni regolari corrisponde.
• Valutazione rispetto agli URL delle risorse, ad esempio gli URL dei file JavaScript e CSS. Nessuna informazione sulle risorse che corrispondono a una delle espressioni regolari viene trasmessa a Instana.
• La valutazione rispetto agli URL di destinazione di HTTP chiama, ad esempio, attraverso XMLHttpRequest e fetch. Nessuna informazione sulle chiamate di HTTP che corrispondono a una delle espressioni regolari viene trasmessa a Instana.

ineum('ignoreUrls', ignoreUrls);
 

Instana supporta anche lo stripping dei segreti dagli URL dei documenti, cioè gli URL visibili nella barra degli indirizzi del browser (vedere l'API dei segreti ). Tuttavia, è bene tenere presente che i segreti memorizzati negli URL dei documenti sono quasi accessibili a tutti i terzi. Abbiamo un' applicazione di esempio dedicata con descrizione che mostra perché i segreti memorizzati negli URL dei documenti sono inclini a trapelare a tutti i terzi. Per maggiori dettagli, consultare l'applicazione e la descrizione di questo esempio. Tuttavia, si può scegliere di ignorare la raccolta dei dati di monitoraggio per questi URL attraverso questa API.

I parametri di query negli URL raccolti potrebbero contenere dati sensibili. Pertanto, l'agente JavaScript supporta la specificazione di modelli per le chiavi dei parametri di query i cui valori sono stati redatti. La reazione avviene all'interno dell'agente JavaScript, cioè all'interno del browser web. Pertanto, i segreti non raggiungono i server Instana per l'elaborazione e non sono disponibili per l'analisi nell'interfaccia utente o recuperati tramite API.

ineum('secrets', secrets);
 

Se un parametro di query corrisponde a una voce dell'elenco, il valore viene eliminato e non inviato al backend di Instana. Se non viene definito ineum('secrets') , Instana utilizza [/key/i, /secret/i, /password/i] come regola di corrispondenza predefinita.

Il frammento di URL raccolto potrebbe contenere informazioni sensibili. Pertanto, l'agente JavaScript supporta la specificazione di modelli per i valori dei frammenti che possono essere redatti in base al percorso URL. Questa rielaborazione avviene all'interno dell'agente JavaScript nel browser web. Di conseguenza, si impedisce che le informazioni sensibili raggiungano i server Instana per l'elaborazione. Le informazioni sensibili rimangono inaccessibili per l'analisi nell'interfaccia utente o per il recupero attraverso l'API.

ineum('fragment', fragment);
 

Se un segmento del percorso di URL corrisponde a una voce dell'elenco, il valore del frammento viene eliminato e non inviato al backend di Instana. Per impostazione predefinita, Instana non redime i frammenti di URL.

Instana raccoglie automaticamente i marcatori e le misure effettuate tramite l' API User-Timing e li trasforma in eventi personalizzati. Ciò significa che l'API User-Timing può essere utilizzata come metodo neutro per segnalare a Instana dati di temporizzazione puri.

Utilizzando l'API User-Timing, è possibile definire diverse espressioni regolari che, quando almeno una di esse corrisponde, non risultano in una raccolta di tempi specifici per l'utente. Per impostazione predefinita, le seguenti condizioni vengono ignorate:

• I tempi utente di React: i segni e le misure che iniziano con l'emoji ⚛️ o ⛔
• I tempi utente di Angular: i segni e le misure che iniziano per Zone
• I marchi e le misure i cui nomi iniziano con start o con end

ineum('ignoreUserTimings', ignoreUserTimings);
 

Per impostazione predefinita, l'agente JavaScript raccoglie l'intero URL, che include tutti i suoi parametri. È possibile configurare l'agente solo per raccogliere i parametri degli URL che corrispondono a un elenco specificato di espressioni regolari. I parametri degli URL esclusi non vengono tracciati.

In base all'elenco di espressioni regolari fornito, l'agente JavaScript traccia gli URL come segue:

• Se URL corrisponde a una voce dell'elenco, viene raccolto l'intero URL che include tutti i parametri.
• Se URL non corrisponde a una voce dell'elenco, i parametri della query e i frammenti di URL non vengono inviati al backend di Instana.
• Se l'elenco fornito è vuoto, viene applicato il comportamento predefinito e viene tracciato l'intero URL con i suoi parametri.

ineum('queryTrackedDomainList',queryTrackedDomainList);
 

I seguenti scenari spiegano la condizione se il sito URL contiene un segreto o un frammento redatto utilizzando ineum('secrets', secrets) o ineum('fragment', fragment):

• Se URL corrisponde a una voce di queryTrackedDomainList, l'intero URL con il segreto o il frammento redatto viene inviato al backend Instana.
• Se URL non corrisponde a una voce di queryTrackedDomainList, tutti i parametri vengono esclusi prima di inviare URL al backend di Instana.

Quando un browser invia una richiesta a un server remoto e l'agente Instana monitora il server remoto, la risposta del server potrebbe contenere l'intestazione HTTP Server-Timing per fornire l'indirizzo backendTraceId all'agente Instana che gira nel browser. Se OpenTelemetry è abilitato nel server remoto, l'intestazione tracestate HTTP può contenere l'elemento backendTraceId.

tracestate e traceparent sono intestazioni di W3C-defined utilizzate per correlare gli ID delle tracce distribuite. Per ulteriori informazioni sulle intestazioni di traccia di W3C, vedere Livello di contesto della traccia.

Se si prevede che il server remoto possa usare OpenTelemetry e fornire il valore backendTraceId nell'intestazione tracestate , l'agente Instana nel browser deve impostare l'API enableW3CHeaders su true per utilizzare il valore backendTraceId nelle intestazioni W3C.

È possibile impostare backendTraceId in tre punti diversi: attraverso l'intestazione Server-Timing , l'intestazione tracestate e manualmente utilizzando l'API traceId nel browser. La sequenza di questi approcci è la seguente:

• Se enableW3CHeaders è abilitato, si hanno due possibilità. Innanzitutto, si estrae il valore tracestate dai metadati della pagina corrente traceparent e lo si utilizza. Se non è possibile recuperare tracestate, viene generata e utilizzata una stringa lunga 16 caratteri compatibile con il contesto di traccia W3C.
• Se enableW3CHeaders è disabilitato, verificare innanzitutto se l'API traceId viene chiamata. Se viene richiamata l'API traceId , utilizzare l'ID come backendTraceId. Se l'API traceId non viene chiamata, analizzare l'intestazione HTTP Server-Timing per ottenere l'API backendTraceId.
• Se nessuno dei valori precedenti è disponibile, non è possibile collegare i beacon alle tracce del backend.

ineum('enableW3CHeaders',true);
 

Per raccogliere metriche aggiuntive, l'agente JavaScript attende che si verifichino le seguenti condizioni. Ad esempio, il ritardo del primo ingresso e lo spostamento cumulativo del layout.

• Tutte le metriche sono disponibili
• La pagina viene scaricata (ad esempio la scheda viene chiusa)
• Fino allo scadere di un tempo di attesa massimo

È possibile utilizzare questa API per riconfigurare il tempo massimo di attesa. Per impostazione predefinita, Instana attende fino a un secondo dopo che il caricamento della pagina è terminato, cioè l'evento onLoad finisce.

ineum('maxMaitForPageLoadMetricsMillis', durationMillis);
 

A volte può essere utile ricevere manualmente l'ID del caricamento della pagina, ad esempio quando si vuole effettuare una correlazione personalizzata. Questa funzione restituisce undefined finché l'agente JavaScript non viene caricato. Dopo che l'agente JavaScript è stato caricato, restituisce sempre lo stesso string.

ineum('getPageLoadId');
 

Per ulteriori informazioni sugli Eventi globali personalizzati, consultare la pagina Eventi.

Gli eventi personalizzati consentono di segnalare a Instana attività non standard, interazioni importanti e tempistiche personalizzate. Questo può essere particolarmente utile per analizzare gli errori non catturati (briciole di pane) e per tracciare altre metriche di prestazione.

ineum('reportEvent', eventName, {
  duration: duration,
  timestamp: timestamp,
  backendTraceId: backendTraceId,
  error: error,
  componentStack: componentStack,
  meta: meta,
  customMetric: customMetric
});
 

La correlazione di backend di Instana funziona impostando intestazioni personalizzate sulle richieste XMLHttpRequest / fetch . L'agente JavaScript imposta queste intestazioni che vengono poi lette dal server. All'interno del browser, il criterio same-origin limita la trasmissione di intestazioni personalizzate. In particolare, le intestazioni personalizzate possono essere impostate solo per le richieste della stessa origine o per le richieste ad altre origini che consentono la trasmissione di intestazioni personalizzate. Ad esempio, per impostazione predefinita, un sito web servito da https://example.com:443 non può fare XMLHttpRequests a https://shop.example.com:443 poiché si tratta di due origini diverse.

Per aggirare questa restrizione di sicurezza, è disponibile la condivisione delle risorse in base all'origine ( CORS). Con CORS, è possibile consentire l'accesso alle risorse da parte delle origini. Se si dispone già di un accesso incrociato alle risorse all'interno della propria applicazione, è molto probabile che si stiano già utilizzando alcune intestazioni CORS.

Per abilitare la correlazione del backend di Instana, completare i passaggi seguenti:

1. Consentire le intestazioni di correlazione di Instana per le richieste di origine incrociata rispondendo sul lato server con le seguenti intestazioni.

   Nota: il server deve rispondere con queste intestazioni sia per le richieste di preflight che per quelle normali. Le richieste di preflight (identificabili attraverso il metodo OPTIONS HTTP ) vengono eseguite dal browser per verificare che le richieste possano essere inviate al server.

   Access-Control-Allow-Origin: https://your-origin.example.com
   Access-Control-Allow-Headers: X-INSTANA-T, X-INSTANA-S, X-INSTANA-L
   
    

2. Informare l'agente JavaScript che CORS è configurato correttamente e che deve impostare queste intestazioni di correlazione:

   ineum('allowedOrigins', urls);
    

Le intestazioni delle richieste HTTP o delle risposte delle richieste XMLHttpRequest o fetch possono essere catturate dall'agente JavaScript. È possibile definire le intestazioni di HTTP che si desidera che l'agente JavaScript catturi con il comando captureHeaders .

All'interno del browser, il criterio same-origin limita l'accesso alle intestazioni personalizzate. Senza la configurazione di CORS (Cross-Origin Resource Sharing ), l'agente JavaScript potrebbe non essere in grado di catturare tutte le intestazioni HTTP. Per abilitare CORS, vedere Correlazione tra richieste di origine incrociata e backend. Con CORS, solo le intestazioni di richiesta o risposta soddisfatte da CORS e quelle definite in Access-Control-Expose-Headers possono essere raccolte dall'agente JavaScript.