Belajar OpenTelemetry - Resource & Semantic Conventions

#Pendahuluan

Setelah tiga episode menggarap traces, metrics, dan logs, sekarang kita naik satu level ke metadata yang menyatukan semuanya: Resource dan Semantic Conventions. Dua topik ini terlihat administratif, tetapi justru menentukan apakah observability kalian bisa diandalkan atau berantakan.

Alasannya sederhana: telemetry yang tidak beridentitas adalah kebisingan. Tanpa Resource yang benar, kalian tidak bisa membedakan traffic staging vs produksi. Tanpa semantic conventions, setiap tim menamai attribute dengan caranya sendiri — dan dashboard lintas tim jadi mustahil dibaca.

#Resource: Identitas Data Telemetry

Resource adalah sekumpulan atribut yang mendeskripsikan entitas yang menghasilkan telemetry — bukan permintaan individual. Resource melekat pada setiap span, metric point, dan log record yang dikirim SDK.

Atribut Resource yang paling penting:

#Mengapa service.name Begitu Kritis

Semua backend observability mengelompokkan data berdasarkan service.name. Jika nama ini salah atau tidak konsisten, telemetry tersebar ke service palsu dan dashboard patah. Kesalahan klasik: memakai nama host (my-laptop-2) atau nama pod yang berubah tiap deploy sebagai service.name. Nama service harus stabil dan mewakili unit bisnis logis, bukan instance.

from opentelemetry.sdk.resources import Resource, SERVICE_NAME
 
resource = Resource.create({
    SERVICE_NAME: "payment-service",
    "service.version": "1.4.0",
    "deployment.environment": "production",
    "cloud.provider": "aws",
    "cloud.region": "ap-southeast-1",
})

#Deteksi Otomatis Resource

Alih-alih mengisi manual, SDK bisa mendeteksi Resource dari lingkungan: atribut host dari OS, atribut cloud dari metadata provider, atribut Kubernetes dari variabel lingkungan pod. Di Python, pasang detector resmi:

pip install opentelemetry-sdk-extension-aws \
            opentelemetry-resourcedetector-gcp \
            opentelemetry-resourcedetector-kubernetes

from opentelemetry.sdk.resources import get_aggregated_resources
from opentelemetry.sdk.resources import Resource
 
detected = get_aggregated_resources()          # deteksi otomatis
manual = Resource.create({SERVICE_NAME: "payment-service"})
resource = manual.merge(detected)              # manual menimpa detected

#Semantic Conventions: Bahasa Bersama

Semantic Conventions (semconv) adalah spesifikasi OTel yang mendefinisikan penamaan standar untuk span names, attribute keys, dan metric names. Tujuannya tunggal: agar data dari bahasa, framework, dan vendor berbeda dapat dibandingkan di dashboard yang sama.

#Aturan Penamaan Umum

• Lowercase dengan titik sebagai pemisah namespace: http.request.method, db.system, messaging.system.
• Namespace dulu, konsep kedua — http.response.status_code bukan status_code.
• Konsisten antar teknologi — db.system dipakai untuk PostgreSQL, MySQL, dan MongoDB sekaligus.
• Unit tidak di nama metric — durasi ditulis http.server.request.duration (unit s), bukan http.server.request.duration.ms.

#Contoh Standar untuk HTTP

Span untuk request server harus membawa attribute HTTP standar:

with tracer.start_as_current_span("GET /products") as span:
    span.set_attribute("http.request.method", "GET")
    span.set_attribute("http.route", "/products/{id}")
    span.set_attribute("http.response.status_code", 200)
    span.set_attribute("server.address", "api.example.com")
    span.set_attribute("url.path", "/products/42")

Perhatikan: method memakai http.request.method, status http.response.status_code — bukan method atau code tanpa namespace. Inilah detail yang membuat data lintas tim konsisten.

#Metric Names Standar

Metric juga punya konvensi, misalnya:

• http.server.request.duration — histogram latensi request server (unit s).
• http.server.active_requests — updown counter request aktif.
• db.client.operation.duration — durasi operasi database.
• process.runtime.cpu.time — pemakaian CPU runtime.

Saat kalian membuat metric kustom, ikuti pola namespace yang sama — misalnya <domain>.<operation>.<quantity> — agar tidak keluar dari bahasa bersama.

#Auto-Instrumentation Sudah Mengikuti Semconv

Berita baiknya: auto-instrumentation dan library resmi OTel sudah mematuhi semconv secara default. Tugas kalian bukan menghafal ratusan attribute, melainkan mengikuti pola yang sudah ada saat menulis manual instrumentation, dan memeriksa registry (opentelemetry.io/docs/specs/semconv/) saat ragu.

#Kesalahan Umum Resource & Semconv

#Penutup

Pada episode 7 ini, kalian telah memahami dua fondasi metadata OTel.

Inti yang harus dibawa pulang:

• Resource memberi identitas entitas penghasil telemetry; service.name wajib stabil dan bermakna.
• Resource sebaiknya dideteksi otomatis dan di-merge dengan atribut manual.
• Semantic conventions menyediakan bahasa bersama: namespace.konsep, lowercase bertitik.
• Auto-instrumentation sudah mengikuti semconv; kewajiban kalian adalah mengikuti polanya di instrumentasi manual.

Di episode 8 selanjutnya, kita akan membahas OTLP protocol & export ke backend — encoding protobuf, kompresi, port gRPC 4317 dan HTTP 4318, versi stabil OTLP v1.10.0, serta konfigurasi exporter dengan retry/backoff ke Jaeger dan collector. Sampai jumpa di episode 8!