Managed Service for OpenTelemetry：Gunakan SkyWalking untuk melaporkan data jejak aplikasi Go

Kode Contoh

Untuk informasi lebih lanjut tentang repositori kode contoh, lihat skywalking-demo di GitHub.

Gunakan agen skywalking-go untuk melaporkan data jejak

1. Unduh agen skywalking-go.

2. Bangun agen skywalking-go.

   cd skywalking-go && make build

3. Hasilkan file executable di direktori skywalking-go/bin.

   File executable bervariasi berdasarkan sistem operasi Anda. Misalnya, gunakan skywalking-go-agent--darwin-amd64 untuk sistem operasi macOS.

   

4. Buka proyek Go dan impor modul SkyWalking ke dalam paket utama.

   Metode 1

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

   Metode 2

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

5. Konfigurasikan file config.yaml.

   Anda dapat mengonfigurasi file config.yaml dengan merujuk pada file skywalking-go/tools/go-agent/config/config.default.yaml di kode contoh.

   Perluas untuk melihat isi sampel dari file config.default.yaml

   agent:
     # Nama layanan ditampilkan di UI.
     service_name: ${SW_AGENT_NAME:Your_ApplicationName}
     # Untuk mendapatkan kunci variabel lingkungan untuk nama instance, jika tidak dapat diperoleh, nama instance akan dibuat secara otomatis.
     instance_env_name: SW_AGENT_INSTANCE_NAME
     # Laju sampling data jejak, nilai floating-point yang harus 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(s) pengecekan layanan dan layanan backend
       check_interval: ${SW_AGENT_REPORTER_GRPC_CHECK_INTERVAL:20}
       # String autentikasi untuk berkomunikasi dengan backend.
       authentication: ${SW_AGENT_REPORTER_GRPC_AUTHENTICATION:}
       # Interval(s) pengambilan konfigurasi dinamis dari backend.
       cds_fetch_interval: ${SW_AGENT_REPORTER_GRPC_CDS_FETCH_INTERVAL:20}
       tls:
         # Apakah akan mengaktifkan TLS dengan backend.
         enable: ${SW_AGENT_REPORTER_GRPC_TLS_ENABLE:false}
         # Jalur file ca.crt. Konfigurasi ini hanya bekerja saat membuka saklar TLS.
         ca_path: ${SW_AGENT_REPORTER_GRPC_TLS_CA_PATH:}
         # Jalur file client.pem. Konfigurasi ini hanya bekerja saat mTLS.
         client_key_path: ${SW_AGENT_REPORTER_GRPC_TLS_CLIENT_KEY_PATH:}
         # Jalur file client.crt. Konfigurasi ini hanya bekerja saat mTLS.
         client_cert_chain_path: ${SW_AGENT_REPORTER_GRPC_TLS_CLIENT_CERT_CHAIN_PATH:}
         # Mengontrol apakah klien memverifikasi rantai sertifikat server dan nama host.
         insecure_skip_verify: ${SW_AGENT_REPORTER_GRPC_TLS_INSECURE_SKIP_VERIFY:false}
   
   log:
     # Jenis menentukan jenis logging yang saat ini digunakan oleh sistem.
     # Agen Go akan menggunakan jenis log ini untuk menghasilkan log kustom. Ini mendukung: "auto", "logrus", atau "zap".
     # auto: Secara otomatis mengidentifikasi sumber log.
     #       Jika logrus ada di proyek, itu akan secara otomatis menggunakan logrus.
     #       Jika zap telah diinisialisasi di proyek, itu akan menggunakan kerangka zap.
     #       Secara default, itu akan menggunakan kesalahan std untuk mengeluarkan konten log.
     # logrus: Menentukan bahwa Agen harus menggunakan kerangka logrus.
     # zap: Menentukan bahwa Agen harus menggunakan kerangka zap.
     # Sistem harus sudah diinisialisasi melalui metode seperti "zap.New", "zap.NewProduction", dll.
     type: ${SW_AGENT_LOG_TYPE:auto}
     tracing:
       # Apakah akan secara otomatis mengintegrasikan informasi Jejak ke dalam log.
       enable: ${SW_AGENT_LOG_TRACING_ENABLE:true}
       # Jika informasi jejak diaktifkan, informasi jejak akan disimpan di Key saat ini di setiap log.
       key: ${SW_AGENT_LOG_TRACING_KEY:SW_CTX}
     reporter:
       # Apakah akan mengunggah log ke backend.
       enable: ${SW_AGENT_LOG_REPORTER_ENABLE:true}
       # Daftar nama bidang yang perlu ditambahkan ke label log.(beberapa dipisahkan dengan ",")
       label_keys: ${SW_AGENT_LOG_REPORTER_LABEL_KEYS:}
   
   plugin:
     # Cantumkan 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}
   

   Dua metode disediakan untuk mengonfigurasi parameter. Misalnya, untuk mengonfigurasi parameter service_name, gunakan salah satu metode berikut:

   Metode 1 (direkomendasikan): Tambahkan parameter service_name ke file config.yaml

   agent:
     service_name: ${SW_AGENT_NAME:<your_service_name>}

   Metode 2: Konfigurasikan variabel lingkungan sistem

   export SW_AGENT_NAME=<your_service_name>

   Untuk menghubungkan agen skywalking-go ke konsol Managed Service for OpenTelemetry, Anda harus mengonfigurasi parameter berikut:

   • service_name: ${SW_AGENT_NAME:Your_ApplicationName}: nama aplikasi Go.

   • backend_service: ${SW_AGENT_REPORTER_GRPC_BACKEND_SERVICE:127.0.0.1:11800}: titik akhir server.

   • authentication: ${SW_AGENT_REPORTER_GRPC_AUTHENTICATION:}: token autentikasi untuk mengakses server.

   Secara default, agen skywalking-go secara otomatis menginstrumentasi semua plugin. Untuk menonaktifkan instrumentasi otomatis untuk plugin tertentu, Anda dapat menentukan parameter excluded. Contoh:

   # Nonaktifkan instrumentasi otomatis untuk plugin SQL.
   plugin:
     excluded: ${SW_AGENT_PLUGIN_EXCLUDES:sql}
   
   # Nonaktifkan instrumentasi otomatis untuk beberapa plugin. Pisahkan plugin dengan koma (,).
   plugin:
     excluded: ${SW_AGENT_PLUGIN_EXCLUDES:sql,gorm}

