Chapter 9. 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/gRPCtraces, an OpenTelemetry Collector is required as tracing proxy.
-
The only implemented exporter in APIcast is OpenTelemetry Protocol (OTLP) over gRPC (Remote Procedure Calls)
9.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.
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: 4317apiVersion: 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",
9.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.
$ 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 = "${COLLECTOR_HOST}" port = ${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
openTelemetryattributes. In the CR definition, set theopenTelemetry.tracingConfigSecretRef.nameattribute 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: "$NAME_OF_SECRET"
