---
title: 'Instrumentasi'
description: "Library ini menyertakan instrumentasi pewaktuan bawaan untuk mengidentifikasi hambatan (bottleneck) performa. Instrumentasi ini memiliki beban nol (zero overhead) saat dinonaktifkan."
navigation:
  icon: 'i-ph-book-open'
seo:
  title: 'Instrumentasi'
  description: "Library ini menyertakan instrumentasi pewaktuan bawaan untuk mengidentifikasi hambatan (bottleneck) performa. Instrumentasi ini memiliki beban nol (zero overhead) saat dinonaktifkan."
---

## Gambaran Umum


## Mulai Cepat

### Aktifkan Pewaktuan (Timing)

Atur variabel lingkungan `JSONEVAL_TIMING`:

```bash
# Linux/macOS
JSONEVAL_TIMING=1 cargo run --release --example basic -- zcc

# Windows PowerShell
$env:JSONEVAL_TIMING=1; cargo run --release --example basic -- zcc
```

### Contoh Output

```
📊 Ringkasan Waktu (JSONEVAL_TIMING aktif)
============================================================
parse schema JSON                       84.96ms
parse context JSON                       3.34µs
parse data JSON                         28.61µs
create instance struct                  83.82ms
parse_schema                           315.57ms
JSONEval::new() [total]                538.59ms
  parse data                            74.26µs
  parse context                          0.76µs
  replace_data_and_context              11.09µs
  purge_cache                           76.16µs
    process batches                    327.53ms
      evaluate_options_templates         5.47µs
      evaluate rules+others            577.61µs
    evaluate_others()                   583.42µs
  evaluate_internal() [total]          328.16ms
evaluate() [total]                     328.34ms
    resolve_layout_elements              0.93ms
    propagate_parent_conditions          0.81ms
  resolve_layout_internal()              1.74ms
get_evaluated_schema()                  11.04ms
============================================================
TOTAL                                    2.42s
```


## Fungsi API

### Bersihkan Data Waktu (Clear Timing Data)

::code-group
  ```rust [Rust]
  use json_eval_rs;

  // Bersihkan data waktu di antara skenario
  json_eval_rs::clear_timing_data();
  ```
  ```csharp [C#]
  // Instrumentasi pewaktuan adalah fitur debugging Rust asli.
  // Fitur ini menulis langsung ke stderr saat JSONEVAL_TIMING=1 disetel.
  ```
  ```typescript [React Native]
  // Instrumentasi pewaktuan adalah fitur debugging Rust asli.
  // Fitur ini menulis langsung ke stderr saat JSONEVAL_TIMING=1 disetel.
  ```
  ```typescript [Web / NodeJS]
  // Instrumentasi pewaktuan adalah fitur debugging Rust asli.
  // Fitur ini menulis langsung ke stderr saat JSONEVAL_TIMING=1 disetel.
  ```
::

### Cetak Ringkasan Waktu (Print Timing Summary)

::code-group
  ```rust [Rust]
  use json_eval_rs;

  // Cetak rincian waktu yang mendetail
  json_eval_rs::print_timing_summary();
  ```
  ```csharp [C#]
  // Instrumentasi pewaktuan adalah fitur debugging Rust asli.
  // Setel variabel lingkungan JSONEVAL_TIMING=1 untuk melihat output di stderr.
  ```
  ```typescript [React Native]
  // Instrumentasi pewaktuan adalah fitur debugging Rust asli.
  // Setel variabel lingkungan JSONEVAL_TIMING=1 untuk melihat output di stderr.
  ```
  ```typescript [Web / NodeJS]
  // Instrumentasi pewaktuan adalah fitur debugging Rust asli.
  // Setel variabel lingkungan JSONEVAL_TIMING=1 untuk melihat output di stderr.
  ```
::

### Contoh Lengkap

::code-group
  ```rust [Rust]
  use json_eval_rs::JSONEval;

  fn main() {
      // Bersihkan data waktu sebelumnya
      json_eval_rs::clear_timing_data();
      
      // Kode Anda di sini
      let mut eval = JSONEval::new(schema, None, Some(data))?;
      eval.evaluate(data, None)?;
      let result = eval.get_evaluated_schema(false);
      
      // Cetak ringkasan waktu (hanya muncul jika JSONEVAL_TIMING=1)
      json_eval_rs::print_timing_summary();
  }
  ```
  ```csharp [C#]
  // Instrumentasi pewaktuan adalah fitur debugging Rust asli.
  // Penggunaan standar memicu log waktu native secara otomatis jika JSONEVAL_TIMING=1 dikonfigurasi di lingkungan.
  ```
  ```typescript [React Native]
  // Instrumentasi pewaktuan adalah fitur debugging Rust asli.
  // Penggunaan standar memicu log waktu native secara otomatis jika JSONEVAL_TIMING=1 dikonfigurasi di lingkungan.
  ```
  ```typescript [Web / NodeJS]
  // Instrumentasi pewaktuan adalah fitur debugging Rust asli.
  // Penggunaan standar memicu log waktu native secara otomatis jika JSONEVAL_TIMING=1 dikonfigurasi di lingkungan.
  ```
::

## Metode yang Diinstrumentasi

Metode-metode berikut telah dilengkapi dengan instrumentasi pewaktuan:

### Inisialisasi
- `JSONEval::new()` - Total waktu inisialisasi
  - `parse schema JSON` - Pengolahan JSON schema
  - `parse context JSON` - Pengolahan JSON konteks
  - `parse data JSON` - Pengolahan JSON data
  - `create instance struct` - Pembuatan struct instance
  - `parse_schema` - Analisis dan kompilasi schema

