Contoh instrumentasi Node.js

Dokumen ini menjelaskan cara menginstrumentasi aplikasi JavaScript Node.js untuk mengumpulkan data trace dan metrik menggunakan SDK OpenTelemetry dan pengumpul OpenTelemetry. Dokumen ini juga menjelaskan cara menulis log JSON terstruktur ke output standar. Untuk bereksperimen dengan instrumentasi, download dan jalankan aplikasi contoh. Aplikasi ini menggunakan framework web Fastify dan menghasilkan data log, metrik, dan rekaman aktivitas.

Saat menggunakan pengumpul OpenTelemetry, Anda menginstrumentasikan aplikasi dengan SDK dan pengekspor dalam proses OTLP SDK. Pengukuran ini bersifat netral terhadap vendor. Anda juga men-deploy OpenTelemetry Collector yang menerima telemetri dari pengekspor dalam proses, lalu mengekspor telemetri tersebut ke project Google Cloud Anda. Untuk mempelajari lebih lanjut pengumpul, lihat Pengumpul OpenTelemetry Buatan Google.

Sebaiknya gunakan pengumpul OpenTelemetry untuk mengekspor data telemetri Anda jika lingkungan Anda mendukung penggunaan pengumpul. Untuk beberapa lingkungan, Anda harus menggunakan eksportir dalam proses yang mengirimkan data langsung ke projectGoogle Cloud Anda. Untuk mempelajari instrumentasi dalam proses, lihat Bermigrasi dari eksportir Trace ke endpoint OTLP.

Untuk mempelajari lebih lanjut instrumentasi, lihat dokumen berikut:

• Instrumentasi dan kemampuan observasi.
• Pilih pendekatan instrumentasi.

Catatan: Dokumen ini hanya menampilkan bagian aplikasi yang berfungsi dan dipilih. Misalnya, contoh tidak menampilkan daftar paket yang diimpor. Namun, aplikasi lengkapnya tersedia di GitHub. Untuk melihat contoh lengkapnya, klik Lainnya, lalu pilih Lihat di GitHub.

Tentang instrumentasi manual dan tanpa kode

Untuk bahasa ini, OpenTelemetry mendefinisikan instrumentasi tanpa kode sebagai praktik mengumpulkan telemetri dari library dan framework tanpa melakukan perubahan kode. Namun, Anda harus menginstal modul dan menetapkan variabel lingkungan.

Dokumen ini tidak menjelaskan instrumentasi tanpa kode. Untuk mengetahui informasi tentang topik tersebut, lihat Pelengkapan kode tanpa kode JavaScript.

Untuk mengetahui informasi umum, lihat Instrumentasi OpenTelemetry untuk Node.js.

Sebelum memulai

Login ke akun Google Cloud Anda. Jika Anda baru menggunakan Google Cloud, buat akun untuk mengevaluasi performa produk kami dalam skenario dunia nyata. Pelanggan baru juga mendapatkan kredit gratis senilai $300 untuk menjalankan, menguji, dan men-deploy workload.

Instal Google Cloud CLI.

Jika Anda menggunakan penyedia identitas (IdP) eksternal, Anda harus login ke gcloud CLI dengan identitas gabungan Anda terlebih dahulu.

Untuk melakukan inisialisasi gcloud CLI, jalankan perintah berikut:

gcloud init

Buat atau pilih Google Cloud project.

Peran yang diperlukan untuk memilih atau membuat project

• Pilih project: Memilih project tidak memerlukan peran IAM tertentu—Anda dapat memilih project mana pun yang telah diberi peran.
• Membuat project: Untuk membuat project, Anda memerlukan peran Pembuat Project (roles/resourcemanager.projectCreator), yang berisi izin resourcemanager.projects.create. Pelajari cara memberikan peran.

Catatan: Jika tidak berencana untuk menyimpan resource yang Anda buat dalam prosedur ini, buatlah project, bukan memilih project yang ada. Setelah menyelesaikan langkah ini, Anda dapat menghapus project, yang menghapus semua resource yang terkait dengan project ini.

• Buat Google Cloud project:

  gcloud projects create PROJECT_ID

  Ganti PROJECT_ID dengan nama untuk Google Cloud project yang Anda buat.

