Node.js dan OpenTelemetry

Halaman ini ditujukan bagi developer aplikasi yang ingin mengumpulkan data Cloud Trace untuk aplikasi Node.js menggunakan OpenTelemetry. OpenTelemetry adalah framework instrumentasi yang tidak bergantung pada vendor yang dapat Anda gunakan untuk mengumpulkan data trace dan metrik. Untuk mengetahui informasi tentang cara menginstrumentasikan kode, lihat Instrumentasi dan kemampuan observasi.

Catatan: Informasi pada halaman ini dibatasi hanya untuk mengumpulkan data trace. Untuk contoh yang lebih lengkap, salah satu yang menggambarkan cara mengumpulkan data trace dan metrik dengan menggunakan OpenTelemetry, serta cara menulis log JSON terstruktur untuk standar, lihat Membuat trace dan metrik dengan Node.js.

Halaman ini akan memandu Anda melakukan langkah-langkah berikut:

• Instal paket OpenTelemetry.
• Konfigurasi aplikasi Anda untuk mengekspor span ke Cloud Trace.
• Konfigurasi platform Anda.

Untuk informasi rilis, lihat referensi berikut:

• Rilis library terbaru untuk Node.js

• Rilis pengekspor Cloud Trace terbaru untuk Node.js

Untuk konten referensi OpenTelemetry, lihat hal berikut:

• Tracer
• Span

Untuk detail terbaru tentang OpenTelemetry untuk Node.js, beserta dokumentasi dan contoh tambahan, lihat OpenTelemetry.

Sebelum memulai

1. Di panel navigasi Konsol Google Cloud, pilih APIs & Services, klik Enable APIs and Services, lalu aktifkan Cloud Trace API:

   Buka setelan Cloud Trace API

2. Jika API enabled ditampilkan, berarti API sudah diaktifkan. Jika belum, klik tombol Enable.

Menginstal, menginisialisasi, dan menggunakan klien

OpenTelemetry menawarkan cara berikut untuk melengkapi aplikasi Anda:

• Instrumentasi otomatis untuk aplikasi Node.js

  Saat menggunakan pendekatan ini, Anda mengonfigurasi aplikasi untuk menyertakan @opentelemetry/sdk-trace-node SDK. Namun, Anda tidak perlu membuat perubahan kode pada library apa pun yang digunakan.

• Pelacakan manual

  Saat pendekatan ini digunakan, Anda akan mengubah library yang digunakan untuk mengumpulkan informasi rekaman aktivitas.

Bagian berikut menunjukkan kasus penggunaan untuk setiap instrumentasi.

Instrumentasi otomatis

Modul @opentelemetry/sdk-trace-node menyediakan instrumentasi otomatis untuk aplikasi Node.js.

Instrumentasi otomatis akan otomatis mengidentifikasi hal-hal berikut dalam aplikasi Anda:

• Framework, seperti Express
• Protokol umum, seperti HTTP, HTTPS, dan gRPC
• Database, seperti MySQL, MongoDB, Redis, dan PostgreSQL
• Library lain dalam aplikasi Anda

Instrumentasi otomatis menyediakan pelacakan yang siap digunakan, sehingga Anda tidak perlu membuat perubahan kode pada library apa pun yang digunakan. Kode instrumentasi secara otomatis melakukan tindakan berikut:

• Mengekstrak ID konteks rekaman aktivitas dari permintaan masuk untuk memungkinkan pelacakan terdistribusi, jika berlaku.
• Memastikan bahwa konteks rekaman aktivitas saat ini disebarkan saat transaksi melintasi aplikasi.
• Menambahkan ID konteks rekaman aktivitas ke permintaan keluar, yang memungkinkan rekaman aktivitas yang didistribusikan untuk melanjutkan ke hop berikutnya, jika berlaku.
• Membuat dan mengakhiri span.

Modul ini menggunakan plugin untuk secara otomatis menginstrumentasikan aplikasi Anda untuk menghasilkan span dan menyediakan pelacakan menyeluruh hanya dengan beberapa baris kode.

Instrumentasi manual

