Belajar Backstage - Observability & Tech Insights

#Pendahuluan

Episode 19 membawa Backstage ke skala besar; episode 20 ini memastikan kalian bisa melihat apa yang terjadi di dalamnya. Backstage yang melayani ribuan engineer adalah sistem yang kompleks — katalog, scaffolder, auth, dan puluhan plugin saling berhubungan. Tanpa observability, kegagalan terasa seperti tebakan. Di sini kalian mempelajari empat sinyal observability: log terstruktur, metrics dan traces OpenTelemetry, pengumpulan Prometheus, dan analytics events — lalu menutupnya dengan Tech Insights untuk memantau kesehatan entitas secara otomatis.

#Sinyal Observability di Backstage

Ada empat sinyal yang saling melengkapi, masing-masing menjawab pertanyaan berbeda:

Sinyal	Menjawab	Contoh Pemakaian
Log	Apa yang terjadi	Error plugin, proses scaffolder, request masuk
Metrics	Berapa banyak	Error rate, latency, panjang antrean task
Traces	Di mana waktu dihabiskan	Perjalanan request lintas plugin dan database
Analytics events	Apa yang dilakukan pengguna	Pencarian katalog, pembuatan service, pembacaan docs

#Structured Logging

Backstage memakai logger berbasis winston. Untuk production, log harus dalam format terstruktur — JSON — agar mudah dicari dan dikelompokkan di Loki, Elasticsearch, atau CloudWatch. Kuncinya adalah konsistensi field: level, service, plugin, timestamp, dan pesan.

Menjalankan backend dengan log JSON

LOG_FORMAT=json node packages/backend

Log terstruktur memungkinkan filter cepat: tampilkan hanya error dari plugin scaffolder, atau cari semua request dari satu pengguna tertentu. Tanpa struktur, operasional di skala besar akan tenggelam dalam teks yang tidak bisa di-query.

#OpenTelemetry: Metrics dan Traces

OpenTelemetry menjadi standar untuk mengukur performa Backstage. Dengan SDK OpenTelemetry, backend bisa mengekspor metrics dan traces ke collector lewat protokol OTLP. Arah ekspor dikendalikan lewat variabel environment standar OpenTelemetry:

Mengarahkan ekspor telemetri ke OTLP collector

OTEL_SERVICE_NAME=backstage
OTEL_EXPORTER_OTLP_ENDPOINT=http://otel-collector.internal:4318

Pemanfaatan yang umum:

Traces — ikuti perjalanan satu request dari Ingress sampai query database, termasuk task scaffolder yang berjalan lama.
Metrics — pantau request rate, error rate, dan durasi p95 per plugin.

Traces sangat membantu menemukan titik lambat: apakah waktu hilang di plugin, di query katalog, atau di pemanggilan service eksternal.

#Pengumpulan Prometheus

Prometheus bekerja dengan menarik metric dari endpoint tertentu. Backend bisa mengekspos endpoint metric yang kemudian di-scrape:

Scrape config Prometheus

scrape_configs:
  - job_name: backstage
    metrics_path: /metrics
    static_configs:
      - targets:
          - backstage-backend.internal:7007

Dengan data di Prometheus, buat alert pada kondisi yang berbahaya — misalnya error rate naik drastis atau antrean task scaffolder memanjang — sehingga tim bisa bertindak sebelum pengguna mengeluh.

#Analytics Events

Analytics menjawab pertanyaan pengalaman pengguna: berapa orang memakai scaffolder bulan ini, halaman mana yang paling banyak dikunjungi, atau template apa yang paling sering dipakai. Backstage menyediakan Analytics API, dan event dikirim ke backend analytics (misalnya GA, Mixpanel, Segment, atau PostHog) lewat module analytics:

Melacak event analytics

import { useAnalytics } from '@backstage/core-plugin-api';
 
const analytics = useAnalytics();
analytics.captureEvent('create', { entityRef: 'service:acme/payment-api' });

Analytics events menjadi bahan evaluasi adopsi — apakah golden path benar-benar dipakai — dan akan kembali dipakai di episode 22 untuk mengukur metrik DORA.

Tip

Mulailah observability dengan log terstruktur plus alert sederhana, lalu tambahkan traces dan metrics seiring kebutuhan. Tidak perlu semuanya sekaligus — sinyal yang bisa ditindaklanjuti lebih berharga daripada banyak sinyal yang tidak pernah dilihat.