6. Bangun ulang proyek.

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

   • path/to/skywalking-go-agent: jalur absolut ke file executable yang dihasilkan di Langkah 3 di bagian "Gunakan agen skywalking-go untuk melaporkan data jejak".

   • path/to/config.yaml: jalur absolut ke file config.yaml agen skywalking-go.

7. Mulai proyek. Lalu, SkyWalking melaporkan data ke konsol Managed Service for OpenTelemetry.

Lampiran

Tabel berikut menjelaskan beberapa variabel lingkungan agen skywalking-go. Nilai NULL menunjukkan bahwa tidak ada nilai default yang ditentukan.

Gunakan agen Go2Sky untuk melaporkan data jejak

1. Agen Go2Sky memungkinkan Anda menuliskan parameter langsung ke dalam proyek atau menggunakan variabel lingkungan untuk mengonfigurasi parameter.

   Tulis parameter langsung ke dalam proyek

   ### Gunakan metode reporter.WithParameter() untuk mengimpor parameter.
   report, err := reporter.NewGRPCReporter(
       <your-backend-server-address>,
       reporter.WithAuthentication(<your-auth-token>))

   Gunakan variabel lingkungan untuk mengonfigurasi parameter

   ### Agen Go2Sky dapat memperoleh nilai parameter berikut dari variabel lingkungan:
   SW_AGENT_AUTHENTICATION
   SW_AGENT_LAYER
   SW_AGENT_COLLECTOR_HEARTBEAT_PERIOD
   SW_AGENT_COLLECTOR_GET_AGENT_DYNAMIC_CONFIG_INTERVAL
   SW_AGENT_COLLECTOR_BACKEND_SERVICES
   SW_AGENT_COLLECTOR_MAX_SEND_QUEUE_SIZE
   SW_AGENT_PROCESS_STATUS_HOOK_ENABLE
   SW_AGENT_PROCESS_LABELS
   
   ### Konfigurasikan variabel lingkungan. Dalam contoh ini, macOS digunakan.
   # Metode 1: Tulis file konfigurasi variabel lingkungan. Variabel lingkungan yang dikonfigurasi dengan metode ini berlaku secara permanen.
   vim ~/.bash_profile
   export SW_AGENT_COLLECTOR_BACKEND_SERVICES=<your-collector-address>
   source ~/.bash_profile
   # Metode 2: Buka terminal dan konfigurasikan variabel lingkungan di baris perintah. Variabel lingkungan yang dikonfigurasi dengan metode ini hanya berlaku sementara dan menjadi tidak valid saat membuka terminal lain.
   export SW_AGENT_COLLECTOR_BACKEND_SERVICES=<your-collector-address>