Modul pelacakan manual, @opentelemetry/sdk-trace-base, memberikan kontrol penuh atas instrumentasi dan pembuatan span. async_hooks tidak akan dimuat. Library ini tidak menggunakan penyimpanan lokal lanjutan atau plugin instrumentasi apa pun secara default. Pelacakan manual memiliki implikasi overhead performa yang lebih sedikit dibandingkan dengan modul instrumentasi otomatis.

Contoh

Petunjuk berikut menunjukkan cara menggunakan modul instrumentasi otomatis untuk Compute Engine dan Google Kubernetes Engine.

Compute Engine

Instal paket berikut:

npm install --save @opentelemetry/api
npm install --save @opentelemetry/sdk-trace-node
npm install --save @opentelemetry/sdk-trace-base
npm install --save @google-cloud/opentelemetry-cloud-trace-exporter

Tambahkan kode berikut ke aplikasi Anda untuk melakukan inisialisasi dan mendaftarkan pengekspor:

const opentelemetry = require("@opentelemetry/api");
const { NodeTracerProvider } = require("@opentelemetry/sdk-trace-node");
const { BatchSpanProcessor } = require("@opentelemetry/sdk-trace-base");
const {
  TraceExporter,
} = require("@google-cloud/opentelemetry-cloud-trace-exporter");

// Enable OpenTelemetry exporters to export traces to Google Cloud Trace.
// Exporters use Application Default Credentials (ADCs) to authenticate.
// See https://developers.google.com/identity/protocols/application-default-credentials
// for more details.
const provider = new NodeTracerProvider();

// Initialize the exporter. When your application is running on Google Cloud,
// you don't need to provide auth credentials or a project id.
const exporter = new TraceExporter();

// Configure the span processor to batch and send spans to the exporter
provider.addSpanProcessor(new BatchSpanProcessor(exporter));

GKE

Tambahkan kode berikut ke Dockerfile:

RUN npm install --save @opentelemetry/api
RUN npm install --save @opentelemetry/sdk-trace-node
RUN npm install --save @opentelemetry/sdk-trace-base
RUN npm install --save @google-cloud/opentelemetry-cloud-trace-exporter

Tambahkan kode berikut ke aplikasi Anda untuk melakukan inisialisasi dan mendaftarkan pengekspor:

const opentelemetry = require("@opentelemetry/api");
const { NodeTracerProvider } = require("@opentelemetry/sdk-trace-node");
const { BatchSpanProcessor } = require("@opentelemetry/sdk-trace-base");
const {
  TraceExporter,
} = require("@google-cloud/opentelemetry-cloud-trace-exporter");

// Enable OpenTelemetry exporters to export traces to Google Cloud Trace.
// Exporters use Application Default Credentials (ADCs) to authenticate.
// See https://developers.google.com/identity/protocols/application-default-credentials
// for more details.
const provider = new NodeTracerProvider();

// Initialize the exporter. When your application is running on Google Cloud,
// you don't need to provide auth credentials or a project id.
const exporter = new TraceExporter();

// Configure the span processor to batch and send spans to the exporter
provider.addSpanProcessor(new BatchSpanProcessor(exporter));

Aplikasi contoh menggunakan framework Express

Dengan Instrumentasi OpenTelemetry Express, Anda dapat otomatis mengumpulkan data rekaman aktivitas dan mengekspornya ke backend pilihan Anda, sehingga Anda dapat mengamati sistem yang terdistribusi.

Agar dapat menggunakan OpenTelemetry untuk aplikasi yang menggunakan framework Express, selesaikan langkah-langkah berikut:

1. Instal paket berikut:

   npm install --save @opentelemetry/instrumentation-http
   npm install --save @opentelemetry/instrumentation-express
   

2. Tambahkan kode berikut ke aplikasi Anda, yang memuat semua plugin yang didukung:

   const { NodeTracerProvider } = require('@opentelemetry/sdk-trace-node');
   const provider = new NodeTracerProvider();
   

Untuk contoh dasar, lihat contoh OpenTelemetry Express.

Membuat span kustom

Anda dapat menambahkan informasi tambahan ke pelacakan yang dibuat sistem dengan membuat span kustom.

Untuk membuat span kustom, tambahkan kode berikut ke kode sumber:

// Initialize the OpenTelemetry APIs to use the
// NodeTracerProvider bindings
provider.register();
const tracer = opentelemetry.trace.getTracer("basic");