#Tech Insights dan Scoring Cards

Tech Insights adalah plugin Backstage untuk memantau kualitas dan kesehatan entitas di catalog secara otomatis. Konsepnya: kumpulkan fakta tentang entitas, periksa dengan aturan, lalu beri skor. Empat komponen utamanya:

Komponen	Peran
Fact collector	Mengumpulkan fakta tentang entitas
Check	Aturan boolean yang dievaluasi dari fakta
Scoring	Skor agregat dari serangkaian checks
Health check	Penilaian kesehatan entitas, misalnya best practice dan deprecation

#Fact Collectors

Fact collectors mengambil data dari berbagai sumber — catalog, sistem eksternal, atau kode — dan menyimpannya sebagai fakta per entitas. Fakta didefinisikan lewat FactRetriever:

Mendefinisikan fact collector

export const techdocsFactRetriever: FactRetriever = {
  id: 'techdocs-fact-retriever',
  version: '0.1.0',
  entityFilter: [{ kind: 'component' }],
  handler: async (ctx) => {
    const entities = await ctx.entityClient.listEntities({ filter: ctx.entityFilter });
    return entities.map((entity) => ({
      entity: { namespace: 'default', kind: 'Component', name: entity.metadata.name },
      facts: { hasTechDocs: entity.metadata.annotations?.['backstage.io/techdocs-ref'] !== undefined },
    }));
  },
};

Fakta disimpan dan diperbarui secara berkala, menjadi bahan baku untuk checks.

#Checks

Check adalah aturan boolean yang menilai entitas dari fakta yang tersedia. Check dibuat dengan createCheck. Contoh check untuk memastikan setiap komponen punya dokumentasi:

Mendefinisikan check

export const techdocsCheck = createCheck({
  id: 'techdocs-check',
  type: 'boolean',
  name: 'Memiliki TechDocs',
  description: 'Komponen seharusnya memiliki dokumentasi TechDocs',
  factIds: ['techdocs-fact-retriever'],
  rule: async (facts) => facts.hasTechDocs === true,
});

Check bisa disusun untuk berbagai best practice: punya owner, punya deskripsi, menggunakan template golden path, atau tidak lagi memakai versi yang terdeprekasi.

#Scoring dan Health Checks atas Entitas

Beberapa check digabung menjadi scoring yang menggambarkan kesehatan keseluruhan entitas — misalnya skor kepatuhan 0 hingga 100. Health checks semacam ini sangat berguna untuk:

Best practice — memastikan entitas mengikuti standar internal, seperti ownership dan dokumentasi.
Deprecation — mendeteksi entitas yang memakai versi lama atau teknologi yang ditinggalkan.
Maturity — mengukur kematangan service sebelum memenuhi standar production.

Important

Tech Insights menilai, bukan memperbaiki. Gunakan skor untuk memprioritaskan perbaikan dan menyepakati standar, bukan untuk menghukum tim. Mulailah dengan beberapa check inti — owner, dokumentasi, dan deprecation — lalu tambahkan check baru seiring pemahaman kalian bertumbuh.

#Penutup

Pada episode 20 ini, kalian memahami observability Backstage lewat empat sinyal: structured logging untuk mencari kejadian, OpenTelemetry untuk metrics dan traces, Prometheus untuk pengumpulan dan alert, serta analytics events untuk memahami perilaku pengguna. Kalian juga mempelajari Tech Insights: fact collectors, checks, scoring, dan health checks untuk menjaga kualitas entitas.

Inti yang harus dibawa pulang:

Empat sinyal saling melengkapi — log untuk detail, metrics untuk jumlah, traces untuk perjalanan, analytics untuk pengguna.
Log harus terstruktur — JSON membuat pencarian dan pengelompokan jadi mungkin.
Tech Insights adalah penilaian berkelanjutan — fakta, checks, dan skor membuat kualitas entitas terukur.
Mulai dari yang bisa ditindaklanjuti — satu alert yang bagus lebih berguna daripada dasbor yang penuh tapi tidak pernah dibaca.

Di episode 21, kalian membawa semua pengetahuan ini ke lingkungan nyata: production deployment & adoption. Kita akan membungkus Backstage ke dalam Docker image, menggelarnya dengan Helm chart di Kubernetes, menyusun CI/CD pipeline, backup dan restore, strategi upgrade mingguan, hingga playbook adopsi untuk tim di organisasi kalian.