JavaScript aracı API 'si

Parametreler

ineum işlevinin hiçbir zaman bir şey döndürmediğini unutmayın ( getPageLoadIdkomutu dışında, aşağıdaki gibi).

İzleme Anahtarı

İzleme tuşları key komutuyla ayarlanabilir. Instana kullanıcı arabirimi içinde web siteleri yapılandırılırken izleme anahtarı görülebilir.

ineum('key', trackingKey);

if (window.location.hostname === 'example.com') {
  ineum('key', 'production monitoring key');
} else if (window.location.hostname === 'qa.example.com') {
  ineum('key', 'QA monitoring key');
} else {
  ineum('key', 'test monitoring key');
}

Raporlama URL 'si

Bu işaretler, izleme verilerini YönOrtamıana 'ya teslim etmek için HTTP GET ve POST aracılığıyla bu URL ' ye iletilir.

ineum('reportingUrl', reportingUrl);

Birden çok arka uç

Bazı durumlarda, birden çok arka uca bir JavaScript aracısı raporu yapmak istenebilir. Bu durumda, JavaScript aracısını birden çok arka uca raporlamak için reportingBackends komutunu kullanın.

ineum('reportingBackends', reportingBackends);

{
  reportingUrl: 'http://example.com',  // The URL to which to send website monitoring data to.
  key: 'monitoring key'                // The monitoring key for the website configuration in Instana.
}

ineum('reportingBackends', [
      { reportingUrl: 'http://backend1.example.com', key: 'monitoring key 1' },
      { reportingUrl: 'http://backend2.example.com', key: 'moniroting key 2' }
    ]);

Sayfa

Instana, web sitesi metriklerini mantıksal sayfalara göre bölebilir. Bunu yapmak için kullanıcının şu anda hangi sayfaya baktığını göstermesi gerekir. Bu sayfa adı page komutuyla ayarlanabilir. page ' yi mümkün olan en erken şekilde ayarlamanızı öneririz. Ayrıca, page ' in bir noktada belge değişikliklerini sunmak (örneğin, tek sayfalık uygulamalar) için değiştirilmesi de son derece iyidir. Bu, Instana 'nın sayfa yüklemelerine ek olarak sayfa geçişlerini de izlemesinisağlar.

ineum('page', pageName);

Sayfa adı, sayfa yükleme aşamasındabu API ' nin ilk kez çağrılması dışında, API aracılığıyla her eşzamanlandığında sayfa geçişi olayları kaydedilir.

Genel olarak, sayfaları tanımlamak için window.title ya da window.href kullanmamanızı öneririz. Bu, vakaların çoğunda değer sağlamayacak çok sayıda izlenen sayfayla sonuçlanır; örneğin, window.title ürün adlarını içerdiğinden. Bunun yerine, sayfalar için mantıksal adlar kullanılmasını öneririz. Örneğin, product detail page ya da payment selection. Bu, gerçekte var olan kodla doğrudan ilişkisi olacak daha az sayfa ile sonuçlanır.

Çeşitli çerçeveler ve kitaplıklar için anlamlı sayfa adlarının nasıl toplanacağını gösteren örnek projeler sağlıyoruz. Çerçeveniz/kitaplığınız eksikse, bir çekme ya da destek isteği gönderebilirsiniz.

ineum('page', 'shopping-cart');

// Do you want to change meta data and the page name at the same time?
// Make sure to change the page name last as this immediately
// triggers a page transition beacon.
ineum('meta', 'product', 'skateboard');
ineum('page', 'article-details');

Kullanıcıları Tanımlama

Kullanıcıya özgü bilgiler, isteğe bağlı olarak, YönOrtama aktarılan verilerle birlikte gönderilebilir. Bu bilgiler daha sonra aşağıdakiler gibi ek yeteneklerin kilidini açmak için kullanılabilir:

• hatalardan etkilenen kullanıcı sayısını hesaplayın,
• belirli kullanıcılar için verileri süzgeçten geçirmek için ve
• Hangi kullanıcının sayfa yükleme/AJAX çağrısı başlattığını görmek için.

Varsayılan olarak, YönOrtamıana kullanıcı tarafından tanımlanabilir bilgileri işaretlerle ilişkilendirmez. Lütfen bunu seçerken ilgili veri koruma yasalarını dikkate alın. Genellikle bir kullanıcı kimliği aracılığıyla kullanıcıların kimliğini belirlemenizi öneririz. Instana için bu, yalnızca belirli metrikleri hesaplamak için kullanılan tamamen saydam bir string ' dir. userName ve userEmail , daha fazla süzgeç ve kullanıcı bilgilerinin daha hoş bir sunumuna erişmek için de kullanılabilir.

Instana 'nın sunucusuna iletilen verilerin geriye dönük olarak güncellenemeyeceğini göz önünde bulundurmak önemlidir. Bu nedenle, sayfa yükleme işleminde bu API ' yi mümkün olan en kısa sürede çağırmak önemlidir. Bu API ' yi sayfa yükleme işleminde zamanuyumlu olarak (örneğin, bilgileri sunucu tarafındaki HTML belgesine görüntüleyerek) çağırmanızı öneririz. Bu, tüm işaretlerin kullanıcı bilgilerini taşımasını, benzersiz/etkilenen kullanıcı istatistiklerinin doğru olmasını ve işaretlerin analiz sırasında doğru şekilde süzülmesini ve gruplanmasını sağlar.

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

// Report everything to Instana
ineum('user', 'hjmna897k1', 'Tom Mason', 'tom@example.com');

// or only some data points
ineum('user', 'hjmna897k1');
ineum('user', null, null, 'tom@example.com');

Oturum İzleme

Sayfa yüklerinde son kullanıcıların etkinliğine ilişkin öngörüler elde etmek için oturum izleme kullanılabilir. Oturum izleme özelliği, instana 'nın tanımlı kullanıcı bilgileriolmadığında son kullanıcı etkisini belirlemesini sağlar.

Oturumları izlemek için JavaScript aracısı, trackSessions çağrısı yaptıktan sonra localStorage tarayıcı API 'sini kullanır. Teknik olarak bir oturum, tarayıcıların localStorage anahtar altında in-sessioniki zaman damgası ile birlikte saklanan rasgele bir tanıtıcıdır.

Gizlilik düzenlemelerine uyulmasına ilişkin sorumluluk, bu API ' yi çağıran kişi tarafından üstlenilmektedir.

ineum('trackSessions', sessionInactivityTimeout, sessionTerminationTimeout);

// Starts tracking sessions with the default timeouts
ineum('trackSessions');

// or specify custom timeouts
ineum('trackSessions', 900000 /* 15min */, 3600000 /* 1h */);

ineum('terminateSession');

// Starts tracking sessions with the default timeouts
ineum('trackSessions');

// after some time…
ineum('terminateSession');

Meta Veri

Meta veriler, sayfa yüklerine ve AJAX çağrılarına ek açıklama eklemek için kullanılabilir. UI yapılandırma değerlerini, ayarlarını, özellik işaretlerini ... analiz için yararlı olabilecek herhangi bir ek bağlamı izlemek için bunu kullanmayı düşünün.

ineum('meta', key, value);

ineum('meta', 'version', '1.42.3');
ineum('meta', 'role', 'admin');

Sayfa Yükleme Arka Uç İzleme Tanıtıcısı

Sayfa yükünün bir parçası olarak, ön uç/arka uç ilintilendirmesine izin vermek için bir arka uç izleme tanıtıcısı tanımlanabilir. Daha fazla ayrıntı için arka uç ilintilendirmebölümünde özel olarak ayrılmış bölüme bakın. Bu yalnızca sayfa yüklerinin arka ucu ve ön uç işlemleri arasında ilişki elde etmek için gereklidir. XMLHttpRequest ya da fetch istekleri arasındaki ilinti için gerekli değildir . İzleme tanıtıcısı 16 ya da 32 karakterli bir onaltılı dizgi olmalıdır.

