Sending OpenTelemetry data to the Instana backend

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
  

  The https:// value that is added in otlp. endpoint indicates that a secure connection is used. If tls is not set, it is enabled by default. For more information, see OtlpExporter Setting.

• 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. Alternatively, you can set x-instana-host as an environment variable. Instana uses the host.id attribute to uniquely identify a host and link OpenTelemetry entities to the correct host. You can provide the host.id in two ways:

• By using OpenTelemetry SDK (suggested for non-containerized systems)

  OpenTelemetry has a standard semantic convention for host.id. Most OpenTelemetry SDKs support collecting the host.id resource attribute on non-containerized systems. When you provide host.id through an OpenTelemetry SDK, Instana can seamlessly link the OpenTelemetry entity to the corresponding host in Instana infrastructure monitoring.

• By retrieving host.id from the Instana UI

  To find the host.id in the Instana UI, go to Analyze Infrastructure > Host. Select the required host from the list to view its details. Under System, you can find Host ID. If you manually set this host.id in your OpenTelemetry resource attributes, Instana links the OpenTelemetry entity to the corresponding host in Instana infrastructure monitoring.

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 // or use ${host.name} if set in the configuration files processors.resource.attributes or in the OpenTelemetry SDK

The `https://` value that is added in `otlp. endpoint` indicates that a secure connection is used. If tls is not set, it is enabled by default. For more information, see [OtlpExporter Setting](https://github.com/open-telemetry/opentelemetry-collector/blob/main/exporter/otlpexporter/README.md). {: note}

• 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 name with value: ${host.name}, which is the name of the host that runs the OpenTelemetry Collector. The host.name can be found in configuration files processors.resource.attributes or in the OpenTelemetry SDK. If the host.name is not set, you can set the host name from your environment variables, such as HOSTNAME or HOST, or you can set it manually.
• 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.

   • For more information about DNS configuration on Instana self-hosted Standard Edition, see single-node cluster DNS Settings and multi-node cluster DNS Settings.
   • For more information about DNS configuration on Instana self-hosted Custom Edition on the Kubernetes platform, see Setting up load balancers and DNS.
   • For more information about configuring Instana self-hosted Custom Edition on the Openshift platform, see Setting up load balancers and DNS - Instana backend on openshift.

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

   • OTLP exporter with certification verification:

     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: https://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 // or use ${host.name} if set in the configuration files processors.resource.attributes or in the OpenTelemetry SDK
        

   • OTLP exporter without certification verification:

     exporters:
        otlp:
          endpoint: https://otlp-grpc.<base_domain>:443
          tls:
            insecure: false
            insecure_skip_verify: true
          headers:
            x-instana-key: xxxxxx
            x-instana-host: xxxxxx // or use ${host.name} if set in the configuration files processors.resource.attributes or in the OpenTelemetry SDK
     

Forwarding Telemetry data to the Instana backend with the OpenTelemetry Collector

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

1. Identify your Instana deployment region. The endpoint for the Instana backend varies based on the deployment region. To find the Instana region that is dedicated to your environment, on the Instana UI, go to the navigation menu, and then click More > About Instana. The Instana dialog is displayed. You can see the Instana deployment region in the dialog.

   Each Instana SaaS environment is associated with a specific region name, such as blue, red, green, orange, or coral. For detailed information about the endpoint of the Instana backend otlp-acceptor, see Endpoints of Instana backend otlp-acceptor.

2. Configure an OTLP/gRPC or OTLP/HTTP connection to the Instana backend. For example, if you are using the Instana blue environment, you can configure an OTLP/gRPC or OTLP/HTTP connection to the Instana backend by using the following configuration:

   • OTLP/gRPC

     exporters:
       otlp:
         endpoint: otlp-blue-saas.instana.io:4317
         headers:
           x-instana-key: xxxx
     ...
     service:
       pipelines:
         traces:
           receivers: [...]
           processors: [...]
           exporters: [..., otlp]
         metrics:
           receivers: [...]
           processors: [...]
           exporters: [..., otlp]
         logs:
           receivers: [...]
           processors: [...]
           exporters: [..., otlp]
     

     Set the x-instana-key field with the agent key of the Instana agent for targeting the Instana backend.

   • OTLP/HTTP

     exporters:
       otlphttp:
         endpoint: https://otlp-blue-saas.instana.io:4318
         headers:
           x-instana-key: xxxx
     ...
     service:
       pipelines:
         traces:
           receivers: [...]
           processors: [...]
           exporters: [..., otlphttp]
         metrics:
           receivers: [...]
           processors: [...]
           exporters: [..., otlphttp]
         logs:
           receivers: [...]
           processors: [...]
           exporters: [..., otlphttp]
     

exporters:
  otlp:
    endpoint: otlp-blue-saas.instana.io:4317
    headers:
      x-instana-key: xxxxxxx
      x-instana-host: xxxx // or use ${host.name} if set in the configuration files processors.resource.attributes or in the OpenTelemetry SDK

processors:
  resource:
    attributes:
    - key: host.name
      action: upsert
      value: "myhost1.ibm.com"

otel-contrib --config configuration.yaml

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.

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