// Create a span.
const span = tracer.startSpan("foo");

// Set attributes to the span.
span.setAttribute("key", "value");

// Annotate our span to capture metadata about our operation
span.addEvent("invoking work");

// simulate some random work.
for (let i = 0; i <= Math.floor(Math.random() * 40000000); i += 1) {}

// Be sure to end the span.
span.end();

• getTracer menampilkan instance tracer, dengan basic adalah nama tracer atau library instrumentasi. Ini memberi tahu OpenTelemetry siapa yang membuat span.

• foo adalah nama span kustom.

• invoking work adalah nama contoh peristiwa. Contoh ini menunjukkan cara menggunakan addEvent API.

Untuk contoh dasar pembuatan span kustom, lihat contoh OpenTelemetry.

Konfigurasi platform Anda

Anda dapat menggunakan Cloud Trace di Google Cloud dan platform lainnya.

Berjalan di Google Cloud

Saat aplikasi Anda berjalan di Google Cloud, Anda tidak perlu memberikan kredensial autentikasi dalam bentuk akun layanan ke library klien. Namun, Anda harus memastikan bahwa platform Google Cloud Anda telah mengaktifkan cakupan akses Cloud Trace API.

Untuk mengetahui daftar lingkungan Google Cloud yang didukung, lihat Dukungan lingkungan.

Untuk konfigurasi berikut, setelan cakupan akses default akan mengaktifkan Cloud Trace API:

• Lingkungan fleksibel App Engine

• Lingkungan standar App Engine

• Google Kubernetes Engine (GKE)

  Catatan: Jika menggunakan Autopilot atau mengaktifkan Workload Identity untuk cluster GKE, pastikan Anda mengonfigurasi aplikasi untuk menggunakan Workload Identity.

• Compute Engine

• Cloud Run

Jika menggunakan cakupan akses kustom, Anda harus memastikan cakupan akses API Cloud Trace diaktifkan:

• Untuk mengetahui informasi cara mengonfigurasi cakupan akses untuk lingkungan Anda menggunakan Konsol Google Cloud, lihat Mengonfigurasi project Google Cloud.

• Untuk pengguna gcloud, tentukan cakupan akses menggunakan flag --scopes dan sertakan cakupan akses Cloud Trace API trace.append. Misalnya, untuk membuat cluster GKE dengan hanya Cloud Trace API yang diaktifkan, lakukan hal berikut:

  gcloud container clusters create example-cluster-name --scopes=https://www.googleapis.com/auth/trace.append

Berjalan secara lokal dan di tempat lain

Jika aplikasi Anda berjalan di luar Google Cloud, Anda harus memberikan kredensial autentikasi dalam bentuk akun layanan ke library klien. Akun layanan harus berisi peran agen Cloud Trace. Untuk mengetahui petunjuknya, lihat Membuat akun layanan.

Library klien Google Cloud menggunakan Kredensial Default Aplikasi (ADC) untuk menemukan kredensial aplikasi Anda.

Anda dapat memberikan kredensial ini dengan salah satu dari tiga cara:

• Jalankan gcloud auth application-default login

• Tempatkan akun layanan di jalur default untuk sistem operasi Anda. Berikut ini daftar jalur default untuk Windows dan Linux:

  • Windows: %APPDATA%/gcloud/application_default_credentials.json

  • Linux: $HOME/.config/gcloud/application_default_credentials.json

• Tetapkan variabel lingkungan GOOGLE_APPLICATION_CREDENTIALS ke jalur ke akun layanan Anda:

Linux/macOS

    export GOOGLE_APPLICATION_CREDENTIALS=path-to-your-service-accounts-private-key

Windows

    set GOOGLE_APPLICATION_CREDENTIALS=path-to-your-service-accounts-private-key

PowerShell:

    $env:GOOGLE_APPLICATION_CREDENTIALS="path-to-your-service-accounts-private-key"

Lihat pelacakan

Di panel navigasi konsol Google Cloud, pilih Trace, lalu pilih Trace explorer:

Buka Trace explorer

Pemecahan masalah

Untuk mengetahui informasi tentang cara memecahkan masalah terkait Cloud Trace, buka halaman Pemecahan masalah.