Gunakan OpenTelemetry untuk menginstrumentasi aplikasi Swift dan melaporkan data jejak - Managed Service for OpenTelemetry

Setelah Anda menginstrumentasikan aplikasi Anda dengan OpenTelemetry dan melaporkan Managed Service for OpenTelemetry ke Managed Service for OpenTelemetry, layanan tersebut mulai memantau aplikasi Anda. Anda dapat melihat berbagai macam data pemantauan, termasuk topologi aplikasi, jejak, eksepsi, transaksi lambat, dan analisis SQL. Topik ini menunjukkan cara menggunakan OpenTelemetry untuk menginstrumentasikan aplikasi Swift dan melaporkan datanya.

Prasyarat

Dapatkan titik akhir

Konsol baru

Masuk ke Konsol Managed Service for OpenTelemetry. Di panel navigasi kiri, klik Integration Center.
Di halaman Integration Center, klik kartu OpenTelemetry pada bagian Open Source Frameworks.
Di panel OpenTelemetry, klik tab Start Integration, lalu pilih wilayah tempat Anda ingin melaporkan data.

Catatan
Saat Anda mengakses wilayah untuk pertama kalinya, resource akan diinisialisasi secara otomatis di sana.
Konfigurasikan parameter Connection Type dan Export Protocol, lalu salin titik akhirnya.
- Connection Type: Jika layanan Anda dideploy di Alibaba Cloud dan berada di wilayah yang Anda pilih, kami menyarankan Anda mengatur parameter ini ke Alibaba Cloud VPC Network. Jika tidak, atur ke Public Network.
- Export Protocol: Atur parameter ini ke HTTP (disarankan) atau gRPC berdasarkan protokol yang didukung oleh client.

Konsol lama

Masuk ke Konsol Managed Service for OpenTelemetry.
Di panel navigasi kiri, klik Cluster Configurations. Di halaman yang muncul, klik tab Access point information.
Di bilah navigasi atas, pilih wilayah tempat Anda ingin melaporkan data. Di bagian Cluster Information, aktifkan Show Token.
Atur parameter Client ke OpenTelemetry.

Di kolom Related Information pada tabel, salin titik akhirnya.

Catatan
Jika aplikasi Anda dideploy di lingkungan produksi Alibaba Cloud, gunakan titik akhir virtual private cloud (VPC). Jika tidak, gunakan titik akhir publik.

Demo

Topik ini menjelaskan cara menggunakan OpenTelemetry untuk melaporkan data dari aplikasi command-line macOS yang ditulis dalam Swift. Metode ini juga berlaku untuk aplikasi iOS.

Repositori kode contoh: opentelemetry-swift-demo

Langkah 1: Buat aplikasi dan tambahkan dependensi

Buat aplikasi macOS Command Line Tool di Xcode.
Di Xcode, pilih File > Add Packages..., masukkan https://github.com/open-telemetry/opentelemetry-swift di kotak pencarian, lalu pilih versi 1.4.1.

Catatan
Untuk informasi lebih lanjut tentang versi, lihat rilis opentelemetry-swift.

Buka File > Add Packages. Di bilah pencarian, masukkan https://github.com/open-telemetry/opentelemetry-swift dan pilih paket opentelemetry-swift. Atur Dependency Rule ke Exact Version, masukkan 1.4.1 sebagai versi, pilih proyek Anda dari menu Add to Project, lalu klik Add Package.
Pilih produk paket yang diperlukan.

Produk paket yang diperlukan untuk demo ini mencakup OpenTelemetryApi, OpenTelemetryProtocolExporter, OpenTelemetrySdk, ResourceExtension, StdoutExporter, dan URLSessionInstrumentation.

Langkah 2: Inisialisasi OpenTelemetry

Buat exporter untuk mengirim data telemetri.

Pilih salah satu dari tiga metode berikut untuk melaporkan data jejak.

Metode 1: Laporkan data jejak melalui gRPC

