Mengirim data pelacakan ke AWS X-Ray

Anda dapat mengirim data pelacakan ke X-Ray dalam bentuk dokumen segmen. Sebuah dokumen segmen adalah string berformat JSON yang berisi informasi tentang pekerjaan yang dilakukan aplikasi Anda dalam pelayanan permintaan. Aplikasi Anda dapat mencatat data tentang pekerjaan yang dilakukannya sendiri di segmen, atau pekerjaan yang menggunakan layanan hilir dan sumber daya di subsegment.

Segmen mencatat informasi tentang pekerjaan yang dilakukan aplikasi Anda. Segmen, setidaknya, mencatat waktu yang dihabiskan untuk tugas, nama, dan dua ID. ID pelacakan melacak permintaan saat perjalanan antara layanan. ID segmen melacak pekerjaan yang dilakukan untuk permintaan oleh satu layanan.

{
  "name" : "Scorekeep",
  "id" : "70de5b6f19ff9a0a",
  "start_time" : 1.478293361271E9,
  "trace_id" : "1-581cf771-a006649127e371903a2de979",
  "end_time" : 1.478293361449E9
}

Ketika permintaan diterima, Anda dapat mengirim segmen yang sedang berlangsung sebagai placeholder sampai permintaan selesai.

{
  "name" : "Scorekeep",
  "id" : "70de5b6f19ff9a0b",
  "start_time" : 1.478293361271E9,
  "trace_id" : "1-581cf771-a006649127e371903a2de979",
  “in_progress”: true
}

Anda dapat mengirim segmen ke X-Ray secara langsung, dengan PutTraceSegments, atau melalui daemon X-Ray.

Sebagian besar aplikasi memanggil layanan lain atau mengakses sumber daya dengan AWS SDK. Mencatat informasi tentang panggilan hilir di subsegmen. X-Ray menggunakan subsegmen untuk mengidentifikasi layanan hilir yang tidak mengirim segmen dan membuat entri untuk mereka di grafik layanan.

Sebuah subsegmen dapat ditanamkan dalam dokumen segmen penuh, atau dikirim secara terpisah. Kirim subsegmen secara terpisah untuk melacak panggilan hilir secara asinkron untuk permintaan yang berlangsung lama, atau untuk menghindari melebihi ukuran dokumen segmen maksimum (64 kB).

{
  "name" : "www2.example.com",
  "id" : "70de5b6f19ff9a0c",
  "start_time" : 1.478293361271E9,
  "trace_id" : "1-581cf771-a006649127e371903a2de979"
  “end_time” : 1.478293361449E9,
  “type” : “subsegment”,
  “parent_id” : “70de5b6f19ff9a0b”
}

Untuk informasi selengkapnya tentang bidang dan nilai yang dapat Anda sertakan dalam segmen dan subsegmen, lihat AWS X-Ray dokumen segmen.

Menghasilkan ID pelacakan

Untuk mengirim data ke X-Ray, Anda harus menghasilkan ID jejak unik untuk setiap permintaan.

Anda dapat menulis skrip untuk menghasilkan ID jejak X-Ray untuk pengujian. Berikut ini adalah dua contoh.

Python

import time
import os
import binascii

START_TIME = time.time()
HEX=hex(int(START_TIME))[2:]
TRACE_ID="1-{}-{}".format(HEX, binascii.hexlify(os.urandom(12)).decode('utf-8'))

Bash

START_TIME=$(date +%s)
HEX_TIME=$(printf '%x\n' $START_TIME)
GUID=$(dd if=/dev/random bs=12 count=1 2>/dev/null | od -An -tx1 | tr -d ' \t\n')
TRACE_ID="1-$HEX_TIME-$GUID"

Lihat aplikasi sampel Scorekeep untuk skrip yang membuat ID pelacakan dan mengirim segmen ke daemon X-Ray.

Menggunakan PutTraceSegments

Anda dapat mengunggah dokumen segmen dengan API PutTraceSegments. API memiliki parameter tunggal , TraceSegmentDocuments, yang mengambil daftar dokumen segmen JSON.

Dengan AWS CLI, gunakan perintah aws xray put-trace-segments untuk mengirim dokumen segmen langsung ke X-Ray.

$ DOC='{"trace_id": "1-5960082b-ab52431b496add878434aa25", "id": "6226467e3f845502", "start_time": 1498082657.37518, "end_time": 1498082695.4042, "name": "test.elasticbeanstalk.com"}'
$ aws xray put-trace-segments --trace-segment-documents "$DOC"
{
    "UnprocessedTraceSegments": []
}

Output mencantumkan segmen yang gagal diproses. Misalnya, jika tanggal di ID pelacakan terlalu lama di masa lalu, Anda melihat kesalahan seperti berikut ini.

{
    "UnprocessedTraceSegments": [
        {
            "ErrorCode": "InvalidTraceId",
            "Message": "Invalid segment. ErrorCode: InvalidTraceId",
            "Id": "6226467e3f845502"
        }
    ]
}

Anda dapat melewati beberapa dokumen segmen pada saat yang sama, dipisahkan oleh spasi.

$ aws xray put-trace-segments --trace-segment-documents "$DOC1" "$DOC2"

Mengirim dokumen segmen ke daemon X-Ray

Daripada mengirim dokumen segmen ke API X-Ray, Anda dapat mengirim segmen dan subsegmen ke daemon X-Ray, yang akan menyangga dokumen tersebut dan mengunggahnya ke API X-Ray dalam batch. X-Ray SDK mengirimkan dokumen segmen ke daemon untuk menghindari panggilan ke AWS secara langsung.

Kirim segmen di JSON melalui UDP port 2000, diawali dengan header daemon, {"format": "json", "version": 1}\n

{"format": "json", "version": 1}\n{"trace_id": "1-5759e988-bd862e3fe1be46a994272793", "id": "defdfd9912dc5a56", "start_time": 1461096053.37518, "end_time": 1461096053.4042, "name": "test.elasticbeanstalk.com"}

Di Linux, Anda dapat mengirim dokumen segmen ke daemon dari terminal Bash. Simpan header dan segmen dokumen ke file teks dan alirkan ke /dev/udp dengan cat.

$ cat segment.txt > /dev/udp/127.0.0.1/2000

{"format": "json", "version": 1}
{"trace_id": "1-594aed87-ad72e26896b3f9d3a27054bb", "id": "6226467e3f845502", "start_time": 1498082657.37518, "end_time": 1498082695.4042, "name": "test.elasticbeanstalk.com"}

Periksa log daemon untuk memverifikasi bahwa segmen tersebut telah dikirim ke X-Ray.

2017-07-07T01:57:24Z [Debug] processor: sending partial batch
2017-07-07T01:57:24Z [Debug] processor: segment batch size: 1. capacity: 50
2017-07-07T01:57:24Z [Info] Successfully sent batch of 1 segments (0.020 seconds)