• Pilih project Google Cloud yang Anda buat:

  gcloud config set project PROJECT_ID

  Ganti PROJECT_ID dengan nama project Google Cloud Anda.

Verifikasi bahwa penagihan diaktifkan untuk project Google Cloud Anda.

Aktifkan Cloud Logging, Cloud Monitoring, Cloud Trace, dan Telemetry API:

Peran yang diperlukan untuk mengaktifkan API

Untuk mengaktifkan API, Anda memerlukan peran IAM Service Usage Admin (roles/serviceusage.serviceUsageAdmin), yang berisi izin serviceusage.services.enable. Pelajari cara memberikan peran.

gcloud services enable logging.googleapis.com monitoring.googleapis.com cloudtrace.googleapis.com telemetry.googleapis.com

Instal Google Cloud CLI.

Jika Anda menggunakan penyedia identitas (IdP) eksternal, Anda harus login ke gcloud CLI dengan identitas gabungan Anda terlebih dahulu.

Untuk melakukan inisialisasi gcloud CLI, jalankan perintah berikut:

gcloud init

Buat atau pilih Google Cloud project.

Peran yang diperlukan untuk memilih atau membuat project

• Pilih project: Memilih project tidak memerlukan peran IAM tertentu—Anda dapat memilih project mana pun yang telah diberi peran.
• Membuat project: Untuk membuat project, Anda memerlukan peran Pembuat Project (roles/resourcemanager.projectCreator), yang berisi izin resourcemanager.projects.create. Pelajari cara memberikan peran.

Catatan: Jika tidak berencana untuk menyimpan resource yang Anda buat dalam prosedur ini, buatlah project, bukan memilih project yang ada. Setelah menyelesaikan langkah ini, Anda dapat menghapus project, yang menghapus semua resource yang terkait dengan project ini.

• Buat Google Cloud project:

  gcloud projects create PROJECT_ID

  Ganti PROJECT_ID dengan nama untuk Google Cloud project yang Anda buat.

• Pilih project Google Cloud yang Anda buat:

  gcloud config set project PROJECT_ID

  Ganti PROJECT_ID dengan nama project Google Cloud Anda.

Verifikasi bahwa penagihan diaktifkan untuk project Google Cloud Anda.

Aktifkan Cloud Logging, Cloud Monitoring, Cloud Trace, dan Telemetry API:

Peran yang diperlukan untuk mengaktifkan API

Untuk mengaktifkan API, Anda memerlukan peran IAM Service Usage Admin (roles/serviceusage.serviceUsageAdmin), yang berisi izin serviceusage.services.enable. Pelajari cara memberikan peran.

gcloud services enable logging.googleapis.com monitoring.googleapis.com cloudtrace.googleapis.com telemetry.googleapis.com

1. Jika Anda menjalankan sampel di Cloud Shell, di resource Google Cloud, atau di lingkungan pengembangan lokal, izin yang tercantum di bagian ini sudah cukup. Untuk aplikasi produksi, biasanya akun layanan menyediakan kredensial untuk menulis data log, metrik, dan trace.

   Untuk mendapatkan izin yang diperlukan agar aplikasi contoh dapat menulis data log, metrik, dan rekaman aktivitas, minta administrator untuk memberi Anda peran IAM berikut di project Anda:

   • Logs Writer (roles/logging.logWriter)
   • Monitoring Metric Writer (roles/monitoring.metricWriter)
   • Cloud Telemetry Traces Writer (roles/telemetry.tracesWriter)

   Untuk mendapatkan izin yang Anda perlukan untuk melihat data log, metrik, dan rekaman aktivitas, minta administrator untuk memberi Anda peran IAM berikut di project Anda:

   • Logs Viewer (roles/logging.viewer)
   • Monitoring Viewer (roles/monitoring.viewer)
   • Cloud Trace User (roles/cloudtrace.user)

   Untuk mengetahui informasi selengkapnya tentang pemberian peran, lihat Mengelola akses ke project, folder, dan organisasi.

   Anda mungkin juga bisa mendapatkan izin yang diperlukan melalui peran khusus atau peran bawaan lainnya.

Melengkapi aplikasi Anda untuk mengumpulkan rekaman aktivitas, metrik, dan log

