Search

Chapter 9. Integrating the OpenTelemetry SDK with APIcast

download PDF

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.

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.

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",

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

  1. 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
  2. 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: "$NAME_OF_SECRET"

9.3. Additional resources

Red Hat logoGithubRedditYoutubeTwitter

Learn

Try, buy, & sell

Communities

About Red Hat Documentation

We help Red Hat users innovate and achieve their goals with our products and services with content they can trust.

Making open source more inclusive

Red Hat is committed to replacing problematic language in our code, documentation, and web properties. For more details, see the Red Hat Blog.

About Red Hat

We deliver hardened solutions that make it easier for enterprises to work across platforms and environments, from the core datacenter to the network edge.

© 2024 Red Hat, Inc.