Application Real-Time Monitoring Service:Reporte de datos de aplicaciones Swift con OpenTelemetry

Requisitos previos

Demostración

En este tema se demuestra cómo usar OpenTelemetry para reportar datos desde una aplicación de línea de comandos de macOS escrita en Swift. Este método también aplica para aplicaciones de iOS.

Repositorio del código de ejemplo: opentelemetry-swift-demo

Paso 1: Crear una aplicación y agregar dependencias

1. Cree una aplicación macOS Command Line Tool en Xcode.

2. En Xcode, seleccione File > Add Packages..., introduzca https://github.com/open-telemetry/opentelemetry-swift en el cuadro de búsqueda y seleccione la versión 1.4.1.

   Nota

   Para obtener más información sobre las versiones, consulte opentelemetry-swift releases.

   Vaya a File > Add Packages. En la barra de búsqueda, introduzca https://github.com/open-telemetry/opentelemetry-swift y seleccione el paquete opentelemetry-swift. Establezca Dependency Rule en Exact Version, introduzca 1.4.1 como versión, seleccione su proyecto en el menú Add to Project y haga clic en Add Package.

3. Seleccione los productos del paquete obligatorios.

   Los productos del paquete necesarios para esta demostración incluyen OpenTelemetryApi, OpenTelemetryProtocolExporter, OpenTelemetrySdk, ResourceExtension, StdoutExporter y URLSessionInstrumentation.

Paso 2: Inicializar OpenTelemetry

1. Cree un exportador para enviar los datos de telemetría.

   Elija uno de los tres métodos siguientes para reportar los datos de trazas.

   • Método 1: reportar datos de trazas mediante gRPC

     • Reemplace <YOUR_GRPC_ENDPOINT> y <YOUR_GRPC_PORT> con la información del endpoint de la sección de requisitos previos. Por ejemplo: host: "tracing-analysis-dc-hz.aliyuncs.com", port: 8090.

     • Reemplace <YOUR_AUTHENTICATION_TOKEN> con el token de autenticación de la sección de requisitos previos.

     let grpcChannel = ClientConnection(
         configuration: ClientConnection.Configuration.default(
             target: .hostAndPort("<YOUR_GRPC_ENDPOINT>", <YOUR_GRPC_PORT>), // Example endpoint: tracing-analysis-dc-hz.aliyuncs.com. Do not include the "http://" prefix.
             eventLoopGroup: MultiThreadedEventLoopGroup(numberOfThreads: 1)
         )
     )
     let otlpGrpcConfiguration = OtlpConfiguration(
         timeout: OtlpConfiguration.DefaultTimeoutInterval,
         headers: [
             ("Authentication","<YOUR_AUTHENTICATION_TOKEN>")
         ]
     )
     let otlpGrpcTraceExporter = OtlpTraceExporter(channel: grpcChannel, config: otlpGrpcConfiguration)

   • Método 2: reportar datos de trazas mediante HTTP

     Reemplace <YOUR_HTTP_ENDPOINT> con la URL del endpoint de la sección de requisitos previos. Por ejemplo: 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!)

   • Método 3: imprimir los datos de trazas en la consola

     let consoleTraceExporter = StdoutExporter(isDebug: true)

2. Obtenga un tracer para crear spans.

   • Reemplace <YOUR_SERVICE_NAME> con el nombre de su aplicación y <YOUR_HOSTNAME> con su nombre de host.

   • Reemplace <trace-exporter> según el método que eligió en the previous step.

     • Método 1: reemplace <trace-exporter> por otlpGrpcTraceExporter.

     • Método 2: reemplace <trace-exporter> por otlpHttpTraceExporter.

     • Método 3: reemplace <trace-exporter> por consoleTraceExporter.

   // Set the application name and hostname.
   let resource = Resource(attributes: [
       ResourceAttributes.serviceName.rawValue: AttributeValue.string("<YOUR_SERVICE_NAME>"),
       ResourceAttributes.hostName.rawValue: AttributeValue.string("<YOUR_HOSTNAME>")
   ])
   // Configure the TracerProvider.
   OpenTelemetry.registerTracerProvider(tracerProvider: TracerProviderBuilder()
                                        .add(spanProcessor: BatchSpanProcessor(spanExporter: <trace-exporter>)) // Report to Managed Service for OpenTelemetry.
                                        .with(resource: resource)
                                        .build())
   // Get a tracer to create spans.
   let tracer = OpenTelemetry.instance.tracerProvider.get(instrumentationName: "instrumentation-library-name", instrumentationVersion: "1.0.0")

Paso 3: Crear spans para rastrear los datos de trazas

1. Cree un span, agregue un atributo y un evento, e imprima su ID de traza.

   let span = tracer.spanBuilder(spanName: "first span").startSpan()
   // Set an attribute.
   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)
   ]
   // your code...
   // Set an event.
   span.addEvent(name: "computation complete", attributes: attributes)
   // Print the TraceId.
   print(span.context.traceId.hexString)
   // your code...
   // End the current span.
   span.end()

2. Cree un span anidado.

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

