Sending OpenTelemetry data to the Instana agent

Enabling the OpenTelemetry data ingestion

By default, the OpenTelemetry data ingestion in the Instana host agent is activated.

The default changes to activated if the host agent is on version 1.1.726 or higher. Previously, the default was deactivated.

To enable the reception of the OpenTelemetry data in the host agent, add the following snippet to the configuration.yaml file of the host agent:

com.instana.plugin.opentelemetry:
  grpc:
    enabled: true
  http:
    enabled: true

After the OpenTelemetry data ingestion is activated, the host agent activates a collector for OpenTelemetry's default OTLP exporter on the ports 4317 for gRPC and 4318 for HTTP or HTTPS connections.

Sending OpenTelemetry data in OTLP format to the Instana agent in Kubernetes

The Instana agent service, which is provided on Kubernetes through the Instana agent Helm Chart, is useful when the service is used with the OpenTelemetry support. The Instana agent service helps ensure that the data is forwarded to the Instana agent, which runs on the same Kubernetes node. The Instana agent service is a Kubernetes service that can be used as the domain name of the pod where the Instana agent runs.

To enable the default OTLP ports 4317 for gRPC and 4318 for HTTP or HTTPS connections, complete the following steps:

1. If you use install the Instana host agent by using the Helm Chart, set the following Helm flags to true:

• --set opentelemetry.enabled=true

• --set opentelemetry.grpc.enabled=true

• --set opentelemetry.http.enabled=true.

  The following sample command installs the Instana agent, which is enabled with OpenTelemetry into a Kubernetes cluster:

  helm install instana-agent \
    --repo https://agents.instana.io/helm \
    --namespace instana-agent \
    --create-namespace \
    --set agent.key=xxxx \
    --set agent.downloadKey=xxxx \
    --set agent.endpointHost=xxxx \
    --set agent.endpointPort=xxxx \
    --set cluster.name=xxxx \
    --set zone.name=xxxx \
    --set opentelemetry.enabled=true \
    --set opentelemetry.grpc.enabled=true \
    --set opentelemetry.http.enabled=true \
    instana-agent
  

  If the Instana host agent is installed by using an Operator, you can enable the OTLP through the Instana agent custom resource. For more information, see Installing the host agent on Kubernetes.

  By default, the Instana agent is installed into the instana-agent namespace of a Kubernetes or Red Hat OpenShift cluster. A Kubernetes service that is named instana-agent is used to access the Instana agent. You can find the ports 4317 for OTLP/gRPC and 4318 for OTLP/HTTP.

  # kubectl get service -n instana-agent
  NAME                     TYPE        CLUSTER-IP      EXTERNAL-IP   PORT(S)                                 AGE
  instana-agent            ClusterIP   172.30.53.248   <none>        42699/TCP,55680/TCP,4317/TCP,4318/TCP   23d
  instana-agent-headless   ClusterIP   None            <none>        42699/TCP,55680/TCP,4317/TCP,4318/TCP   23d
  

2. To access an OTLP endpoint of an Instana agent in a Kubernetes or Red Hat OpenShift cluster, you can use the Kubernetes service. For example, you can send OpenTelemetry data to instana-agent.instana-agent:4317 as the OTLP/gRPC endpoint. Or you can send OpenTelemetry data to instana-agent.instana-agent:4318 as the OTLP/HTTP endpoint.

   In the following configuration example, the OpenTelemetry collector is used to connect to the local Instana host agent with both OTLP/gRPC and OTLP/HTTP protocols:

   exporters:
     otlp:
       endpoint: 'instana-agent.instana-agent:4317'
       tls:
         insecure: true
     otlphttp:
       endpoint: 'instana-agent.instana-agent:4318'
       tls:
         insecure: true
   

   Another way to access the endpoint of the Instana agent is to use the host IP address directly. See the following example about how to get the host IP address in a Kubernetes or Red Hat OpenShift cluster and build the full domain name of the endpoint of OTLP/gRPC, which is TRACER_EXPORTER_OTLP_ENDPOINT:

   env:
     - name: INSTANA_AGENT_HOST
       valueFrom:
         fieldRef:
           apiVersion: v1
           fieldPath: status.hostIP
     - name: TRACER_EXPORTER_OTLP_ENDPOINT
       value: "http://$(INSTANA_AGENT_HOST):4317"
   

Enabling TLS encryption for OpenTelemetry ingestion

You can enable TLS encryption on the host agent so that all the data that is sent to the OpenTelemetry ingestion endpoint is TLS-encrypted.

For more information, see Enabling TLS Encryption.

Avoiding compatibility issues caused by multiple tracers

Multiple tracers working for the same app might cause conflicts or duplicated data. For example, the Instana agent does not automatically instrument Java virtual machines (JVMs) that have a number of Java agents running.