2. Konfigurasikan parameter ServiceName untuk menentukan aplikasi.

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

3. Tambahkan panggilan balik untuk plugin Go2Sky.

   Agen Go2Sky menyediakan plugin untuk banyak pustaka. Anda perlu menambahkan panggilan balik untuk plugin ini ke kode sumber proyek Anda. Untuk informasi lebih lanjut tentang cara menambahkan panggilan balik, lihat repositori go2sky-plugins di GitHub. File README.md disediakan di folder plugin setiap plugin untuk menjelaskan cara menggunakan plugin tersebut.

   Dalam contoh ini, kerangka gin digunakan.

   1. Pergi ke folder /gin dan lihat file /gin/v3/README.md.

   2. Tambahkan panggilan balik untuk middleware: v3.Middleware(r, tracer).

      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 pelapor 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 penelusuran
      	r.Use(v3.Middleware(r, tracer))
      
      	// lakukan sesuatu
      }

4. Mulai ulang aplikasi.

Lampiran

Tabel berikut menjelaskan variabel lingkungan agen Go2Sky. Nilai NULL menunjukkan bahwa tidak ada nilai default yang ditentukan.

FAQ

• Apa yang harus saya lakukan jika pesan kesalahan yang ditunjukkan pada gambar berikut muncul saat saya menggunakan agen skywalking-go?

  

  Jika metode inject gagal, Anda dapat menggunakan metode import untuk mengimpor modul SkyWalking ke dalam paket utama.

• Mengapa konsol Managed Service for OpenTelemetry gagal menampilkan data jejak yang benar untuk pemanggilan layanan lintas proses saat saya menggunakan agen Go2Sky untuk melaporkan data jejak?

  Managed Service for OpenTelemetry menghubungkan jejak berdasarkan ID jejak. ID jejak dibawa dan ditransmisikan oleh permintaan HTTP. Jika data jejak tidak valid ditampilkan, ID jejak tidak ditransmisikan dengan benar. Dalam hal ini, Anda harus mengonfigurasi rentang yang sesuai untuk instrumentasi.

  Anda dapat memanggil dua operasi penting berikut untuk menghubungkan jejak untuk pemanggilan layanan lintas proses:

  • CreateEntrySpan: membuat rentang entri. Anda dapat memanggil operasi ini untuk mengekstrak konteks analisis jejak, termasuk ID jejak, dari permintaan HTTP.

  • CreateExitSpan: membuat rentang keluar. Anda dapat memanggil operasi ini untuk menyuntikkan konteks analisis jejak, termasuk ID jejak, ke dalam permintaan HTTP.

  // Panggil operasi CreateLocalSpan untuk membuat rentang dalam proses. 
  span, ctx, err := tracer.CreateLocalSpan(context.Background())
  subSpan, newCtx, err := tracer.CreateLocalSpan(ctx)
  
  // Untuk pemanggilan layanan lintas proses, panggil operasi CreateEntrySpan untuk mengekstrak konteks analisis jejak dari permintaan HTTP, dan panggil operasi CreateExitSpan untuk menyuntikkan konteks analisis jejak ke dalam permintaan HTTP. 
  span, ctx, err := tracer.CreateEntrySpan(r.Context(), "/api/login", func(key string) (string, error) {
      return r.Header.Get(key), nil
  })
  span, err := tracer.CreateExitSpan(req.Context(), "/service/validate", "tomcat-service:8080", func(key, value string) error {
  		req.Header.Set(key, value)
  		return nil
  })

  Untuk pemanggilan layservice lintas proses, ID jejak harus ditransmisikan lintas proses untuk menghubungkan jejak. Oleh karena itu, Anda harus memanggil operasi sebelumnya untuk menyuntikkan konteks analisis jejak ke dalam permintaan HTTP yang ditransmisikan lintas proses.

Referensi

• Situs Resmi Apache SkyWalking

• Repositori skywalking-go di GitHub

• Dokumentasi Resmi skywalking-go

• Repositori Go2Sky di GitHub

• Repositori go2sky-plugins di GitHub