Sending OpenTelemetry data to the Instana agent

The Instana agent can directly receive OpenTelemetry traces, metrics, and logs in OTLP format. Then, the Instana agent forwards the data to the Instana backend. Complete the following configurations:

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.

By default, the Instana agent is configured to listen on the localhost IP address (127.0.0.1). The following snippet shows a typical example configuration for the OpenTelemetry Collector to forward telemetry data to a local Instana host agent by using the OTLP/gRPC protocol.

exporters:
  otlp:
    endpoint: localhost:4317
    tls:
      insecure: true
...
service:
  pipelines:
    traces:
      receivers: [...]
      processors: [...]
      exporters: [..., otlp]
    metrics:
      receivers: [...]
      processors: [...]
      exporters: [..., otlp]
    logs:
      receivers: [...]
      processors: [...]
      exporters: [..., otlp]

Notes:

If tls is enabled (tls.insecure: false), prefix the endpoint value with https:// (for example, https://).
If tls is disabled (tls.insecure: true), you can prefix the endpoint value with http://. However, you are suggested to not use http:// in this configuration.
If the Instana SaaS server uses the https:// scheme, then the client transport security is enabled and overrides the tls.insecure: true configuration. For more information, see OTLP gRPC Exporter .
If you do not specify any value for tls.insecure, then tls is enabled by default.

The following example shows a typical configuration of the OpenTelemetry Collector for forwarding Telemetry data to a local Instana host agent with the OTLP/HTTP protocol.

exporters:
  otlphttp:
    endpoint: http://localhost:4318
...
service:
  pipelines:
    traces:
      receivers: [...]
      processors: [...]
      exporters: [..., otlphttp]
    metrics:
      receivers: [...]
      processors: [...]
      exporters: [..., otlphttp]
    logs:
      receivers: [...]
      processors: [...]
      exporters: [..., otlphttp]

If tls is disabled (tls.insecure: true), prefix the endpoint value with http://. If tls is enabled (tls.insecure: false), prefix the endpointvalue withhttps://`.

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.

If you install the Instana host agent by using the Helm Chart or Operator, the OpenTelemetry data ingestion in the Instana host agent is activated by default.

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
```
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 http://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: http://instana-agent.instana-agent:4318
```
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.