ineum('traceId', traceId);

ineum('traceId', '89jkbds891jkn321');

İzlemedeki URL ' leri Dışlama

Bu API, en az bir eşleşme olduğunda YönOrtamıana 'ya veri iletimine neden olmayacak birkaç düzenli ifade tanımlamanıza olanak sağlar. Düzenli ifadeler aşağıdaki senaryolarda değerlendirilir.

• Belgelerin URL 'lerine (adres çubuğunda görünen URL' ler, örneğin window.location.href) ilişkin değerlendirme. Düzenli ifadelerden biri eşleştiğinde, YönOrtama yapılan tüm veri iletimi geçersiz kılınır.
• Kaynakların URL 'lerine (örneğin, JavaScript ve CSS dosyalarının URL' lerine) ilişkin değerlendirme. Düzenli ifadelerden biriyle eşleşen kaynaklarla ilgili hiçbir bilgi YönOrtama 'ya iletilmez.
• HTTP çağrılarının hedef URL ' lerine ilişkin değerlendirme; örneğin, XMLHttpRequest ve fetcharacılığıyla. Düzenli ifadelerden biriyle eşleşen HTTP çağrılarıyla ilgili hiçbir bilgi YönOrtama iletilecek.

ineum('ignoreUrls', ignoreUrls);

Ayrıca, belge URL ' lerinden güvenlik dizgileri çıkarılmasını destekliyoruz; örneğin, tarayıcı adres çubuğunda görünen URL ( güvenlik dizgileri API 'sine bakın). Ancak, belge URL ' lerinde saklanan sırların neredeyse tüm üçüncü kişilere sızdırıldığına dikkat edin. Belge URL ' lerinde saklanan sırların neden tüm üçüncü kişilere sızmaya eğilimli olduğunu gösteren açıklamalı özel olarak ayrılmış bir örnek uygulamamız var. Daha fazla ayrıntı için lütfen bu örnek uygulamaya ve açıklamaya bakın. Ancak, bu API aracılığıyla bu URL ' ler için tüm izleme verileri toplamasını yoksaymayı seçebilirsiniz.

ineum('ignoreUrls', [
  /\/comet.+/i,
  /\/ws.+/i,
  /.*(&|\?)secret=.*/i
]);

URL ' lerden güvenlik sırlarını düzeltme

Toplanan URL ' lerdeki sorgu parametreleri hassas veriler içerebilir. Bu nedenle, JavaScript aracısı, değerleri düzeltilecek sorgu değiştirgesi anahtarlarına ilişkin örüntü belirtimini destekler. Düzelti, JavaScript aracısı içinde, yani web tarayıcısı içinde gerçekleşir. Sonuç olarak, sırlar işlenmek üzere YönOrtamıana sunucularına ulaşmaz ve kullanıcı arabiriminde analiz veya API aracılığıyla alma için kullanılamaz.

ineum('secrets', secrets);

Bir sorgu parametresi listedeki bir girişle eşleşirse, değer düzeltiilir ve YönOrtamıana arka ucuna gönderilmez. ineum('secrets') tanımlanmazsa, YönOrtamı'nıda varsayılan olarak eşleşen kural olarak [/key/i, /secret/i, /password/i] kullanılır.

ineum('secrets', [/account/i, /user/i]);

İzlemedeki Kullanıcı Zamanlamalarını Dışlama

