Sending OpenTelemetry data to the Instana backend

Telemetry data can be sent in OTLP format directly from applications or systems to the Instana backend. Complete the following configurations:

Prerequisites

  • The special endpoints of the backend otlp-acceptor component are used when OpenTelemetry data is sent.

    In the following configuration example, the OpenTelemetry collector is used to connect to the Instana backend otlp-acceptor component:

    exporters:
  otlp:
    endpoint: INSTANA_OTLP_GRPC_BACKEND:4317
    headers:
      x-instana-key: xxxxxxx

  • You must set the required Instana agent key for validation. Set the x-instana-key field with the agent key of the Instana for targeting the Instana backend.

Creating the required resource attribute or environment variable

The Instana backend requires the host.id, faas.id, or device.id resource attribute, or you can also set x-instana-host as an environment variable.

If the OpenTelemetry Collector is deployed in a Daemonset mode, the OpenTelemetry Collector is located in the same host of the applications that send out OpenTelemetry data. You can also set the x-instana-host header by using the OTLP exporter.

exporters:
  otlp:
    endpoint: INSTANA_OTLP_GRPC_BACKEND:4317
    headers:
      x-instana-key: xxxxxxx
      x-instana-host: xxxx

Notes:

  • Set the x-instana-key field with the agent key of the Instana agent for targeting the Instana backend.
  • Set the x-instana-host field with the host ID if no host.id, faas.id, or device.id resource attribute is defined in your application or system.
  • Set the endpoint field with the correct domain name of the otlp-acceptor component of the Instana backend.
  • Instana uses OTLP standard port numbers, such as 4317 for OTLP/gRPC and 4318 for OTLP/HTTP. Port 443 is also supported for OTLP/HTTP.

Configuring Self-Hosted Instana

On Instana self-hosted, port 443 is used for OTLP/gRPC and OTLP/HTTP protocols. The following domain names are used for the protocols:

otlp-grpc.<base_domain> for OTLP/gRPC otlp-http.<base_domain> for OTLP/HTTP

To send the OpenTelemetry data to the Instana backend, complete the following steps:

  1. Make sure the two DNS entries otlp-http.<base_domain> and otlp-grpc.<basedomain> are created for the otlp-acceptor component in your Instana backend.

  2. Configure the OTLP exporter to use with OpenTelemetry collector and complete one of the following steps:

    • OTLP exporter with Transport Layer Security (TLS):

      1. Get CA file from self-hosted instana

        • For self-hosted standard edition:
          kubectl get secret instana-tls -n instana-core -o jsonpath='{.data.ca\.crt}'|base64 -d > ca.crt
        • For self-hosted custom edition which certificate is generated by openssl command:
          kubectl get secret instana-tls -n instana-core -o jsonpath='{.data.tls\.crt}'|base64 -d > tls.crt

      2. Copy ca.crt to the location of the OpenTelemetry collector environment:

        exporters:
  otlp:
    endpoint: otlp-grpc.<base_domain>:443
  tls:
    insecure: false
    ca_file: <path_to_cert_file>/<cert_file_name>
  headers:
    x-instana-key: xxxxxx
    x-instana-host: xxxxxx

    • OTLP exporter without TLS:

      exporters:
   otlp:
     endpoint: otlp-grpc.<base_domain>:443
   tls:
     insecure: false
     insecure_skip_verify: true
   headers:
     x-instana-key: xxxxxx
     x-instana-host: xxxxxx

Endpoints of the Instana backend otlp-acceptor

In the following table, you can see the domain names of the Instana backend otlp-acceptor for different Instana SaaS environments. For more information about the Instana SaaS environment, see Integrating with OpenTelemetry by using the OpenTelemetry Collector.

Instana SaaS environment Domain name of otlp-accepter
blue otlp-blue-saas.instana.io
red otlp-red-saas.instana.io
green otlp-green-saas.instana.io
orange otlp-orange-saas.instana.io
coral otlp-coral-saas.instana.io

All endpoints of the Instana backend otlp-acceptor in SaaS environments are TLS-enabled.