1 
2Kali pertama anda benar-benar memerlukan pemerhatian bukanlah apabila anda melihat papan pemuka dengan tenang. Ia adalah apabila pengguna menulis "checkout lambat", graf ralat kelihatan normal dan dalam log anda hanya menemui satu baris mesej yang terputus sambungan.
3 
4OpenTelemetry dicipta untuk mengelakkan detik itu: bukan untuk mempunyai lebih banyak grafik, tetapi untuk menyambung kepingan. Permintaan memasuki API, memanggil pangkalan data, melalui pembekal luaran, menyiarkan kerja beratur dan mungkin gagal tiga perkhidmatan kemudian. Tanpa pengesanan yang diedarkan, anda membina semula cerita itu dengan tangan. Dengan OpenTelemetry sekurang-kurangnya anda mempunyai peta.
5 
6## Intinya bukan trace, tetapi ceritanya
7 
8A trace ialah urutan span. Letakkan seperti itu bunyinya sejuk. Dalam amalan, setiap span ialah secebis cerita: `POST /checkout`, `SELECT inventory`, `call payment provider`, `publish order.created`.
9 
10Nilai itu datang apabila anda mula menjawab soalan sebenar:
11 
12- perkhidmatan luaran manakah yang semakin perlahan?
13- adakah ralat datang daripada versi tertentu?
14- adakah masalah itu menjejaskan semua orang atau hanya seorang penyewa?
15- adakah percubaan semula menyembunyikan tamat masa?
16- kerja tak segerak bermula tetapi kemudian mati di tempat lain?
17 
18Soalan-soalan ini tidak dapat diselesaikan dengan `console.log` dilemparkan dengan tergesa-gesa. Memang, selalunya log yang ditambahkan dalam kecemasan membantu anda hari ini dan menjadi bising esok.
19 
20## Bagaimanakah saya boleh meletakkan ini dalam apl Node.js
21 
22Persediaan paling sihat adalah mudah: apl menghasilkan telemetri, Collector menentukan tempat untuk menghantarnya.
23 
24```text
25Node.js app -> OpenTelemetry Collector -> backend di observability
26```
27 
28Mengapa tidak mengeksport terus kepada vendor? Kerana pada mulanya ia kelihatan lebih pantas, kemudian anda menyedari bahawa setiap perkhidmatan mempunyai konfigurasi berbeza, percubaan semula berbeza, penapis berbeza dan tiada titik pusat untuk mengalih keluar data sensitif atau menukar destinasi.
29 
30Collector membosankan dengan cara yang betul. Ia menerima OTLP, melakukan pengumpulan, boleh menapis, boleh melakukan pensampelan, boleh menambah atribut biasa dan boleh mengeksport ke berbilang sistem.
31 
32## Instrumen kendiri: baik, tetapi tidak mencukupi
33 
34Dalam Node.js saya akan mulakan dengan auto-instrumentasi. Ia memberi anda keterlihatan serta-merta ke dalam HTTP, rangka kerja yang disokong, pangkalan data dan perpustakaan biasa.
35 
36```bash
37npm install @opentelemetry/sdk-node \
38  @opentelemetry/auto-instrumentations-node \
39  @opentelemetry/exporter-trace-otlp-http
40```
41 
42Kemudian anda memulakan SDK sebelum apl yang lain:
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 
59Walau bagaimanapun, ini melihat rangka kerja, bukan produk anda. Ia mengetahui bahawa anda membuat pertanyaan, tetapi ia tidak mengetahui bahawa pertanyaan adalah dalam "buat pesanan" atau "perbaharui langganan". Untuk itu anda memerlukan span manual pada titik di mana penguasaan penting.
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-mana sahaja. Saya akan meletakkannya di mana, pada pukul tiga pagi, saya ingin memahami apa yang berlaku tanpa membaca separuh asas kod.
78 
79## Tiga peraturan yang mengelakkan banyak huru-hara
80 
81Peraturan pertama: setiap perkhidmatan mesti mempunyai `service.name`, persekitaran dan versi. Ia kelihatan remeh, tetapi tanpa atribut ini trace adalah kurang berguna. Apabila penggunaan memecahkan sesuatu, anda mahu menapis mengikut versi dalam masa dua saat.
82 
83Peraturan kedua: jangan letakkan data sensitif dalam atribut. E-mel, token, muatan integer dan alamat tidak sepatutnya berakhir di bahagian belakang yang boleh diperhatikan secara tidak sengaja. Jika anda perlu mengenal pasti pengguna, pertimbangkan ID dalaman, pencincangan atau medan yang kurang sensitif.
84 
85Peraturan ketiga: beri perhatian kepada kardinaliti. `user.id` sebagai atribut trace boleh masuk akal. Sebagai label metrik ia boleh memusnahkan kos dan prestasi anda.
86 
87## Metrik: sedikit, tetapi bagus
88 
89Saya akan mulakan dengan metrik yang sangat praktikal:
90 
91- kadar, kesilapan dan tempoh permintaan;
92- kependaman kebergantungan luar;
93- bilangan tamat masa dan percubaan semula;
94- kedalaman ekor;
95- tempoh kerja;
96- peratusan ralat setiap versi.
97 
98Selebihnya ditambah apabila diperlukan. Papan pemuka yang penuh dengan graf yang tiada siapa yang melihat adalah perabot, bukan kebolehmerhatian.
99 
100## Log: Masih berguna, tetapi dipautkan
101 
102Log tidak hilang. Mereka menjadi lebih berguna apabila mereka membawa `trace_id` dan `span_id`. Jadi anda boleh bermula dari log ralat dan buka trace, atau mulakan dari trace perlahan dan baca hanya log yang dihasilkan dalam laluan itu.
103 
104Tanpa korelasi, anda sedang mencari jarum. Dengan korelasi, sekurang-kurangnya anda tahu laci mana yang hendak dilihat.
105 
106## Senarai semak yang saya akan gunakan sebelum mengatakan "kami dilindungi"
107 
108- trace sebenarnya merentas pelbagai perkhidmatan.
109- Log termasuk `trace_id` dan `span_id`.
110- Collector dikonfigurasikan dengan batching dan had memori.
111- Ralat direkodkan dalam span.
112- Terdapat dasar pensampelan.
113- Metrik mempunyai kardinaliti yang dikawal.
114- Data sensitif ditapis.
115- Makluman bermula daripada simptom pengguna, bukan graf rawak.
116 
117## Kesimpulan
118 
119OpenTelemetry tidak menyelesaikan masalah pengeluaran dengan sendirinya. Tetapi cara anda berurusan dengan mereka berubah. Daripada menambah log secara membuta tuli, anda mula mengikut laluan sebenar permintaan.
120 
121Bagi saya tanda bahawa ia berfungsi adalah mudah: apabila sesuatu berlaku, pasukan berhenti bertanya "di mana kita mencari?" dan mula bertanya "kenapa sekeping itu lambat?". Di situlah kebolehmerhatian menjadi alat, bukan koleksi papan pemuka.
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