Untuk menginstrumentasi aplikasi Anda guna mengumpulkan data rekaman aktivitas dan metrik, serta menulis JSON terstruktur ke output standar, lakukan langkah-langkah berikut seperti yang dijelaskan di bagian selanjutnya dalam dokumen ini:

1. Mengonfigurasi OpenTelemetry
2. Mengonfigurasi aplikasi Anda untuk memuat ulang konfigurasi OpenTelemetry
3. Mengonfigurasi logging terstruktur
4. Menulis log terstruktur

Mengonfigurasi OpenTelemetry

Konfigurasi default untuk OpenTelemetry Node.js SDK mengekspor trace menggunakan protokol OTLP. Selain itu, kode ini mengonfigurasi OpenTelemetry untuk menggunakan format W3C Trace Context untuk mempropagasi konteks trace. Konfigurasi ini memastikan bahwa rentang memiliki hubungan induk-turunan yang benar dalam rekaman aktivitas.

Contoh kode berikut menggambarkan modul JavaScript untuk menyiapkan OpenTelemetry.

Untuk melihat contoh lengkapnya, klik Lainnya, lalu pilih Lihat di GitHub.

diag.setLogger(
  new DiagConsoleLogger(),
  opentelemetry.core.diagLogLevelFromString(
    opentelemetry.core.getStringFromEnv('OTEL_LOG_LEVEL')
  )
);

const sdk = new opentelemetry.NodeSDK({
  instrumentations: getNodeAutoInstrumentations({
    // Disable noisy instrumentations
    '@opentelemetry/instrumentation-fs': {enabled: false},
  }),
  resourceDetectors: getResourceDetectorsFromEnv(),
  metricReader: getMetricReader(),
});

try {
  sdk.start();
  diag.info('OpenTelemetry automatic instrumentation started successfully');
} catch (error) {
  diag.error(
    'Error initializing OpenTelemetry SDK. Your application is not instrumented and will not produce telemetry',
    error
  );
}

// Gracefully shut down the SDK to flush telemetry when the program exits
process.on('SIGTERM', () => {
  sdk
    .shutdown()
    .then(() => diag.debug('OpenTelemetry SDK terminated'))
    .catch(error => diag.error('Error terminating OpenTelemetry SDK', error));
});

Contoh kode sebelumnya mengonfigurasi OpenTelemetry untuk mengekspor metrik menggunakan protokol OTLP, dan menggunakan paket @opentelemetry/auto-instrumentations-node untuk mengonfigurasi semua instrumentasi Node.js yang tersedia.

Untuk memastikan semua telemetri yang tertunda dibersihkan dan koneksi ditutup dengan benar sebelum aplikasi dimatikan, handler SIGTERM memanggil shutdown.

Untuk mengetahui informasi dan opsi konfigurasi selengkapnya, lihat Konfigurasi Instrumentasi Tanpa Kode.

Mengonfigurasi aplikasi Anda untuk memuat konfigurasi OpenTelemetry terlebih dahulu

Untuk mengonfigurasi aplikasi agar menulis log terstruktur dan mengumpulkan data metrik dan trace menggunakan OpenTelemetry, perbarui pemanggilan aplikasi Anda untuk memuat modul instrumentasi terlebih dahulu dengan tanda --require Node.js. Menggunakan flag --require memastikan OpenTelemetry diinisialisasi sebelum aplikasi Anda dimulai. Untuk mengetahui informasi selengkapnya, lihat Mulai Menggunakan OpenTelemetry Node.js.

Contoh kode berikut menggambarkan Dockerfile yang meneruskan tanda --require:

CMD node --require ./build/src/instrumentation.js build/src/index.js 2>&1 | tee /var/log/app.log

Mengonfigurasi logging terstruktur

Untuk menyertakan informasi rekaman aktivitas sebagai bagian dari log berformat JSON yang ditulis ke output standar, konfigurasi aplikasi Anda untuk menghasilkan log terstruktur dalam format JSON.

Catatan: Contoh kode berikut bergantung pada Fastify, yang menggunakan framework log Pino dan menyediakan logger di setiap handler permintaan. Fungsi timestamp yang ditentukan dalam contoh menampilkan pasangan nilai kunci, dengan kuncinya diberi label "timestamp". Jika data log Anda tidak muncul seperti yang diharapkan, coba tetapkan kunci ke "time", bukan "timestamp".

