Application Real-Time Monitoring Service:Laporkan data jejak Go melalui SkyWalking

Langkah 1: Dapatkan titik akhir SkyWalking

1. Masuk ke Konsol Managed Service for OpenTelemetry.

2. Di panel navigasi kiri, klik Cluster Configurations. Pada halaman yang muncul, klik tab Access point information.

3. Di bilah navigasi atas, pilih wilayah. Di bagian Cluster Information, aktifkan Show Token.

4. Atur parameter Client ke SkyWalking.

5. Salin titik akhir dari kolom Related Information.

Langkah 2: Bangun binari agen

Kloning dan bangun agen skywalking-go:

git clone https://github.com/apache/skywalking-go.git
cd skywalking-go && make build

Proses pembangunan menghasilkan file eksekusi di direktori skywalking-go/bin/. Nama file bervariasi tergantung OS—misalnya, skywalking-go-agent--darwin-amd64 pada macOS.

Langkah 3: Tambahkan modul SkyWalking ke proyek Anda

Pilih salah satu metode berikut:

package main

import (
	_ "github.com/apache/skywalking-go"
)

skywalking-go/bin/skywalking-go-agent--darwin-amd64 -inject path/to/your-project

Langkah 4: Konfigurasikan agen

Buat file config.yaml dengan setidaknya tiga parameter berikut:

agent:
  service_name: ${SW_AGENT_NAME:<your-service-name>}

reporter:
  grpc:
    backend_service: ${SW_AGENT_REPORTER_GRPC_BACKEND_SERVICE:<your-skywalking-endpoint>}
    authentication: ${SW_AGENT_REPORTER_GRPC_AUTHENTICATION:<your-auth-token>}

Ganti placeholder dengan nilai Anda:

Tetapkan nilai-nilai ini langsung di config.yaml (disarankan) atau melalui variabel lingkungan:

export SW_AGENT_NAME=my-go-service
export SW_AGENT_REPORTER_GRPC_BACKEND_SERVICE=xxx.api.aliyuncs.com:11800
export SW_AGENT_REPORTER_GRPC_AUTHENTICATION=abcdef123456

plugin:
  # Nonaktifkan satu plugin
  excluded: ${SW_AGENT_PLUGIN_EXCLUDES:sql}

  # Nonaktifkan beberapa plugin (dipisahkan koma)
  # excluded: ${SW_AGENT_PLUGIN_EXCLUDES:sql,gorm}

agent:
  # Nama layanan ditampilkan di UI.
  service_name: ${SW_AGENT_NAME:Your_ApplicationName}
  # Untuk mendapatkan kunci variabel lingkungan untuk nama instans, jika tidak dapat diperoleh, nama instans akan dibuat secara otomatis.
  instance_env_name: SW_AGENT_INSTANCE_NAME
  # Laju pengambilan sampel data jejak, yaitu nilai floating-point antara 0 dan 1.
  sampler: ${SW_AGENT_SAMPLE:1}
  meter:
    # Interval pengumpulan metrik, dalam detik.
    collect_interval: ${SW_AGENT_METER_COLLECT_INTERVAL:20}

reporter:
  grpc:
    # Alamat server gRPC dari layanan backend.
    backend_service: ${SW_AGENT_REPORTER_GRPC_BACKEND_SERVICE:127.0.0.1:11800}
    # Jumlah maksimum segmen untuk melaporkan data jejak.
    max_send_queue: ${SW_AGENT_REPORTER_GRPC_MAX_SEND_QUEUE:5000}
    # Interval (detik) pemeriksaan layanan dan layanan backend
    check_interval: ${SW_AGENT_REPORTER_GRPC_CHECK_INTERVAL:20}
    # String otentikasi untuk berkomunikasi dengan backend.
    authentication: ${SW_AGENT_REPORTER_GRPC_AUTHENTICATION:}
    # Interval (detik) pengambilan konfigurasi dinamis dari backend.
    cds_fetch_interval: ${SW_AGENT_REPORTER_GRPC_CDS_FETCH_INTERVAL:20}
    tls:
      # Apakah TLS diaktifkan dengan backend.
      enable: ${SW_AGENT_REPORTER_GRPC_TLS_ENABLE:false}
      # Jalur file ca.crt. Konfigurasi ini hanya berlaku saat sakelar TLS diaktifkan.
      ca_path: ${SW_AGENT_REPORTER_GRPC_TLS_CA_PATH:}
      # Jalur file client.pem. Konfigurasi ini hanya berlaku saat mTLS.
      client_key_path: ${SW_AGENT_REPORTER_GRPC_TLS_CLIENT_KEY_PATH:}
      # Jalur file client.crt. Konfigurasi ini hanya berlaku saat mTLS.
      client_cert_chain_path: ${SW_AGENT_REPORTER_GRPC_TLS_CLIENT_CERT_CHAIN_PATH:}
      # Mengontrol apakah klien memverifikasi rantai sertifikat dan nama host server.
      insecure_skip_verify: ${SW_AGENT_REPORTER_GRPC_TLS_INSECURE_SKIP_VERIFY:false}

