OpenTelemetry dalam produksi: Hentikan proses debug dalam kegelapan

spinny:~/writing $ vim opentelemetry-nodejs-observability-guide.md

1~
2Pertama kali Anda benar-benar membutuhkan kemampuan observasi bukanlah saat Anda dengan tenang melihat ke dasbor. Itu ketika pengguna menulis "checkout lambat", grafik kesalahan terlihat normal dan di log Anda hanya menemukan deretan pesan yang terputus.
3~
4OpenTelemetry diciptakan untuk menghindari momen itu: bukan untuk memiliki lebih banyak grafik, tetapi untuk menghubungkan bagian-bagiannya. Permintaan memasuki API, memanggil database, melewati penyedia eksternal, memposting pekerjaan yang antri, dan mungkin gagal pada tiga layanan kemudian. Tanpa penelusuran terdistribusi, Anda merekonstruksi cerita itu dengan tangan. Dengan OpenTelemetry setidaknya Anda memiliki peta.
5~
6## Intinya bukan trace, tapi ceritanya
7~
8A trace adalah barisan span. Taruh seperti itu kedengarannya dingin. Dalam praktiknya, setiap span adalah bagian dari cerita: `POST /checkout`, `SELECT inventory`, `call payment provider`, `publish order.created`.
9~
10Nilainya muncul ketika Anda mulai menjawab pertanyaan nyata:
11~
12- layanan eksternal mana yang melambat?
13- apakah kesalahan berasal dari versi tertentu?
14- apakah masalahnya berdampak pada semua orang atau hanya satu penyewa?
15- apakah percobaan ulang menyembunyikan batas waktu?
16- pekerjaan asinkron dimulai tetapi kemudian mati di tempat lain?
17~
18Pertanyaan-pertanyaan ini tidak dapat diselesaikan dengan `console.log` yang dilontarkan secara terburu-buru. Memang sering kali log yang ditambahkan dalam keadaan darurat membantu Anda hari ini dan menjadi kebisingan besok.
19~
20## Bagaimana cara memasukkan ini ke dalam aplikasi Node.js
21~
22Penyiapan yang paling sehat adalah sederhana: aplikasi menghasilkan telemetri, Collector memutuskan ke mana akan mengirimkannya.
23~
24```text
25Node.js app -> OpenTelemetry Collector -> backend di observability
26```
27~
28Mengapa tidak mengekspor langsung ke vendornya? Karena pada awalnya tampak lebih cepat, kemudian Anda menyadari bahwa setiap layanan memiliki konfigurasi yang berbeda, percobaan ulang yang berbeda, filter yang berbeda dan tidak ada titik pusat untuk menghapus data sensitif atau mengubah tujuan.
29~
30Collector membosankan dalam semua hal yang benar. Ia menerima OTLP, melakukan pengelompokan, dapat memfilter, dapat melakukan pengambilan sampel, dapat menambahkan atribut umum, dan dapat mengekspor ke beberapa sistem.
31~
32## Instrumentasi diri: bagus, tapi tidak cukup
33~
34Di Node.js Saya akan mulai dengan instrumentasi otomatis. Ini memberi Anda visibilitas langsung ke HTTP, kerangka kerja yang didukung, database, dan perpustakaan umum.
35~
36```bash
37npm install @opentelemetry/sdk-node \
38  @opentelemetry/auto-instrumentations-node \
39  @opentelemetry/exporter-trace-otlp-http
40```
41~
42Kemudian Anda menginisialisasi SDK sebelum aplikasi lainnya:
43~
44```typescript
45import { NodeSDK } from '@opentelemetry/sdk-node';
46import { OTLPTraceExporter } from '@opentelemetry/exporter-trace-otlp-http';
47import { getNodeAutoInstrumentations } from '@opentelemetry/auto-instrumentations-node';
48~
49const sdk = new NodeSDK({
50  traceExporter: new OTLPTraceExporter({
51    url: process.env.OTEL_EXPORTER_OTLP_TRACES_ENDPOINT,
52  }),
53  instrumentations: [getNodeAutoInstrumentations()],
54});
55~
56sdk.start();
57```
58~
59Namun, ini melihat kerangka kerjanya, bukan produk Anda. Ia mengetahui Anda membuat kueri, tetapi ia tidak mengetahui bahwa kueri tersebut berada dalam "buat pesanan" atau "perpanjang langganan". Untuk itu Anda memerlukan span manual pada titik-titik di mana dominasi diperhitungkan.
60~
61```typescript
62const span = tracer.startSpan('checkout.create_order');
63~
64try {
65  span.setAttribute('cart.items_count', input.items.length);
66  const order = await createOrder(input);
67  span.setAttribute('order.id', order.id);
68  return order;
69} catch (error) {
70  span.recordException(error as Error);
71  throw error;
72} finally {
73  span.end();
74}
75```
76~
77Saya tidak akan meletakkan manual span di mana pun. Saya akan meletakkannya di tempat, pada jam tiga pagi, saya ingin memahami apa yang terjadi tanpa membaca setengah dari basis kode.
78~
79## Tiga aturan yang menghindari banyak kekacauan
80~
81Aturan pertama: setiap layanan harus memiliki `service.name`, lingkungan dan versi. Tampaknya sepele, tetapi tanpa atribut ini, trace kurang berguna. Saat penerapan merusak sesuatu, Anda ingin memfilter berdasarkan versi dalam dua detik.
82~
83Aturan kedua: jangan memasukkan data sensitif ke dalam atribut. Email, token, muatan bilangan bulat, dan alamat tidak boleh berakhir di backend observabilitas secara tidak sengaja. Jika Anda perlu mengidentifikasi pengguna, pertimbangkan ID internal, hashing, atau kolom yang kurang sensitif.
84~
85Aturan ketiga: perhatikan kardinalitas. `user.id` sebagai atribut trace bisa masuk akal. Sebagai label metrik, hal ini dapat merusak biaya dan kinerja Anda.
86~
87## Metrik: sedikit, tapi bagus
88~
89Saya akan mulai dengan metrik yang sangat praktis:
90~
91- tarif, kesalahan dan durasi permintaan;
92- latensi ketergantungan eksternal;
93- jumlah batas waktu dan percobaan ulang;
94- kedalaman ekor;
95- durasi pekerjaan;
96- persentase kesalahan per versi.
97~
98Sisanya ditambahkan bila diperlukan. Dasbor yang penuh dengan grafik yang tidak dilihat oleh siapa pun hanyalah furnitur, bukan yang dapat diamati.
99~
100## Log: Masih berguna, tetapi tertaut
101~
102Log tidak hilang. Mereka menjadi jauh lebih berguna ketika membawa `trace_id` dan `span_id`. Jadi Anda dapat memulai dari log kesalahan dan membuka trace, atau memulai dari trace yang lambat dan hanya membaca log yang dihasilkan di jalur tersebut.
103~
104Tanpa korelasi, Anda mencari jarum. Dengan korelasi, setidaknya Anda tahu laci mana yang harus dicari.
105~
106## Daftar periksa yang akan saya gunakan sebelum mengatakan "kita terlindungi"
107~
108- trace sebenarnya melintasi beberapa layanan.
109- Log termasuk `trace_id` dan `span_id`.
110- Collector dikonfigurasi dengan batching dan batas memori.
111- Kesalahan dicatat di span.
112- Ada kebijakan pengambilan sampel.
113- Metrik telah mengontrol kardinalitas.
114- Data sensitif disaring.
115- Peringatan dimulai dari gejala pengguna, bukan grafik acak.
116~
117## Kesimpulan
118~
119OpenTelemetry tidak menyelesaikan masalah produksi dengan sendirinya. Namun cara Anda menghadapinya berubah. Daripada menambahkan log secara membabi buta, Anda mulai mengikuti jalur permintaan yang sebenarnya.
120~
121Bagi saya tanda bahwa ini berhasil adalah sederhana: ketika sesuatu terjadi, tim berhenti bertanya "di mana kita mencari?" dan mulai bertanya "mengapa lagu itu lambat?". Di sinilah observabilitas menjadi sebuah alat, bukan kumpulan dasbor.
122~
123## Sumber
124~
125- [OpenTelemetry: Overview](https://opentelemetry.io/docs/specs/otel/overview/)
126- [OpenTelemetry Collector: Configuration](https://opentelemetry.io/docs/collector/configuration/)
127- [OpenTelemetry JavaScript: Node.js getting started](https://opentelemetry.io/docs/languages/js/getting-started/nodejs/)
128- [OpenTelemetry Semantic Conventions](https://opentelemetry.io/docs/concepts/semantic-conventions/)
129~

NORMAL · opentelemetry-nodejs-observability-guide.md [readonly]129 lines · :q to close

2Pertama kali Anda benar-benar membutuhkan kemampuan observasi bukanlah saat Anda dengan tenang melihat ke dasbor. Itu ketika pengguna menulis "checkout lambat", grafik kesalahan terlihat normal dan di log Anda hanya menemukan deretan pesan yang terputus.

4OpenTelemetry diciptakan untuk menghindari momen itu: bukan untuk memiliki lebih banyak grafik, tetapi untuk menghubungkan bagian-bagiannya. Permintaan memasuki API, memanggil database, melewati penyedia eksternal, memposting pekerjaan yang antri, dan mungkin gagal pada tiga layanan kemudian. Tanpa penelusuran terdistribusi, Anda merekonstruksi cerita itu dengan tangan. Dengan OpenTelemetry setidaknya Anda memiliki peta.

6## Intinya bukan trace, tapi ceritanya

8A trace adalah barisan span. Taruh seperti itu kedengarannya dingin. Dalam praktiknya, setiap span adalah bagian dari cerita: `POST /checkout`, `SELECT inventory`, `call payment provider`, `publish order.created`.

10Nilainya muncul ketika Anda mulai menjawab pertanyaan nyata:

11~

12- layanan eksternal mana yang melambat?

13- apakah kesalahan berasal dari versi tertentu?

14- apakah masalahnya berdampak pada semua orang atau hanya satu penyewa?

15- apakah percobaan ulang menyembunyikan batas waktu?

16- pekerjaan asinkron dimulai tetapi kemudian mati di tempat lain?

17~

18Pertanyaan-pertanyaan ini tidak dapat diselesaikan dengan `console.log` yang dilontarkan secara terburu-buru. Memang sering kali log yang ditambahkan dalam keadaan darurat membantu Anda hari ini dan menjadi kebisingan besok.

19~

20## Bagaimana cara memasukkan ini ke dalam aplikasi Node.js

21~

22Penyiapan yang paling sehat adalah sederhana: aplikasi menghasilkan telemetri, Collector memutuskan ke mana akan mengirimkannya.

23~

24```text

25Node.js app -> OpenTelemetry Collector -> backend di observability

26```

27~

28Mengapa tidak mengekspor langsung ke vendornya? Karena pada awalnya tampak lebih cepat, kemudian Anda menyadari bahwa setiap layanan memiliki konfigurasi yang berbeda, percobaan ulang yang berbeda, filter yang berbeda dan tidak ada titik pusat untuk menghapus data sensitif atau mengubah tujuan.

29~

30Collector membosankan dalam semua hal yang benar. Ia menerima OTLP, melakukan pengelompokan, dapat memfilter, dapat melakukan pengambilan sampel, dapat menambahkan atribut umum, dan dapat mengekspor ke beberapa sistem.

31~

32## Instrumentasi diri: bagus, tapi tidak cukup

33~

34Di Node.js Saya akan mulai dengan instrumentasi otomatis. Ini memberi Anda visibilitas langsung ke HTTP, kerangka kerja yang didukung, database, dan perpustakaan umum.

35~

36```bash

37npm install @opentelemetry/sdk-node \

38 @opentelemetry/auto-instrumentations-node \

39 @opentelemetry/exporter-trace-otlp-http

40```

41~

42Kemudian Anda menginisialisasi SDK sebelum aplikasi lainnya:

43~

44```typescript

45import { NodeSDK } from '@opentelemetry/sdk-node';

46import { OTLPTraceExporter } from '@opentelemetry/exporter-trace-otlp-http';

47import { getNodeAutoInstrumentations } from '@opentelemetry/auto-instrumentations-node';

48~

49const sdk = new NodeSDK({

50 traceExporter: new OTLPTraceExporter({

51 url: process.env.OTEL_EXPORTER_OTLP_TRACES_ENDPOINT,

52 }),

53 instrumentations: [getNodeAutoInstrumentations()],

54});

55~

56sdk.start();

57```

58~

59Namun, ini melihat kerangka kerjanya, bukan produk Anda. Ia mengetahui Anda membuat kueri, tetapi ia tidak mengetahui bahwa kueri tersebut berada dalam "buat pesanan" atau "perpanjang langganan". Untuk itu Anda memerlukan span manual pada titik-titik di mana dominasi diperhitungkan.

60~

61```typescript

62const span = tracer.startSpan('checkout.create_order');

63~

64try {

65 span.setAttribute('cart.items_count', input.items.length);

66 const order = await createOrder(input);

67 span.setAttribute('order.id', order.id);

68 return order;

69} catch (error) {

70 span.recordException(error as Error);

71 throw error;

72} finally {

73 span.end();

74}

75```

76~

77Saya tidak akan meletakkan manual span di mana pun. Saya akan meletakkannya di tempat, pada jam tiga pagi, saya ingin memahami apa yang terjadi tanpa membaca setengah dari basis kode.

78~

79## Tiga aturan yang menghindari banyak kekacauan

80~

81Aturan pertama: setiap layanan harus memiliki `service.name`, lingkungan dan versi. Tampaknya sepele, tetapi tanpa atribut ini, trace kurang berguna. Saat penerapan merusak sesuatu, Anda ingin memfilter berdasarkan versi dalam dua detik.

82~

83Aturan kedua: jangan memasukkan data sensitif ke dalam atribut. Email, token, muatan bilangan bulat, dan alamat tidak boleh berakhir di backend observabilitas secara tidak sengaja. Jika Anda perlu mengidentifikasi pengguna, pertimbangkan ID internal, hashing, atau kolom yang kurang sensitif.

84~

85Aturan ketiga: perhatikan kardinalitas. `user.id` sebagai atribut trace bisa masuk akal. Sebagai label metrik, hal ini dapat merusak biaya dan kinerja Anda.

86~

87## Metrik: sedikit, tapi bagus

88~

89Saya akan mulai dengan metrik yang sangat praktis:

90~

91- tarif, kesalahan dan durasi permintaan;

92- latensi ketergantungan eksternal;

93- jumlah batas waktu dan percobaan ulang;

94- kedalaman ekor;

95- durasi pekerjaan;

96- persentase kesalahan per versi.

97~

98Sisanya ditambahkan bila diperlukan. Dasbor yang penuh dengan grafik yang tidak dilihat oleh siapa pun hanyalah furnitur, bukan yang dapat diamati.

99~

100## Log: Masih berguna, tetapi tertaut

101~

102Log tidak hilang. Mereka menjadi jauh lebih berguna ketika membawa `trace_id` dan `span_id`. Jadi Anda dapat memulai dari log kesalahan dan membuka trace, atau memulai dari trace yang lambat dan hanya membaca log yang dihasilkan di jalur tersebut.

103~

104Tanpa korelasi, Anda mencari jarum. Dengan korelasi, setidaknya Anda tahu laci mana yang harus dicari.

105~

106## Daftar periksa yang akan saya gunakan sebelum mengatakan "kita terlindungi"

107~

108- trace sebenarnya melintasi beberapa layanan.

109- Log termasuk `trace_id` dan `span_id`.

110- Collector dikonfigurasi dengan batching dan batas memori.

111- Kesalahan dicatat di span.

112- Ada kebijakan pengambilan sampel.

113- Metrik telah mengontrol kardinalitas.

114- Data sensitif disaring.

115- Peringatan dimulai dari gejala pengguna, bukan grafik acak.

116~

117## Kesimpulan

118~

119OpenTelemetry tidak menyelesaikan masalah produksi dengan sendirinya. Namun cara Anda menghadapinya berubah. Daripada menambahkan log secara membabi buta, Anda mulai mengikuti jalur permintaan yang sebenarnya.

120~

121Bagi saya tanda bahwa ini berhasil adalah sederhana: ketika sesuatu terjadi, tim berhenti bertanya "di mana kita mencari?" dan mulai bertanya "mengapa lagu itu lambat?". Di sinilah observabilitas menjadi sebuah alat, bukan kumpulan dasbor.

122~

123## Sumber

124~

125- [OpenTelemetry: Overview](https://opentelemetry.io/docs/specs/otel/overview/)

126- [OpenTelemetry Collector: Configuration](https://opentelemetry.io/docs/collector/configuration/)

127- [OpenTelemetry JavaScript: Node.js getting started](https://opentelemetry.io/docs/languages/js/getting-started/nodejs/)

128- [OpenTelemetry Semantic Conventions](https://opentelemetry.io/docs/concepts/semantic-conventions/)

129~