Contoh kode berikut menggambarkan objek LoggerOptions Pino yang mengonfigurasi aplikasi untuk menghasilkan log terstruktur JSON:

// Expected attributes that OpenTelemetry adds to correlate logs with spans
interface LogRecord {
  trace_id?: string;
  span_id?: string;
  trace_flags?: string;
  [key: string]: unknown;
}

// https://cloud.google.com/logging/docs/reference/v2/rest/v2/LogEntry#logseverity
const PinoLevelToSeverityLookup: Record<string, string | undefined> = {
  trace: 'DEBUG',
  debug: 'DEBUG',
  info: 'INFO',
  warn: 'WARNING',
  error: 'ERROR',
  fatal: 'CRITICAL',
};

export const loggerConfig = {
  messageKey: 'message',
  // Same as pino.stdTimeFunctions.isoTime but uses "timestamp" key instead of "time"
  timestamp(): string {
    return `,"timestamp":"${new Date(Date.now()).toISOString()}"`;
  },
  formatters: {
    log(object: LogRecord): Record<string, unknown> {
      // Add trace context attributes following Cloud Logging structured log format described
      // in https://cloud.google.com/logging/docs/structured-logging#special-payload-fields
      const {trace_id, span_id, trace_flags, ...rest} = object;

      return {
        'logging.googleapis.com/trace': trace_id,
        'logging.googleapis.com/spanId': span_id,
        'logging.googleapis.com/trace_sampled': trace_flags
          ? trace_flags === '01'
          : undefined,
        ...rest,
      };
    },
    // See
    // https://getpino.io/#/docs/help?id=mapping-pino-log-levels-to-google-cloud-logging-stackdriver-severity-levels
    level(label: string) {
      return {
        severity:
          PinoLevelToSeverityLookup[label] ?? PinoLevelToSeverityLookup['info'],
      };
    },
  },
} satisfies LoggerOptions;

Konfigurasi sebelumnya mengekstrak informasi tentang rentang aktif dari pesan log, lalu menambahkan informasi tersebut sebagai atribut ke log terstruktur JSON. Atribut ini kemudian dapat digunakan untuk mengorelasikan log dengan rekaman aktivitas:

• logging.googleapis.com/trace: Nama resource rekaman aktivitas yang terkait dengan entri log.
• logging.googleapis.com/spanId: ID rentang dengan rekaman aktivitas yang terkait dengan entri log.
• logging.googleapis.com/trace_sampled: Nilai kolom ini harus berupa true atau false.

Untuk mengetahui informasi selengkapnya tentang kolom ini, lihat struktur LogEntry.

Untuk menggunakan konfigurasi Pino dengan Fastify, teruskan objek konfigurasi logger saat membuat aplikasi Fastify:

// Create the Fastify app providing the Pino logger config
const fastify = Fastify({
  logger: loggerConfig,
});

Menulis log terstruktur

Untuk menulis log terstruktur yang ditautkan ke rekaman aktivitas, gunakan pencatat log Pino yang disediakan Fastify. Misalnya, pernyataan berikut menunjukkan cara memanggil metode Logger.info():

request.log.info({subRequests}, 'handle /multi request');

OpenTelemetry otomatis mengisi entri log Pino dengan konteks span dari span aktif saat ini di Konteks OpenTelemetry. Konteks rentang ini kemudian disertakan dalam log JSON seperti yang dijelaskan dalam Mengonfigurasi logging terstruktur.

Menjalankan aplikasi contoh yang dikonfigurasi untuk mengumpulkan telemetri

Instrumentasi di aplikasi contoh menggunakan format netral vendor, seperti JSON untuk data log dan OTLP untuk data metrik dan pelacakan. Aplikasi ini juga menggunakan dan framework Fastify. OpenTelemetry Collector mengirimkan data log dan metrik ke project Anda menggunakan pengekspor Google. Agen ini mengirimkan data rekaman aktivitas ke project Anda menggunakan Telemetry API, yang menggunakan OTLP.

Aplikasi ini memiliki dua endpoint:

• Endpoint /multi ditangani oleh fungsi handleMulti. Generator beban di aplikasi mengirimkan permintaan ke endpoint /multi. Saat menerima permintaan, endpoint ini akan mengirimkan tiga hingga tujuh permintaan ke endpoint /single di server lokal.

  /**
   * handleMulti handles an http request by making 3-7 http requests to the /single endpoint.
   *
   * OpenTelemetry instrumentation requires no changes here. It will automatically generate a
   * span for the handler body.
   */
  fastify.get('/multi', async request => {
    const subRequests = randInt(3, 8);
    request.log.info({subRequests}, 'handle /multi request');
  
    for (let i = 0; i < subRequests; i++) {
      await axios.get(`http://localhost:${port}/single`);
    }
    return 'ok';
  });

• Endpoint /single ditangani oleh fungsi handleSingle. Saat menerima permintaan, endpoint ini akan tertidur selama beberapa saat, lalu merespons dengan string.

  /**
   * handleSingle handles an http request by sleeping for 100-200 ms. It writes the number of
   * milliseconds slept as its response.
   */
  fastify.get('/single', async request => {
    // Sleep between 100-200 milliseconds
    const sleepMillis = randInt(100, 200);
    request.log.info({sleepMillis}, 'Going to sleep');
    await sleep(sleepMillis);
    return `slept ${sleepMillis}\n`;
  });

Mendownload dan men-deploy aplikasi

Catatan: Sebaiknya jalankan aplikasi contoh menggunakan Cloud Shell. Namun, jika Anda ingin menjalankan aplikasi contoh secara lokal di Linux atau Mac, lewati langkah pertama dalam petunjuk berikut.

Untuk menjalankan contoh, lakukan hal berikut:

1. Di konsol Google Cloud , aktifkan Cloud Shell.

   Aktifkan Cloud Shell

   Di bagian bawah konsol Google Cloud , sesi Cloud Shell akan dimulai dan menampilkan perintah command line. Cloud Shell adalah lingkungan shell dengan Google Cloud CLI yang sudah terinstal, dan dengan nilai yang sudah ditetapkan untuk project Anda saat ini. Diperlukan waktu beberapa detik untuk melakukan inisialisasi pada sesi.

2. Buat clone repositori:

   git clone https://github.com/GoogleCloudPlatform/opentelemetry-operations-js
   

3. Buka direktori contoh:

   cd opentelemetry-operations-js/samples/instrumentation-quickstart
   

4. Buat dan jalankan sampel:

   docker compose up --abort-on-container-exit
   

   Jika Anda tidak menjalankan di Cloud Shell, jalankan aplikasi dengan variabel lingkungan GOOGLE_APPLICATION_CREDENTIALS yang mengarah ke file kredensial. Kredensial Default Aplikasi menyediakan file kredensial di $HOME/.config/gcloud/application_default_credentials.json.

   # Set environment variables
   export GOOGLE_CLOUD_PROJECT="PROJECT_ID"
   export GOOGLE_APPLICATION_CREDENTIALS="$HOME/.config/gcloud/application_default_credentials.json"
   export USERID="$(id -u)"
   
   # Run
   docker compose -f docker-compose.yaml -f docker-compose.creds.yaml up --abort-on-container-exit
   

Melihat metrik

Instrumentasi OpenTelemetry di aplikasi contoh menghasilkan metrik Prometheus yang dapat Anda lihat menggunakan Metrics Explorer:

• Prometheus/http_server_duration_milliseconds/histogram mencatat durasi permintaan server dan menyimpan hasilnya dalam histogram.

• Prometheus/http_client_duration_milliseconds/histogram mencatat durasi permintaan klien dan menyimpan hasilnya dalam histogram.

Untuk melihat metrik yang dihasilkan oleh aplikasi contoh, lakukan hal berikut:

1. Di konsol Google Cloud , buka halaman  Metrics explorer:

   Buka Metrics explorer

   Jika Anda menggunakan kotak penelusuran untuk menemukan halaman ini, pilih hasil yang subjudulnya adalah Monitoring.

