Chapter 10. Integrating the OpenTelemetry SDK with APIcast
Chapter 10. Integrating the OpenTelemetry SDK with APIcast The integration of OpenTelemetry SDK with APIcast enables the export of telemetry data that provide insights into system performance and behavior. APIcast relies on the NGINX OpenTelemetry tracing library . This integration helps to identify and resolve performance issues, leading to improved system stability. Prerequisites Trace Collector supporting APIcast exporter traces. The only implemented exporter in APIcast is OpenTelemetry Protocol (OTLP) over gRPC (Remote Procedure Calls) OTLP/gRPC . OTLP over HTTP ( OTLP/HTTP ) is not being used by APIcast. If the existing collector does not support APIcast OTLP/gRPC traces, an OpenTelemetry Collector is required as tracing proxy. 10.1. Jaeger service examples for deploying listening for OTP and gRPC traces Jaeger 1.35 or later supports the trace collector, which includes APIcast exporter functionality. As a result, Jaeger can now receive trace data from the OpenTelemetry SDKs in the native OpenTelemetry Protocol (OTLP) over gRPC (Remote Procedure Calls) OTLP/gRPC . Important The following examples are not suitable for production use. Example for deploying Jaeger oc apply -f - <<EOF apiVersion: apps/v1 kind: Deployment metadata: name: jaeger labels: app: jaeger spec: replicas: 1 selector: matchLabels: app: jaeger template: metadata: labels: app: jaeger spec: containers: - name: jaeger image: jaegertracing/all-in-one:latest env: - name: JAEGER_DISABLED value: "false" - name: COLLECTOR_OTLP_ENABLED value: "true" imagePullPolicy: Always ports: - containerPort: 16686 - containerPort: 4317 apiVersion: v1 kind: Service metadata: name: jaeger labels: app: jaeger spec: ports: - port: 16686 name: http - port: 4317 name: internal selector: app: jaeger EOF A Jaeger service instance will be deployed listening for OTLP/gRPC traces in port 4317 and in the 3scale Admin Portal on port 16686. Tracing header example: "Traceparent": "00-4335058ae8ec72f9636d8c0da08c62be-137a4beaae638572-01", 10.2. Configuring APIcast for tracing To ensure a scalable and reliable gateway infrastructure for 3scale APIs, you can manually configure APIcast for tracing. This will help ensure a reliable and scalable gateway infrastructure for your API services. Procedure Create a configuration file for APIcast instrumentation: The configuration file specification is defined in the NGINX instrumentation library repo . USD oc apply -f - <<EOF apiVersion: v1 kind: Secret metadata: name: otel-config type: Opaque stringData: config.json: | # "otlp" is the only supported exporter in APIcast exporter = "otlp" processor = "simple" [exporters.otlp] # Alternatively the OTEL_EXPORTER_OTLP_ENDPOINT environment variable can also be used. host = "USD{COLLECTOR_HOST}" port = USD{COLLECTOR_PORT} # Optional: enable SSL, for endpoints that support it # use_ssl = true # Optional: set a filesystem path to a pem file to be used for SSL encryption # (when use_ssl = true) # ssl_cert_path = "/path/to/cert.pem" [processors.batch] max_queue_size = 2048 schedule_delay_millis = 5000 max_export_batch_size = 512 [service] name = "apicast" # Opentelemetry resource name EOF Define an APIcast custom resource (CR) that specifies openTelemetry attributes. In the CR definition, set the openTelemetry.tracingConfigSecretRef.name attribute to the name of the secret that contains your openTelemetry configuration details. The following example shows only content relative to configuring openTelemetry: apiVersion: apps.3scale.net/v1alpha1 kind: APIcast metadata: name: apicast1 spec: ... openTelemetry: enabled: true tracingConfigSecretRef: name: "USDNAME_OF_SECRET" 10.3. Additional resources APIcast environment variables W3C Supported propagation types
apply -f - <<EOF apiVersion: apps/v1 kind: Deployment metadata: name: jaeger labels: app: jaeger spec: replicas: 1 selector: matchLabels: app: jaeger template: metadata: labels: app: jaeger spec: containers: - name: jaeger image: jaegertracing/all-in-one:latest env: - name: JAEGER_DISABLED value: "false" - name: COLLECTOR_OTLP_ENABLED value: "true" imagePullPolicy: Always ports: - containerPort: 16686 - containerPort: 4317 apiVersion: v1 kind: Service metadata: name: jaeger labels: app: jaeger spec: ports: - port: 16686 name: http - port: 4317 name: internal selector: app: jaeger EOF "Traceparent": "00-4335058ae8ec72f9636d8c0da08c62be-137a4beaae638572-01", oc apply -f - <<EOF apiVersion: v1 kind: Secret metadata: name: otel-config type: Opaque stringData: config.json: | # "otlp" is the only supported exporter in APIcast exporter = "otlp" processor = "simple" [exporters.otlp] # Alternatively the OTEL_EXPORTER_OTLP_ENDPOINT environment variable can also be used. host = "USD{COLLECTOR_HOST}" port = USD{COLLECTOR_PORT} # Optional: enable SSL, for endpoints that support it # use_ssl = true # Optional: set a filesystem path to a pem file to be used for SSL encryption # (when use_ssl = true) # ssl_cert_path = "/path/to/cert.pem" [processors.batch] max_queue_size = 2048 schedule_delay_millis = 5000 max_export_batch_size = 512 [service] name = "apicast" # Opentelemetry resource name EOF apiVersion: apps.3scale.net/v1alpha1 kind: APIcast metadata: name: apicast1 spec: openTelemetry: enabled: true tracingConfigSecretRef: name: "USDNAME_OF_SECRET"