Membuat trace dan metrik dengan Node.js

Dokumen ini menjelaskan cara mengubah aplikasi JavaScript Node.js untuk mengumpulkan data trace dan metrik menggunakan framework OpenTelemetry open source, dan cara menulis log JSON terstruktur ke output standar. Dokumen ini juga memberikan informasi tentang contoh aplikasi Node.js yang dapat Anda instal dan jalankan. Aplikasi ini menggunakan framework web Fastify dan dikonfigurasi untuk menghasilkan metrik, rekaman aktivitas, dan log.

Untuk mempelajari instrumentasi lebih lanjut, lihat dokumen berikut:

Tentang instrumentasi manual dan otomatis

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

Dokumen ini tidak menjelaskan instrumentasi otomatis. Untuk informasi tentang topik tersebut, lihat Instrumentasi Otomatis untuk Node.

Untuk informasi umum, lihat Instrumentasi OpenTelemetry untuk Node.

Sebelum memulai

Enable the Cloud Logging, Cloud Monitoring, and Cloud Trace APIs.

Enable the APIs

Menginstrumentasikan aplikasi untuk mengumpulkan trace, metrik, dan log

Untuk melengkapi 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 berikutnya dalam dokumen ini:

  1. Mengonfigurasi OpenTelemetry
  2. Mengonfigurasi aplikasi untuk memuat konfigurasi OpenTelemetry secara otomatis
  3. Mengonfigurasi logging terstruktur
  4. Menulis log terstruktur

Mengonfigurasi OpenTelemetry

Konfigurasi default untuk OpenTelemetry Node.js SDK mengekspor trace menggunakan protokol OTLP. Fitur ini juga mengonfigurasi OpenTelemetry untuk menggunakan format Konteks Trace W3C guna memperluas konteks trace. Konfigurasi ini memastikan bahwa span memiliki hubungan induk-turunan yang benar dalam rekaman aktivitas.

Contoh kode berikut mengilustrasikan modul JavaScript untuk menyiapkan OpenTelemetry.

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


diag.setLogger(
  new DiagConsoleLogger(),
  opentelemetry.core.getEnv().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 dihapus dan koneksi ditutup dengan baik sebelum aplikasi dimatikan, pengendali SIGTERM memanggil shutdown.

Untuk informasi selengkapnya dan opsi konfigurasi, lihat Instrumentasi otomatis Node.js OpenTelemetry.

Mengonfigurasi aplikasi untuk memuat konfigurasi OpenTelemetry secara otomatis

Untuk mengonfigurasi aplikasi agar dapat menulis log terstruktur dan mengumpulkan metrik serta data trace menggunakan OpenTelemetry, perbarui pemanggilan aplikasi Anda untuk memuat ulang modul instrumentasi dengan tanda --require Node.js. Menggunakan tanda --require memastikan bahwa OpenTelemetry diinisialisasi sebelum aplikasi Anda dimulai. Untuk informasi selengkapnya, lihat Memulai Node.js OpenTelemetry.

Contoh kode berikut mengilustrasikan Dockerfile yang meneruskan flag --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, konfigurasikan aplikasi Anda untuk menghasilkan log terstruktur dalam format JSON. Fastify menggunakan framework log Pino dan menyediakan logger di setiap pengendali permintaan. Contoh kode berikut mengilustrasikan 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 span aktif dari pesan log, lalu menambahkan informasi tersebut sebagai atribut ke log terstruktur JSON. Atribut ini kemudian dapat digunakan untuk mengaitkan log dengan rekaman aktivitas:

  • logging.googleapis.com/trace: Nama resource rekaman aktivitas yang terkait dengan entri log.
  • logging.googleapis.com/spanId: ID span dengan rekaman aktivitas yang terkait dengan entri log.
  • logging.googleapis.com/trace_sampled: Nilai kolom ini harus 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 logger 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 span ini kemudian disertakan dalam log JSON seperti yang dijelaskan dalam Mengonfigurasi logging terstruktur.

Menjalankan aplikasi contoh yang dikonfigurasi untuk mengumpulkan telemetri

Aplikasi contoh menggunakan format yang netral vendor, termasuk JSON untuk log dan OTLP untuk metrik dan rekaman aktivitas, serta framework Fastify. Untuk merutekan telemetri ke Google Cloud, contoh ini menggunakan Collector OpenTelemetry yang dikonfigurasi dengan eksportir Google. 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 antara 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 endpoint ini menerima permintaan, endpoint akan tidur selama penundaan singkat, 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

Untuk menjalankan contoh, lakukan hal berikut:

  1. In the Google Cloud console, activate Cloud Shell.

    Activate Cloud Shell

    At the bottom of the Google Cloud console, a Cloud Shell session starts and displays a command-line prompt. Cloud Shell is a shell environment with the Google Cloud CLI already installed and with values already set for your current project. It can take a few seconds for the session to initialize.

  2. Meng-cloning repository

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

  3. Buka direktori contoh:

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

  4. Build dan jalankan contoh:

    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. Pada elemen Metric, luaskan menu Select a metric, 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 Active metrics, pilih metrik.
    4. Klik Terapkan.
  3. Konfigurasi cara data dilihat.

    Jika pengukuran untuk metrik bersifat kumulatif, Metrics Explorer akan otomatis menormalisasi data yang diukur menurut periode penyelarasan, yang akan menghasilkan diagram yang 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

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 menggunakan kotak penelusuran.

  2. Pada diagram sebar, pilih rekaman aktivitas dengan URI /multi.

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

    Panel akan terbuka dan menampilkan informasi tentang permintaan HTTP. 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 setiap log. Untuk melihat detail entri log, luaskan entri log. Anda juga dapat mengklik View Logs dan melihat log menggunakan Logs Explorer.

Untuk informasi selengkapnya tentang cara menggunakan Cloud Trace Explorer, lihat Menemukan dan menjelajahi trace.

Melihat log

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

  1. Di konsol Google Cloud, buka halaman 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 Trace details akan terbuka dan menampilkan rekaman aktivitas yang dipilih.

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

Langkah selanjutnya