2. Di toolbar konsol Google Cloud , pilih project Google Cloud Anda. Untuk konfigurasi App Hub, pilih project host App Hub atau project pengelolaan folder yang mendukung aplikasi.
3. Pada elemen Metrik, luaskan menu Pilih metrik, masukkan http_server di panel filter, lalu gunakan submenu untuk memilih jenis dan metrik resource tertentu:
   1. Di menu Active resources, pilih Prometheus Target.
   2. Di menu Active metric categories, pilih Http.
   3. Di menu Metrik aktif, pilih metrik.
   4. Klik Terapkan.

4. Untuk menambahkan filter, yang menghapus deret waktu dari hasil kueri, gunakan elemen Filter.

5. Konfigurasi cara data dilihat.
   

   Jika pengukuran untuk metrik bersifat kumulatif, Metrics Explorer akan otomatis menormalisasi data yang diukur berdasarkan periode perataan, sehingga diagram menampilkan rasio. Untuk mengetahui informasi selengkapnya, lihat Jenis, tipe, dan konversi.

   Saat nilai bilangan bulat atau ganda diukur, seperti dengan dua metrik counter, Metrics Explorer akan otomatis menjumlahkan semua deret waktu. Untuk melihat data untuk rute HTTP /multi dan /single, tetapkan menu pertama entri Aggregation ke None.

   Untuk informasi selengkapnya tentang cara mengonfigurasi diagram, lihat Memilih metrik saat menggunakan Metrics Explorer.

Melihat trace Anda

Mungkin perlu waktu beberapa menit sebelum data rekaman aktivitas Anda tersedia. Misalnya, saat data rekaman aktivitas diterima oleh project Anda, Google Cloud Observability mungkin perlu membuat database untuk menyimpan data tersebut. Pembuatan database dapat memerlukan waktu beberapa menit dan selama periode tersebut, tidak ada data rekaman aktivitas yang tersedia untuk dilihat.

Untuk melihat data rekaman aktivitas, lakukan hal berikut:

1. Di konsol Google Cloud , buka halaman Trace explorer:

   Buka Trace explorer

   Anda juga dapat menemukan halaman ini dengan menggunakan kotak penelusuran.

2. Di bagian tabel halaman, pilih baris dengan nama rentang /multi.

3. Pada diagram Gantt di panel Trace details, pilih rentang yang diberi label /multi.

   Panel yang menampilkan informasi tentang permintaan HTTP akan terbuka. Detail ini mencakup metode, kode status, jumlah byte, dan agen pengguna pemanggil.

4. Untuk melihat log yang terkait dengan rekaman aktivitas ini, pilih tab Logs & Events.

   Tab ini menampilkan log individual. Untuk melihat detail entri log, luaskan entri log. Anda juga dapat mengklik View Logs dan melihat log menggunakan Logs Explorer.

Untuk mengetahui informasi selengkapnya tentang cara menggunakan penjelajah Cloud Trace, lihat Menemukan dan menjelajahi rekaman aktivitas.

Melihat log

Dari Logs Explorer, Anda dapat memeriksa log, dan Anda juga dapat melihat rekaman aktivitas terkait, jika ada.

1. Di konsol Google Cloud , buka segmen Logs Explorer:

   Buka Logs Explorer

   Jika Anda menggunakan kotak penelusuran untuk menemukan halaman ini, pilih hasil yang subjudulnya adalah Logging.

2. Temukan log dengan deskripsi handle /multi request.

   Untuk melihat detail log, luaskan entri log.

3. Klik Traces pada entri log dengan pesan "handle /multi request", lalu pilih View trace details.

   Panel Detail rekaman aktivitas akan terbuka dan menampilkan rekaman aktivitas yang dipilih.

   Data log Anda mungkin tersedia beberapa menit sebelum data rekaman aktivitas Anda tersedia. Jika Anda mengalami error saat melihat data rekaman aktivitas baik dengan menelusuri rekaman aktivitas menurut ID atau dengan mengikuti langkah-langkah dalam tugas ini, tunggu satu atau dua menit, lalu coba lagi tindakan tersebut.

Untuk mengetahui informasi selengkapnya tentang cara menggunakan Logs Explorer, lihat Melihat log menggunakan Logs Explorer.

Langkah berikutnya

• OpenTelemetry
• Spesifikasi OTLP
• Logging terstruktur
• Memecahkan masalah Managed Service for Prometheus
• Memecahkan Masalah Cloud Trace