Ganti <YOUR_GRPC_ENDPOINT> dan <YOUR_GRPC_PORT> dengan informasi titik akhir dari bagian Prasyarat. Contoh: host: "tracing-analysis-dc-hz.aliyuncs.com", port: 8090.
Ganti <YOUR_AUTHENTICATION_TOKEN> dengan token autentikasi dari bagian Prasyarat.

let grpcChannel = ClientConnection(
    configuration: ClientConnection.Configuration.default(
        target: .hostAndPort("<YOUR_GRPC_ENDPOINT>", <YOUR_GRPC_PORT>), // Contoh titik akhir: tracing-analysis-dc-hz.aliyuncs.com. Jangan sertakan awalan "http://".
        eventLoopGroup: MultiThreadedEventLoopGroup(numberOfThreads: 1)
    )
)
let otlpGrpcConfiguration = OtlpConfiguration(
    timeout: OtlpConfiguration.DefaultTimeoutInterval,
    headers: [
        ("Authentication","<YOUR_AUTHENTICATION_TOKEN>")
    ]
)
let otlpGrpcTraceExporter = OtlpTraceExporter(channel: grpcChannel, config: otlpGrpcConfiguration)

Metode 2: Laporkan data jejak melalui HTTP

Ganti <YOUR_HTTP_ENDPOINT> dengan URL titik akhir dari bagian Prasyarat. Contoh: http://tracing-analysis-dc-hz.aliyuncs.com/adapt_xxxx@xxxx_xxxx@xxxx/api/otlp/traces.
```
let url = URL(string: "<YOUR_HTTP_ENDPOINT>")
let otlpHttpTraceExporter = OtlpHttpTraceExporter(endpoint: url!)
```

Metode 3: Cetak data jejak ke konsol

let consoleTraceExporter = StdoutExporter(isDebug: true)

Dapatkan tracer untuk membuat rentang.

Ganti <YOUR_SERVICE_NAME> dengan nama aplikasi Anda dan <YOUR_HOSTNAME> dengan hostname Anda.
Ganti <trace-exporter> berdasarkan metode yang Anda pilih di langkah sebelumnya.
- Metode 1: Ganti <trace-exporter> dengan otlpGrpcTraceExporter.
- Metode 2: Ganti <trace-exporter> dengan otlpHttpTraceExporter.
- Metode 3: Ganti <trace-exporter> dengan consoleTraceExporter.

// Tetapkan nama aplikasi dan hostname.
let resource = Resource(attributes: [
    ResourceAttributes.serviceName.rawValue: AttributeValue.string("<YOUR_SERVICE_NAME>"),
    ResourceAttributes.hostName.rawValue: AttributeValue.string("<YOUR_HOSTNAME>")
])
// Konfigurasikan TracerProvider.
OpenTelemetry.registerTracerProvider(tracerProvider: TracerProviderBuilder()
                                     .add(spanProcessor: BatchSpanProcessor(spanExporter: <trace-exporter>)) // Laporkan ke Managed Service for OpenTelemetry.
                                     .with(resource: resource)
                                     .build())
// Dapatkan tracer untuk membuat rentang.
let tracer = OpenTelemetry.instance.tracerProvider.get(instrumentationName: "instrumentation-library-name", instrumentationVersion: "1.0.0")

Langkah 3: Buat rentang untuk melacak data jejak

Buat rentang, tambahkan atribut dan event, lalu cetak ID jejaknya.

let span = tracer.spanBuilder(spanName: "first span").startSpan()
// Tetapkan atribut.
span.setAttribute(key: "http.method", value: "GET")
span.setAttribute(key: "http.url", value: "www.aliyun.com")
let attributes = [
    "key": AttributeValue.string("value"),
    "result": AttributeValue.int(100)
]
// kode Anda...
// Tambahkan event.
span.addEvent(name: "computation complete", attributes: attributes)
// Cetak TraceId.
print(span.context.traceId.hexString)
// kode Anda...
// Akhiri rentang saat ini.
span.end()