log:
  # Jenis menentukan jenis pencatatan log yang digunakan sistem saat ini.
  # Agen Go akan menggunakan jenis log ini untuk menghasilkan log kustom. Mendukung: "auto", "logrus", atau "zap".
  # auto: Secara otomatis mengidentifikasi sumber log.
  #       Jika logrus ada di proyek, akan secara otomatis menggunakan logrus.
  #       Jika zap telah diinisialisasi di proyek, akan menggunakan framework zap.
  #       Secara default, akan menggunakan std errors untuk mengeluarkan konten log.
  # logrus: Menentukan bahwa Agen harus menggunakan framework logrus.
  # zap: Menentukan bahwa Agen harus menggunakan framework zap.
  # Sistem harus sudah diinisialisasi melalui metode seperti "zap.New", "zap.NewProduction", dll.
  type: ${SW_AGENT_LOG_TYPE:auto}
  tracing:
    # Apakah informasi Tracing secara otomatis diintegrasikan ke dalam log.
    enable: ${SW_AGENT_LOG_TRACING_ENABLE:true}
    # Jika informasi tracing diaktifkan, informasi tracing akan disimpan di Key saat ini di setiap log.
    key: ${SW_AGENT_LOG_TRACING_KEY:SW_CTX}
  reporter:
    # Apakah log diunggah ke backend.
    enable: ${SW_AGENT_LOG_REPORTER_ENABLE:true}
    # Daftar nama bidang yang perlu ditambahkan ke label log. (dipisahkan dengan ",")
    label_keys: ${SW_AGENT_LOG_REPORTER_LABEL_KEYS:}

plugin:
  # Daftar nama plugin yang dikecualikan, beberapa nama plugin harus dipisahkan dengan ","
  # CATATAN: Parameter ini hanya berlaku selama fase kompilasi.
  excluded: ${SW_AGENT_PLUGIN_EXCLUDES:}
  config:
    http:
      # Kumpulkan parameter permintaan HTTP di sisi server
      server_collect_parameters: ${SW_AGENT_PLUGIN_CONFIG_HTTP_SERVER_COLLECT_PARAMETERS:false}
    mongo:
      # Kumpulkan pernyataan permintaan MongoDB
      collect_statement: ${SW_AGENT_PLUGIN_CONFIG_MONGO_COLLECT_STATEMENT:false}
    sql:
      # Kumpulkan parameter permintaan SQL
      collect_parameter: ${SW_AGENT_PLUGIN_CONFIG_SQL_COLLECT_PARAMETER:false}

Langkah 5: Bangun ulang proyek Anda

Kompilasi dengan flag -toolexec yang mengarah ke binari agen dan file konfigurasi Anda:

sudo go build -toolexec "path/to/skywalking-go-agent -config path/to/config.yaml" -a

• path/to/skywalking-go-agent – jalur mutlak ke eksekusi yang dibangun di Langkah 2

• path/to/config.yaml – jalur mutlak ke file konfigurasi yang dibuat di Langkah 4

Langkah 6: Jalankan aplikasi Anda dan verifikasi

Jalankan binari yang telah dikompilasi. Agen secara otomatis menginstrumentasi semua plugin yang didukung dan mulai melaporkan jejak melalui gRPC.

Setelah Anda menjalankan proyek, SkyWalking melaporkan data ke Konsol Managed Service for OpenTelemetry.

Referensi variabel lingkungan