3. Inicie la aplicación.

   Inicie sesión en la consola de ARMS. En el panel de navegación izquierdo, seleccione Application Monitoring > Applications. En la página Applications, haga clic en el nombre de la aplicación. En la página que aparece, consulte los datos de trazas.

   Nota

   Si se muestra el ícono en la columna Language, la aplicación está conectada a Application Monitoring. Si se muestra un guion (-), la aplicación está conectada a Managed Service for OpenTelemetry.

Paso 4: Conectar las trazas del cliente y del servidor

1. Modifique el formato de propagación del contexto de traza en los encabezados de la solicitud.

   • Los distintos protocolos usan diferentes encabezados HTTP para propagar el contexto de traza a los servicios posteriores. Por ejemplo, OpenTelemetry usa el formato W3C Trace Context de manera predeterminada, pero también admite otros formatos, mientras que Zipkin usa el formato B3 o B3 Multi. Para obtener más información, consulte Configure trace context propagation formats for OpenTelemetry.

   • Para conectar las trazas del cliente y del servidor, configure el formato de propagación (textPropagators y baggagePropagator) en el cliente para que coincida con el protocolo del servidor:

     • Si el servidor usa el formato W3C Trace Context predeterminado de OpenTelemetry, no es necesario configurar textPropagators ni baggagePropagator en el cliente.

     • Si el servidor usa el formato B3 o B3 Multi de Zipkin, establezca textPropagators en B3Propagator y baggagePropagator en ZipkinBaggagePropagator dentro del cliente.

       // Set the B3 propagation format.
       OpenTelemetry.registerPropagators(textPropagators: [B3Propagator()],
                                         baggagePropagator: ZipkinBaggagePropagator())

     • Si el servidor usa el protocolo Jaeger, establezca textPropagators en JaegerPropagator y baggagePropagator en JaegerBaggagePropagator dentro del cliente.

       // Set the Jaeger propagation format.
       OpenTelemetry.registerPropagators(textPropagators: [JaegerPropagator()],
                                         baggagePropagator: JaegerBaggagePropagator())

     • También puede configurar varios formatos de propagación de trazas de forma simultánea.

       // Use the W3C Trace Context, B3, and Jaeger formats at the same time.
       OpenTelemetry.registerPropagators(textPropagators: [W3CTraceContextPropagator(), 
                                                           B3Propagator(), 
                                                           JaegerPropagator()],
                                         baggagePropagator: W3CBaggagePropagator())

2. Importe URLSessionInstrumentation.

   URLSessionInstrumentation es un complemento que intercepta automáticamente las solicitudes de red de URLSession para crear trazas.

   import URLSessionInstrumentation
   ...
   let networkInstrumentation = URLSessionInstrumentation(configuration: URLSessionInstrumentationConfiguration())

3. Use URLSession para enviar una solicitud de red al servidor.

   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()

   Consulte el código de ejemplo completo

   OpenTelemetryUtil.swift

   import Foundation
   import GRPC
   import NIO
   import OpenTelemetryApi
   import OpenTelemetrySdk
   import OpenTelemetryProtocolExporter
   import StdoutExporter
   class OpenTelemetryUtil {
       private static let tracerProvider: TracerProvider = {
           // Report data over 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)
           // Set the application name and 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)) // Print the trace to the console for debugging.
               .with(resource: resource)
               .build()
           // Configure the TracerProvider.
           OpenTelemetry.registerTracerProvider(tracerProvider: tracerProvider)
           // Modify the propagation format.
           OpenTelemetry.registerPropagators(textPropagators: [W3CTraceContextPropagator(),
                                                               B3Propagator(),
                                                               JaegerPropagator()],
                                             baggagePropagator: W3CBaggagePropagator())
           return tracerProvider
       }()
       // Get a tracer to create spans.
       static func getTracer(name: String, version: String) -> Tracer {
           return tracerProvider.get(instrumentationName: name, instrumentationVersion: version)
       }
   }
   

   main.swift

   import Foundation
   import OpenTelemetryApi
   import OpenTelemetrySdk
   // Automatically instrument network requests.
   import URLSessionInstrumentation
   let tracer = OpenTelemetryUtil.getTracer(name: "ios-demo", version: "1.0.0")
   // Create a nested span.
   let parentSpan = tracer.spanBuilder(spanName: "parent span").startSpan()
   let childSpan = tracer.spanBuilder(spanName: "child span").setParent(parentSpan).startSpan()
   // Set attributes.
   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)
   ]
   // Set an event.
   childSpan.addEvent(name: "event", attributes: attributes)
   // Print the TraceId.
   print(childSpan.context.traceId.hexString)
   // Send a network request to the 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()
   // Manually end the created spans.
   childSpan.end()
   parentSpan.end()
   sleep(60)
   print("end")
   

4. Inicie la aplicación y consulte la traza conectada entre el cliente y el servidor en la página Trace Explorer.

   En la traza, HTTP GET representa la aplicación de iOS y zipkin-demo-server representa la aplicación del servidor.

   Los atributos de la solicitud, como http.method=GET, http.status_code=200 y http.url=http://localhost:8081/zipkin/server, aparecen en la sección Additional Information > Attributes del span.