Buat rentang bersarang.

let parentSpan = tracer.spanBuilder(spanName: "parent span").startSpan()
// kode Anda...
let childSpan = tracer.spanBuilder(spanName: "child span").setParent(parentSpan).startSpan()
// kode Anda...
childSpan.end()
// kode Anda...
parentSpan.end()

Jalankan aplikasi.

Di halaman Applications pada atau Managed Service for OpenTelemetry console, klik nama aplikasi, lalu lihat Data jejak pada halaman yang muncul.

Langkah 4: Hubungkan jejak client dan server

Ubah format propagasi konteks jejak di header permintaan.
- Protokol yang berbeda menggunakan Header HTTP yang berbeda untuk menyebarkan konteks jejak ke layanan downstream. Misalnya, OpenTelemetry menggunakan format W3C Trace Context secara default tetapi juga mendukung format lain, sedangkan Zipkin menggunakan format B3 atau B3 Multi. Untuk informasi lebih lanjut, lihat Konfigurasikan format propagasi konteks jejak untuk OpenTelemetry.
- Untuk menghubungkan jejak client dan server, atur format propagasi (textPropagators dan baggagePropagator) di client agar sesuai dengan protokol server:
  - Jika server menggunakan format W3C Trace Context OpenTelemetry default, Anda tidak perlu mengatur textPropagators dan baggagePropagator di client.
  - Jika server menggunakan format B3 atau B3 Multi Zipkin, atur textPropagators ke B3Propagator dan baggagePropagator ke ZipkinBaggagePropagator di client.
```
// Atur format propagasi B3.
OpenTelemetry.registerPropagators(textPropagators: [B3Propagator()],
                                  baggagePropagator: ZipkinBaggagePropagator())
```
  - Jika server menggunakan protokol Jaeger, atur textPropagators ke JaegerPropagator dan baggagePropagator ke JaegerBaggagePropagator di client.
```
// Atur format propagasi Jaeger.
OpenTelemetry.registerPropagators(textPropagators: [JaegerPropagator()],
                                  baggagePropagator: JaegerBaggagePropagator())
```
  - Anda juga dapat mengatur beberapa format propagasi jejak secara bersamaan.
```
// Gunakan format W3C Trace Context, B3, dan Jaeger secara bersamaan.
OpenTelemetry.registerPropagators(textPropagators: [W3CTraceContextPropagator(), 
                                                    B3Propagator(), 
                                                    JaegerPropagator()],
                                  baggagePropagator: W3CBaggagePropagator())
```
Impor URLSessionInstrumentation.

URLSessionInstrumentation adalah plug-in yang secara otomatis mengintersepsi permintaan jaringan URLSession untuk membuat jejak.
```
import URLSessionInstrumentation
...
let networkInstrumentation = URLSessionInstrumentation(configuration: URLSessionInstrumentationConfiguration())
```

Gunakan URLSession untuk mengirim permintaan jaringan ke server.

let url = URL(string: "<YOUR_SERVER_ADDRESS>")!
let request = URLRequest(url: url)
let semaphore = DispatchSemaphore(value: 0)
let task = URLSession.shared.dataTask(with: request) { data, _, _ in
    if let data = data {
        let string = String(decoding: data, as: UTF8.self)
        print(string)
    }
    semaphore.signal()
}
task.resume()
semaphore.wait()

Lihat kode contoh lengkap

OpenTelemetryUtil.swift