Plugin yang didukung

Agen skywalking-go secara otomatis menginstrumentasi pustaka-pustaka berikut saat kompilasi. Tidak diperlukan instalasi per pustaka.

Langkah 1: Siapkan reporter

Konfigurasikan reporter gRPC dengan mengkode keras parameter atau mengatur variabel lingkungan.

report, err := reporter.NewGRPCReporter(
    "<your-backend-server-address>",
    reporter.WithAuthentication("<your-auth-token>"))

# Permanen -- tambahkan ke profil shell Anda
export SW_AGENT_COLLECTOR_BACKEND_SERVICES=<your-collector-address>
export SW_AGENT_AUTHENTICATION=<your-auth-token>

# Lalu jalankan aplikasi Anda (agen membaca variabel ini secara otomatis)

Langkah 2: Buat tracer

ServiceName := "<your-service-name>"
tracer, err := go2sky.NewTracer(ServiceName, go2sky.WithReporter(report))

Langkah 3: Tambahkan hook plugin

Go2Sky memerlukan hook untuk setiap pustaka yang diinstrumentasi. Lihat repositori go2sky-plugins di GitHub — setiap folder plugin berisi README dengan instruksi integrasi.

Contoh – framework gin:

package main

import (
	"log"

	"github.com/SkyAPM/go2sky"
	v3 "github.com/SkyAPM/go2sky-plugins/gin/v3"
	"github.com/SkyAPM/go2sky/reporter"
	"github.com/gin-gonic/gin"
)

func main() {
	// Gunakan reporter gRPC untuk produksi
	re, err := reporter.NewLogReporter()
	if err != nil {
		log.Fatalf("new reporter error %v \n", err)
	}
	defer re.Close()

	tracer, err := go2sky.NewTracer("gin-server", go2sky.WithReporter(re))
	if err != nil {
		log.Fatalf("create tracer error %v \n", err)
	}

	gin.SetMode(gin.ReleaseMode)
	r := gin.New()

	// Gunakan middleware go2sky dengan pelacakan
	r.Use(v3.Middleware(r, tracer))

	// Tambahkan rute Anda di sini
}

Langkah 4: Restart aplikasi

Setelah menambahkan hook, restart aplikasi Anda. Jejak mulai mengalir ke Konsol Managed Service for OpenTelemetry.

Pustaka plugin yang didukung

Setiap plugin memerlukan instalasi terpisah melalui go get:

Referensi variabel lingkungan

Apa yang harus saya lakukan jika perintah inject skywalking-go gagal?

Jika metode -inject gagal, tambahkan impor SkyWalking langsung di paket utama Anda sebagai gantinya:

import _ "github.com/apache/skywalking-go"

Lalu bangun ulang dengan -toolexec seperti yang dijelaskan di Langkah 5.

Mengapa konsol menampilkan jejak terputus untuk panggilan lintas-proses dengan Go2Sky?

Managed Service for OpenTelemetry mengorelasikan rentang berdasarkan ID jejak yang dibawa dalam Header HTTP. Jika jejak tampak terputus di berbagai layanan, konteks jejak tidak tersebar dengan benar.

Untuk memperbaikinya, buat rentang masuk dan keluar yang menyebarkan konteks jejak melintasi batas HTTP:

// CreateEntrySpan -- ekstrak konteks jejak dari permintaan HTTP masuk
span, ctx, err := tracer.CreateEntrySpan(r.Context(), "/api/login", func(key string) (string, error) {
    return r.Header.Get(key), nil
})

// CreateExitSpan -- suntikkan konteks jejak ke permintaan HTTP keluar
span, err := tracer.CreateExitSpan(req.Context(), "/service/validate", "tomcat-service:8080", func(key, value string) error {
    req.Header.Set(key, value)
    return nil
})

Untuk rentang dalam proses (tanpa batas jaringan), gunakan CreateLocalSpan:

span, ctx, err := tracer.CreateLocalSpan(context.Background())
subSpan, newCtx, err := tracer.CreateLocalSpan(ctx)

Setiap panggilan HTTP yang melintasi batas proses harus membawa konteks jejak. Tanpa CreateEntrySpan dan CreateExitSpan di setiap batas, layanan downstream akan memulai jejak baru yang terputus.