Enable OpenTelemetry

This topic describes how to enable OpenTelemetry for F5 NGINX Ingress Controller using the native NGINX module.

Before you begin

To complete this guide, you need the following pre-requisites:

Load the OpenTelemetry module

To enable OpenTelemetry, you must first load the module by adding the otel-exporter-endpoint ConfigMap key, which takes an endpoint argument.

The following is an example of a OpenTelemetry collector running in your cluster as the target for exporting data:

otel-exporter-endpoint: "http://otel-collector.default.svc.cluster.local:4317"

A complete ConfigMap example with all OpenTelemetry options could look as follows:

kind: ConfigMap
apiVersion: v1
metadata:
  name: nginx-config
  namespace: nginx-ingress
data:
  otel-exporter-endpoint: "otel.example.com:4317"
  otel-service-name: "nginx-ingress-controller:nginx"
  otel-exporter-header-name: "x-otel-header"
  otel-exporter-header-value: "otel-header-value"
  # otel-trace-in-http: "true" # Uncomment to enable tracing at the HTTP level

Enable OpenTelemetry

Once you have loaded the module, you can now enable OpenTelemetry.

You can configure it globally for all resources, or on a per resource basis.

Global

To enable OpenTelemetry for all resources, set the otel-trace-in-http ConfigMap key to true:

otel-trace-in-http: "true"

Per resource

You can configure OpenTelemetry on a per resource basis in NGINX Ingress Controller.

For this functionality, you must enable snippets with the -enable-snippets command-line argument.

Based on the state of global configuration, you can selectively enable or disable metrics for each resource.

Enable a specific resource or path

With OpenTelemetry disabled globally, you can enable it for a specific resource using the server snippet annotation:

nginx.org/server-snippets: |
    otel_trace on;

You can enable it for specific paths using Mergeable Ingress resources.

Use the server snippet annotation for the paths of a specific Minion Ingress resource:

nginx.org/location-snippets: |
    otel_trace on;

Disable a specific resource or path

With OpenTelemetry enabled globally, you can disable it for a specific resource using the server snippet annotation:

nginx.org/server-snippets: |
   otel_trace off;

You can disable it for specific paths using Mergeable Ingress resources.

Use the server snippet annotation for the paths of a specific Minion Ingress resource:

nginx.org/location-snippets: |
    otel_trace off;

Customize OpenTelemetry

You cannot modify the additional directives in the otel_exporter block using snippets.

You can customize OpenTelemetry through the supported OpenTelemetry module directives.

Use the location-snippets ConfigMap keys or annotations to insert those directives into the generated NGINX configuration.