import Foundation
import GRPC
import NIO
import OpenTelemetryApi
import OpenTelemetrySdk
import OpenTelemetryProtocolExporter
import StdoutExporter
class OpenTelemetryUtil {
    private static let tracerProvider: TracerProvider = {
        // Laporkan data melalui gRPC.
        let grpcChannel = ClientConnection(
            configuration: ClientConnection.Configuration.default(
                target: .hostAndPort("tracing-analysis-dc-hz.aliyuncs.com", 8090),
                eventLoopGroup: MultiThreadedEventLoopGroup(numberOfThreads: 1)
            )
        )
        let otlpGrpcConfiguration = OtlpConfiguration(
            timeout: OtlpConfiguration.DefaultTimeoutInterval,
            headers: [
                ("Authentication","${YOUR_AUTHENTICATION_TOKEN}")
            ]
        )
        let otlpGrpcTraceExporter = OtlpTraceExporter(channel: grpcChannel, config: otlpGrpcConfiguration)
        let consoleTraceExporter = StdoutExporter(isDebug: true)
        // Tetapkan nama aplikasi dan hostname.
        let resource = Resource(attributes: [
            ResourceAttributes.serviceName.rawValue: AttributeValue.string("otel-swift-demo-grpc"),
            ResourceAttributes.hostName.rawValue: AttributeValue.string("adam.mac")
        ])
        let tracerProvider = TracerProviderBuilder()
            .add(spanProcessor: BatchSpanProcessor(spanExporter: otlpGrpcTraceExporter))
//            .add(spanProcessor: BatchSpanProcessor(spanExporter: consoleTraceExporter)) // Cetak jejak ke konsol untuk debugging.
            .with(resource: resource)
            .build()
        // Konfigurasikan TracerProvider.
        OpenTelemetry.registerTracerProvider(tracerProvider: tracerProvider)
        // Ubah format propagasi.
        OpenTelemetry.registerPropagators(textPropagators: [W3CTraceContextPropagator(),
                                                            B3Propagator(),
                                                            JaegerPropagator()],
                                          baggagePropagator: W3CBaggagePropagator())
        return tracerProvider
    }()
    // Dapatkan tracer untuk membuat rentang.
    static func getTracer(name: String, version: String) -> Tracer {
        return tracerProvider.get(instrumentationName: name, instrumentationVersion: version)
    }
}

main.swift

import Foundation
import OpenTelemetryApi
import OpenTelemetrySdk
// Instrumentasi otomatis permintaan jaringan.
import URLSessionInstrumentation
let tracer = OpenTelemetryUtil.getTracer(name: "ios-demo", version: "1.0.0")
// Buat rentang bersarang.
let parentSpan = tracer.spanBuilder(spanName: "parent span").startSpan()
let childSpan = tracer.spanBuilder(spanName: "child span").setParent(parentSpan).startSpan()
// Tetapkan atribut.
childSpan.setAttribute(key: "http.method", value: "GET")
childSpan.setAttribute(key: "http.url", value: "www.aliyun.com")
let attributes = [
    "stringKey": AttributeValue.string("value"),
    "intKey": AttributeValue.int(100)
]
// Tambahkan event.
childSpan.addEvent(name: "event", attributes: attributes)
// Cetak TraceId.
print(childSpan.context.traceId.hexString)
// Kirim permintaan jaringan ke server.
let networkInstrumentation = URLSessionInstrumentation(configuration: URLSessionInstrumentationConfiguration())
let url = URL(string: "${YOUR_SERVER_ADDRESS}")!
let request = URLRequest(url: url)
let semaphore = DispatchSemaphore(value: 0)
let task = URLSession.shared.dataTask(with: request) { data, _, _ in
    if let data = data {
        let string = String(decoding: data, as: UTF8.self)
        print(string)
    }
    semaphore.signal()
}
task.resume()
semaphore.wait()
// Akhiri secara manual rentang yang dibuat.
childSpan.end()
parentSpan.end()
sleep(60)
print("end")

Jalankan aplikasi dan lihat jejak client-server yang terhubung di halaman Trace Explorer.

Dalam jejak tersebut, HTTP GET merepresentasikan aplikasi iOS dan zipkin-demo-server merepresentasikan aplikasi server.

Atribut permintaan seperti http.method=GET, http.status_code=200, dan http.url=http://localhost:8081/zipkin/server muncul di bagian Additional Information > Attributes pada rentang tersebut.