User-Timing API (Kullanıcı Zamanlama API 'si) aracılığıyla yapılan işaretçileri ve ölçümleri otomatik olarak toplar ve bunları özel olaylaradönüştürürz. Bu, Kullanıcı-Zamanlama API 'sinin, YönOrtamıana 'ya saf zamanlama verilerini raporlamak için satıcı tarafından tarafsız bir yöntem olarak kullanılabileceği anlamına gelir.

Bu API, en az bir eşleşme olduğunda belirli kullanıcı zamanlamasının toplanmasıyla sonuçlanmayacak birkaç düzenli ifade tanımlamanıza olanak sağlar. Varsayılan olarak yoksayıyoruz ...

• ⚛️ ya da ⛔ ifadesiyle başlayan işaretler ve ölçüler,
• Angular 'ın kullanıcı zamanlamaları-örneğin, Zone ile başlayan işaretler ve ölçüler ve
• Adları start ya da end ile başlayan işaretleri ve ölçümleri gösterir.

ineum('ignoreUserTimings', ignoreUserTimings);

ineum('ignoreUserTimings', [
  /^\u269B/,
  /^\u26D4/,
  /^Zone(:|$)/,
  /mySecretTiming/i
]);

Sayfa Yükünden Sonra Bekleme Üst Sınırını Yapılandırma

Ek metrikleri (örneğin, ilk giriş gecikmesi ve birikmeli yerleşim düzeni vardiyasını) toplamak için, JavaScript aracısı şu zamana kadar bekler ...

• tüm metrikler kullanılabilir
• sayfa boşaltıldı (örneğin, sekme kapatıldı) ya da
• bekleme süresi üst sınırı geçinceye kadar.

Bekleme süresi üst sınırını yeniden yapılandırmak için bu API ' yi kullanabilirsiniz. Varsayılan olarak, sayfa yüklemesi bittikten sonra en fazla bir saniye bekleriz; örneğin, onLoad olayı sona ermiştir.

ineum('maxMaitForPageLoadMetricsMillis', durationMillis);

ineum('maxMaitForPageLoadMetricsMillis', 500);

Sayfa Yükleme Tanıtıcısının Alınması

Bazen, örneğin özel ilinti yapmak istediğinde, sayfa yükünün tanıtıcısını el ile almak yararlı olabilir. Bu işlev, JavaScript aracısı henüz yüklenmediği sürece undefined döndürür. Yüklendikten sonra, her zaman aynı stringdöndürülür.

ineum('getPageLoadId');

var pageLoadId = ineum('getPageLoadId');
console.log(pageLoadId);

Hata İzleme

ineum('reportError', error, opts);

{
  componentStack: '...' // an optional string

  meta: {               // An optional JavaScript object with `string` values which can be used
    widgetType: 'chart' // to send metadata to Instana just for this singular event. In contrast to
  }                     // the usage of the metadata API, this metadata is not included in subsequent
                        // beacons.
}

ineum('reportError', new Error('Something failed'), {
  componentStack: '…',
  meta: {
    widgetType: 'chart'
  }
});

componentDidCatch(error, info) {
  ineum('reportError', error, {
    componentStack: info.componentStack
  });

  // your regular error boundary code
}

import { ErrorHandler, NgModule } from '@angular/core';

class CustomErrorHandler implements ErrorHandler {
  handleError(error) {
    ineum('reportError', error);

    // Continue to log caught errors to the console
    console.error(error);
  }
}

@NgModule({
  providers: [{ provide: ErrorHandler, useClass: CustomErrorHandler }],
})
class MyModule {
  // the rest of your application code…
}

app.config.errorHandler = (err, instance, info) => {
  ineum('reportError', err);
  // your regular error handling code
}

ineum('ignoreErrorMessages', ignoreErrorMessages);

ineum('ignoreErrorMessages', [/^script error/i]);

ineum('wrapEventHandlers', enabled);

ineum('wrapEventHandlers', true);

ineum('wrapTimers', enabled);

ineum('wrapTimers', true);

ineum('ignoreErrorMessages', [/^script error/i]);

Özel Olayları Raporlama

Belirsizliği giderme: Bunun yerine Genel Özel Olayları mı arıyorsunuz? Etkinlikler sayfasınagidin.

Özel olaylar, standart olmayan etkinlikler, önemli etkileşimler ve özel zamanlamaların YönOrtama raporlanmasını sağlar. Bu, özellikle yakalanmayan hataları (işlem izlerini) analiz ederken ve ek performans ölçümlerini izlerken yararlı olabilir.

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

ineum('reportEvent', 'login');

ineum('reportEvent', 'full example', {
  timestamp: Date.now(),
  duration: 42,
  backendTraceId: '31ab91fc109223fe',
  error: new Error('whooops – sorry!'),
  componentStack: 'a component stack',
  meta: {
    state: 'running'
  }
});

Kökler Arası İstek Arka Uç İlintisi

Instana 'nın arka uç ilintisi, XMLHttpRequest / fetch isteklerinde özel üstbilgiler ayarlanarak çalışır. JavaScript aracısı, sunucu tarafından okunan bu üstbilgileri ayarlar. Tarayıcı içinde, aynı kaynak ilkesi özel üstbilgilerin iletimini sınırlar. Daha spesifik olarak, özel üstbilgiler yalnızca aynı köken istekleri ya da özel üstbilgilerin iletilmesine izin veren diğer kökenlere yönelik istekler için ayarlanabilir. Örneğin, varsayılan olarak https://example.com:443 tarafından sunulan bir web sitesi, iki farklı kökenden oluşması nedeniyle https://shop.example.com:443 ' e XMLHttpRequestyapamaz.

Bu güvenlik kısıtlaması üzerinde çalışmak için kaynaklar arası kaynak paylaşımı (CORS) kullanılabilir. CORS ile kökenlere, köken arası kaynak erişimi için izin verilebilir. Uygulamanızda köken arası kaynak erişiminiz varsa, büyük olasılıkla bazı CORS üstbilgilerini zaten kullanıyorsunuz.

Instana arka uç ilintisini etkinleştirmek için aşağıdaki yapılması gerekir:

1. Sunucu tarafında aşağıdaki üstbilgilerle yanıt vererek YönOrtamıana 'nın başlangıç noktaları arası isteklere ilişkin ilinti üstbilgilerine izin verin.

   Sunucunuzun hem uçuş öncesi istekler hem de düzenli istekler için bu üstbilgilerle yanıt vermesi gerektiğini lütfen unutmayın. Uçuş öncesi istekler ( OPTIONS HTTP yöntemiyle tanımlanabilir), isteklerin sunucuya yayınlanabileceğini doğrulamak için tarayıcı tarafından yürütülür.

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

2. JavaScript aracısını CORS ' un doğru yapılandırıldığını ve bu ilinti üstbilgilerini ayarlaması gerektiğini bildirin:

   ineum('allowedOrigins', urls);
   

ineum('allowedOrigins', [/.*api\.example\.com.*/]);

HTTP istek/yanıt üstbilgilerini yakala

XMLHttpRequest / fetch isteklerinde HTTP istek/yanıt üstbilgileri JavaScript aracısı tarafından yakalanabilir. JavaScript aracısının captureHeaders komutuyla yakalamasını istediğiniz HTTP üstbilgilerini tanımlayabilirsiniz.

Tarayıcı içinde, aynı kaynak ilkesi özel üstbilgilere erişimi kısıtlar. Köken arası kaynak paylaşımı (CORS) yapılandırması olmadan, JavaScript aracısı tüm HTTP üstbilgilerini yakalayamayabilir. CRS ' yi etkinleştirmek için bkz. Köken Arası İstek Arka Uç İlintisi. CORS ile, JavaScript Agent tarafından yalnızca COSR ' nin karşıladığı istek/yanıt üstbilgileri ve Erişim Denetimi-Göster-Üstbilgileri 'nde tanımlananlar toplanabilir.

ineum('captureHeaders', [/content-type/i]);