This article provides instructions for setting up OpenTelemetry instrumentation for the Cequence Unified API Protection (UAP) platform services.

When the OpenTelemetry operator is required

The OpenTelemetry operator is only needed in clusters where you want automatic instrumentation.

• The Cequence UAP platform cluster: Install the operator if you want to auto-instrument the Cequence UAP platform services, such as api-gateway, bff, or ticketing-service).
• Other clusters:
  • Not required when applications use manual instrumentation (OpenTelemetry SDK) or send traces directly.
  • When you want auto-instrumentation in a cluster, you have to install the OpenTelemetry operator on that cluster.
  • Applications in other clusters only need the Cequence UAP platform endpoint URL and Bearer token to send traces.

Applications in different clusters can send traces to the Cequence UAP platform without installing the operator. Such applications only need the endpoint URL (https://edge.<uap-domain>/otlp/trace) and a valid Bearer token.

Install UAP with full deployment

Install the Cequence Unified API Protection (UAP) platform with the full deployment type.

/opt/cequence/bin/setup.sh [subdomain.com] [full]

The OpenTelemetry operator installs automatically when you run 4-setup-opentelemetry.sh in the next step.

Create the Flow Graph OTLP client

The Flow Graph OTLP client provides the credentials that the Cequence UAP platform uses to authenticate telemetry data.

1. Log in to the Cequence UAP platform and click the gear in the top right.
2. Select General Settings.
3. In User Management, click the Clients tab.
4. At the top right, click Add New Client.
   The New Client dialog appears.
5. Create a new client with the following configuration.
   • Client ID: flow-graph (or your preferred name)
   • Client type: Select Flow Graph OTLP.
   • Offline access: Enable this option for long-lived tokens.
6. Configure token settings.
   • Access Token Lifespan: Set to 31536000 (1 year in seconds).
7. Click Save.
   The client credentials appear.
8. Copy the Client Secret from the client credentials.
   You need this value for the next step. Note the Client Secret securely.

Use the setup script to configure OpenTelemetry

Use this method when the target namespace is in the same cluster as the Cequence UAP platform. If the target namespace is in a different cluster, use the manual setup method described later in this document.

Run the OpenTelemetry setup script using the client credentials from the previous step.

/opt/cequence/bin/4-setup-opentelemetry.sh <CLIENT_NAME> <CLIENT_SECRET> [TARGET_NAMESPACE]

Parameters

• CLIENT_NAME: The Keycloak client ID that you created (for example, flow-graph).
• CLIENT_SECRET: The client secret that you copied.
• TARGET_NAMESPACE: (Optional) The namespace where the instrumentation should be installed.

Example

/opt/cequence/bin/4-setup-opentelemetry.sh flow-graph "your-client-secret-here" your-namespace

The script performs the following actions.

1. Installs the OpenTelemetry operator if it is not already installed.
2. Uses the provided client credentials to obtain a Bearer token from Cequence UAP platform Auth.
3. Creates the OpenTelemetry Instrumentation resource in the target namespace.
4. Configures services to use the Bearer token for authentication when sending traces.

Manual setup

Use this method if any of the following conditions apply.

• The target namespace is in a different cluster than the Cequence UAP platform.
• You prefer to set up OpenTelemetry instrumentation manually.
• The setup script is not accessible from your environment.

If you set up instrumentation in a different cluster, verify that the OpenTelemetry operator is installed on that cluster first. The Cequence UAP platform setup script does not install the operator on remote clusters.

Image specifications (java, nodejs, python) are not required if the OpenTelemetry auto-instrumentation images are already available in your environment (for example, pulled from a default registry or available in other namespaces). The operator uses default images if you do not specify them.

Get the Bearer token

Obtain an access token from the Cequence UAP platform Auth using the Flow Graph OTLP client credentials.

curl -X POST https://auth.<your-uap-domain>/auth/realms/<namespace>/protocol/openid-connect/token \
  -d 'client_id=flow-graph' \
  -d 'client_secret=<your-client-secret>' \
  -d 'grant_type=client_credentials'

Note the access_token value from the response and store the value securely.

Create the Instrumentation resource

Create an otel-instrumentation.yaml file with the following content, replacing the placeholders.

apiVersion: opentelemetry.io/v1alpha1
kind: Instrumentation
metadata:
  name: instrumentation-uap
spec:
  env:
    - name: OTEL_EXPORTER_OTLP_PROTOCOL
      value: http/protobuf
    - name: OTEL_EXPORTER_OTLP_HEADERS
      value: "Authorization=Bearer <your-access-token>"
  exporter:
    endpoint: https://edge.<your-uap-domain>/otlp/trace
  propagators:
    - tracecontext
    - baggage
  sampler:
    type: parentbased_traceidratio
    argument: "0.1"

Replace the following placeholders.

• <your-access-token>: The access token that you obtained in the previous step.
• <your-uap-domain>: Your Cequence UAP platform domain (for example, uap1.armor.cequence.net).

To specify custom images for use in airgapped environments or to use private registries, add image specifications to the spec section.

spec:
  java:
    image: registry.gitlab.com/cequence/releases/third-party/opentelemetry/autoinstrumentation-java:1.33.6
  nodejs:
    image: registry.gitlab.com/cequence/releases/third-party/opentelemetry/autoinstrumentation-nodejs:0.57.1
  python:
    image: registry.gitlab.com/cequence/releases/third-party/opentelemetry/autoinstrumentation-python:0.51b0
  env:
    # ... rest of configuration

Apply the Instrumentation resource

Apply the instrumentation resource to your target namespace.

kubectl apply -f otel-instrumentation.yaml -n <TARGET_NAMESPACE>

Replace <TARGET_NAMESPACE> with the namespace where your services are running.