Managed Service for OpenTelemetry:Relate dados de aplicações Swift com o OpenTelemetry

Pré-requisitos

Demonstração

Este tópico demonstra como usar o OpenTelemetry para relatar dados de uma aplicação de linha de comando macOS escrita em Swift. Este método também se aplica a aplicações iOS.

Repositório de código de exemplo: opentelemetry-swift-demo

Etapa 1: Criar uma aplicação e adicionar dependências

1. Crie uma aplicação macOS Command Line Tool no Xcode.

2. No Xcode, selecione File > Add Packages..., insira https://github.com/open-telemetry/opentelemetry-swift na caixa de pesquisa e selecione a versão 1.4.1.

   Nota

   Para mais informações sobre versões, consulte opentelemetry-swift releases.

   Acesse File > Add Packages. Na barra de pesquisa, insira https://github.com/open-telemetry/opentelemetry-swift e selecione o pacote opentelemetry-swift. Defina a Dependency Rule como Exact Version, insira 1.4.1 como versão, selecione seu projeto no menu Add to Project e clique em Add Package.

3. Selecione os produtos do pacote necessários.

   Os produtos do pacote necessários para esta demonstração incluem OpenTelemetryApi, OpenTelemetryProtocolExporter, OpenTelemetrySdk, ResourceExtension, StdoutExporter e URLSessionInstrumentation.

Etapa 2: Inicializar o OpenTelemetry

1. Crie um exporter para enviar dados de telemetria.

   Escolha um dos três métodos a seguir para relatar dados de trace.

   • Método 1: Relatar dados de trace via gRPC

     • Substitua <YOUR_GRPC_ENDPOINT> e <YOUR_GRPC_PORT> pelas informações de endpoint da seção Pré-requisitos. Exemplo: host: "tracing-analysis-dc-hz.aliyuncs.com", port: 8090.

     • Substitua <YOUR_AUTHENTICATION_TOKEN> pelo token de autenticação obtido na seção Pré-requisitos.

     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: Relatar dados de trace via HTTP

     Substitua <YOUR_HTTP_ENDPOINT> pela URL do endpoint obtida na seção Pré-requisitos. Exemplo: 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 dados de trace no console

     let consoleTraceExporter = StdoutExporter(isDebug: true)

2. Obtenha um tracer para criar spans.

   • Substitua <YOUR_SERVICE_NAME> pelo nome da sua aplicação e <YOUR_HOSTNAME> pelo seu hostname.

   • Substitua <trace-exporter> de acordo com o método escolhido na etapa anterior.

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

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

     • Método 3: Substitua <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")

Etapa 3: Criar spans para rastrear dados de trace

1. Crie um span, adicione um atributo e um evento e imprima seu trace ID.

   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. Crie um span aninhado.

   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 a aplicação.

   Na página Applications do console do Managed Service for OpenTelemetry, clique no nome da aplicação. Na página exibida, visualize os dados de trace.

Etapa 4: Conectar os traces de cliente e servidor

1. Modifique o formato de propagação de contexto de trace nos cabeçalhos da requisição.

   • Protocolos diferentes utilizam cabeçalhos HTTP distintos para propagar o contexto de trace para services downstream. Por exemplo, o OpenTelemetry usa o formato W3C Trace Context por padrão, mas também suporta outros formatos, enquanto o Zipkin utiliza o formato B3 ou B3 Multi. Para mais informações, consulte Configurar formatos de propagação de contexto de trace para OpenTelemetry.

   • Para conectar traces de cliente e servidor, defina o formato de propagação (textPropagators e baggagePropagator) no cliente para corresponder ao protocolo do servidor:

     • Se o servidor utilizar o formato padrão OpenTelemetry W3C Trace Context, não é necessário definir textPropagators e baggagePropagator no cliente.

     • Se o servidor utilizar o formato Zipkin B3 ou B3 Multi, defina textPropagators como B3Propagator e baggagePropagator como ZipkinBaggagePropagator no cliente.

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

     • Se o servidor utilizar o protocolo Jaeger, defina textPropagators como JaegerPropagator e baggagePropagator como JaegerBaggagePropagator no cliente.

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

     • Também é possível definir múltiplos formatos de propagação de trace simultaneamente.

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

2. Importe URLSessionInstrumentation.

   O URLSessionInstrumentation é um plug-in que intercepta automaticamente requisições de rede URLSession para criar traces.

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

3. Utilize URLSession para enviar uma requisição de rede ao 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()

   Visualizar o código de exemplo 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 a aplicação e visualize o trace conectado entre cliente e servidor na página Trace Explorer.

   No trace, HTTP GET representa a aplicação iOS e zipkin-demo-server representa a aplicação servidora.

   Atributos da requisição como http.method=GET, http.status_code=200 e http.url=http://localhost:8081/zipkin/server aparecem na seção Additional Information > Attributes do span.