Application Real-Time Monitoring Service:Rapporter les données d'application Swift avec OpenTelemetry

Prérequis

Démo

Cette rubrique montre comment utiliser OpenTelemetry pour rapporter les données d'une application en ligne de commande macOS écrite en Swift. Cette méthode s'applique également aux applications iOS.

Référentiel de code exemple : opentelemetry-swift-demo

Étape 1 : Créer une application et ajouter des dépendances

1. Créez une application macOS Command Line Tool dans Xcode.

2. Dans Xcode, sélectionnez File > Add Packages..., saisissez https://github.com/open-telemetry/opentelemetry-swift dans la zone de recherche et sélectionnez la version 1.4.1.

   Remarque

   Pour plus d'informations sur les versions, consultez les versions opentelemetry-swift.

   Accédez à File > Add Packages. Dans la barre de recherche, saisissez https://github.com/open-telemetry/opentelemetry-swift et sélectionnez le package opentelemetry-swift. Définissez la règle Dependency Rule sur Exact Version, saisissez 1.4.1 comme version, sélectionnez votre projet dans le menu Add to Project, puis cliquez sur Add Package.

3. Sélectionnez les produits de package requis.

   Les produits de package requis pour cette démo incluent OpenTelemetryApi, OpenTelemetryProtocolExporter, OpenTelemetrySdk, ResourceExtension, StdoutExporter et URLSessionInstrumentation.

Étape 2 : Initialiser OpenTelemetry

1. Créez un exportateur pour envoyer les données de télémétrie.

   Choisissez l'une des trois méthodes suivantes pour rapporter les données de trace.

   • Méthode 1 : Rapporter les données de trace via gRPC

     • Remplacez <YOUR_GRPC_ENDPOINT> et <YOUR_GRPC_PORT> par les informations d'endpoint de la section Prérequis. Exemple : host: "tracing-analysis-dc-hz.aliyuncs.com", port: 8090.

     • Remplacez <YOUR_AUTHENTICATION_TOKEN> par le jeton d'authentification de la section Prérequis.

     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éthode 2 : Rapporter les données de trace via HTTP

     Remplacez <YOUR_HTTP_ENDPOINT> par l'URL d'endpoint de la section Prérequis. Exemple : 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éthode 3 : Imprimer les données de trace dans la console

     let consoleTraceExporter = StdoutExporter(isDebug: true)

2. Obtenez un traceur pour créer des spans.

   • Remplacez <YOUR_SERVICE_NAME> par le nom de votre application et <YOUR_HOSTNAME> par votre nom d'hôte.

   • Remplacez <trace-exporter> en fonction de la méthode choisie à l'étape précédente.

     • Méthode 1 : Remplacez <trace-exporter> par otlpGrpcTraceExporter.

     • Méthode 2 : Remplacez <trace-exporter> par otlpHttpTraceExporter.

     • Méthode 3 : Remplacez <trace-exporter> par 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")

Étape 3 : Créer des spans pour suivre les données de trace

1. Créez une span, ajoutez un attribut et un événement, puis imprimez son ID de trace.

   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. Créez une span imbriquée.

   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. Démarrez l'application.

   Connectez-vous à la console ARMS. Dans le volet de navigation de gauche, choisissez Application Monitoring > Applications. Sur la page Applications, cliquez sur le nom de l'application. Sur la page qui s'affiche, consultez les données de trace.

   Remarque

   Si l'icône s'affiche dans la colonne Language, l'application est connectée à Application Monitoring. Si un tiret (-) s'affiche, l'application est connectée à Managed Service for OpenTelemetry.

Étape 4 : Connecter les traces client et serveur

1. Modifiez le format de propagation du contexte de trace dans les en-têtes de requête.

   • Différents protocoles utilisent différents en-têtes HTTP pour propager le contexte de trace vers les services en aval. Par exemple, OpenTelemetry utilise par défaut le format W3C Trace Context, mais prend également en charge d'autres formats, tandis que Zipkin utilise le format B3 ou B3 Multi. Pour plus d'informations, consultez Configurer les formats de propagation du contexte de trace pour OpenTelemetry.

   • Pour connecter les traces client et serveur, définissez le format de propagation (textPropagators et baggagePropagator) dans le client afin qu'il corresponde au protocole du serveur :

     • Si le serveur utilise le format W3C Trace Context par défaut d'OpenTelemetry, vous n'avez pas besoin de définir textPropagators et baggagePropagator dans le client.

     • Si le serveur utilise le format Zipkin B3 ou B3 Multi, définissez textPropagators sur B3Propagator et baggagePropagator sur ZipkinBaggagePropagator dans le client.

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

     • Si le serveur utilise le protocole Jaeger, définissez textPropagators sur JaegerPropagator et baggagePropagator sur JaegerBaggagePropagator dans le client.

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

     • Vous pouvez également définir plusieurs formats de propagation de trace simultanément.

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

2. Importez URLSessionInstrumentation.

   URLSessionInstrumentation est un plug-in qui intercepte automatiquement les requêtes réseau URLSession pour créer des traces.

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

3. Utilisez URLSession pour envoyer une requête réseau au serveur.

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

   Voir l'exemple de code complet

   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. Démarrez l'application et consultez la trace client-serveur connectée sur la page Trace Explorer.

   Dans la trace, HTTP GET représente l'application iOS et zipkin-demo-server représente l'application serveur.

   Les attributs de requête tels que http.method=GET, http.status_code=200 et http.url=http://localhost:8081/zipkin/server apparaissent dans la section Additional Information > Attributes de la span.