### Evaluasi
- `evaluate()` - Total waktu evaluasi
  - `parse data` - Pengolahan data
  - `parse context` - Pengolahan konteks
  - `replace_data_and_context` - Penggantian data
  - `purge_cache` - Invalidation cache
  - `evaluate_internal()` - Logika inti evaluasi
    - `process batches` - Pemrosesan batch
    - `evaluate_others()` - Evaluasi lainnya
      - `evaluate_options_templates` - Evaluasi template opsi
      - `evaluate rules+others` - Evaluasi aturan

### Finalisasi
- `get_evaluated_schema()` - Pengambilan schema
  - `resolve_layout_internal()` - Resolusi layout
    - `resolve_layout_elements` - Resolusi elemen
    - `propagate_parent_conditions` - Propagasi kondisi induk


## Karakteristik Performa

### Beban Nol Saat Dinonaktifkan (Zero Overhead)

Saat `JSONEVAL_TIMING` tidak diatur:
- Semua pengecekan waktu akan dikompilasi menjadi satu pengecekan boolean sederhana (`is_timing_enabled()`).
- Optimizer akan melakukan inlining dan menghapus kode yang tidak berjalan (dead code).
- **Tidak ada dampak performa yang bisa diukur.**

### Penyimpanan Lokal Thread (Thread-Local Storage)

Data waktu disimpan di penyimpanan lokal thread:
- Setiap thread memiliki data waktunya sendiri.
- Tidak ada beban sinkronisasi antar thread.
- Aman untuk aplikasi multi-thread.

### Format Output

Output waktu ditulis ke `stderr` menggunakan `eprintln!`:
- Tidak mengganggu output normal (`stdout`).
- Dapat dialihkan secara terpisah: `2>timing.log`.
- Indentasi menunjukkan hierarki panggilan.

## Menafsirkan Hasil

### Memahami Indentasi

```
JSONEval::new() [total]      500ms    ← Metode tingkat atas
  parse_schema               300ms    ← Sub-operasi (2 spasi)
    process batches          200ms    ← Operasi bersarang (4 spasi)
```

### Mengidentifikasi Hambatan (Bottleneck)

1. Cari metode dengan waktu absolut yang tinggi (>100ms).
2. Cari metode dengan waktu relatif yang tinggi (>20% dari total).
3. Periksa operasi bersarang untuk peluang optimasi.

### Contoh Analisis

```
parse_schema                315ms  ← HAMBATAN UTAMA (35%)
process batches             327ms  ← HAMBATAN SEKUNDER (37%)
resolve_layout                2ms  ← Tidak perlu dikhawatirkan (<1%)
```

## Integrasi dengan Alat Eksternal

### Cargo Flamegraph

Gabungkan instrumentasi pewaktuan dengan flamegraph:

```bash
# Instal flamegraph
cargo install flamegraph

# Buat flamegraph dengan pewaktuan
JSONEVAL_TIMING=1 cargo flamegraph --example basic -- zcc
```

### Criterion Benchmarks

Gunakan data waktu untuk memvalidasi peningkatan benchmark:

```rust
use criterion::{black_box, criterion_group, criterion_main, Criterion};
use json_eval_rs::JSONEval;

fn bench_evaluate(c: &mut Criterion) {
    json_eval_rs::clear_timing_data();
    
    c.bench_function("evaluate zcc", |b| {
        b.iter(|| {
            let mut eval = JSONEval::new(schema, None, Some(data)).unwrap();
            eval.evaluate(data, None).unwrap();
            black_box(eval.get_evaluated_schema(false))
        });
    });
    
    json_eval_rs::print_timing_summary();
}
```

## Pemecahan Masalah (Troubleshooting)

### Tidak Ada Output Waktu

**Masalah**: Menjalankan dengan `JSONEVAL_TIMING=1` tetapi tidak ada output yang muncul.

**Solusi**:
1. Pastikan Anda memanggil `print_timing_summary()`.
2. Pastikan kode pewaktuan benar-benar dijalankan.
3. Pastikan stderr tidak dialihkan (redirect).

### Nilai Waktu Tidak Sesuai Harapan

**Masalah**: Nilai waktu terlihat terlalu tinggi atau terlalu rendah.

**Penyebab**:
1. Build debug vs build release (gunakan `--release`).
2. Cold start vs warm start (pemuatan pertama lebih lambat).
3. Proses background yang mempengaruhi CPU.
4. Efek caching dari sistem file.

**Praktik Terbaik**: Jalankan beberapa kali dan ambil rata-ratanya:
```bash
for i in {1..5}; do JSONEVAL_TIMING=1 cargo run --release --example basic -- zcc; done
```

### Penggunaan Memori

**Masalah**: Khawatir tentang beban memori.

**Fakta**:
- Data waktu menyimpan tuple `(String, Duration)`.
- Skenario tipikal: <100 entri = ~10KB.
- Otomatis dibersihkan dengan `clear_timing_data()`.
- Thread-local = terisolasi per thread.

## Berkontribusi

Untuk menambahkan pewaktuan ke metode baru:

```rust
fn my_method(&self) -> Result<Value, String> {
    time_block!("my_method", {
        // Kode Anda di sini
        let result = expensive_operation();
        result
    })
}
```

Konvensi penamaan:
- Metode tingkat atas: `method_name()`
- Sub-operasi: `  sub_operation` (2 spasi)
- Operasi bersarang: `    nested_op` (4 spasi)

## Lihat Juga

- [Cargo Book - Profiling](https://doc.rust-lang.org/cargo/guide/build-cache.html)
- [Rust Performance Book](https://nnethercote.github.io/perf-book/)
